크롬 개발자도구 375px 뷰포트로 홈페이지를 열면, 다크 배경 히어로 섹션이 뷰포트 폭을 다 못 채우고 오른쪽에 흰 여백이 남았다 /projects 페이지도 동일한 세로선에서 함께 잘려서, 개별 섹션 문제가 아니라 더 상위 구조의 문제라는 걸 시사했다 overflow-x-hidden을 body에 걸어도 증상이 사라지지 않았다 — 넘치는 걸 숨기는 처방이라, 애초에 뭔가가 뷰포트보다 넓게 그려지는 근본 원인은 그대로 남아 있었다 배포 후에는 로컬에서 안 보이던 증상이 또 나타났다. 실제 프로덕션 데이터에만 존재하는 콘텐츠(들여쓰기 코드블록)가 dev DB에는 없어서, 로컬 테스트로는 재현 자체가 안 됐던 것
세 가지 원인을 각각 다른 층위에서 잡았다.
프로젝트 개요
이 사이트(jeysbuildlog.com)를 모바일로 열었더니, 화면이 세로로 정확히 반 잘려 보였다. 왼쪽은 의도한 다크 배경, 오른쪽은 아무것도 칠해지지 않은 흰 여백. 처음엔 CSS 한 군데만 손보면 끝날 줄 알았다. 실제로는 서로 무관한 세 가지 원인이 같은 증상(가로 스크롤로 인한 배경 절단) 뒤에 겹겹이 숨어 있었고, 하나를 고칠 때마다 "이제 끝났다" 싶은 순간 다른 페이지나 다른 데이터에서 똑같은 증상이 다시 튀어나왔다.
세 원인 모두 "당장 보이는 지점만 막는" 대신 "같은 문제가 다시 안 생기는 지점"까지 거슬러 올라가서 고쳤다.
개별 페이지마다 min-w-0을 넣는 대신 공용 레이아웃에 한 번만 넣은 것은, 새 페이지가 추가될 때마다 사람이 이 클래스를 기억해서 넣어야 하는 방식이 결국 언젠가 빠뜨릴 걸 알았기 때문이다. 관리 지점을 하나로 줄이는 게 나은 선택이었다. 마크다운 렌더러 수정도 pre 태그에 안전장치만 씌우는 최소 수정과, 아예 code가 하던 스타일링 책임을 pre로 넘겨 구조 자체를 정리하는 방식 중 후자를 택했다. 이 렌더러가 프로젝트 설명, 로그 본문, 관리자 미리보기까지 전부 재사용되는 단일 컴포넌트였기 때문에, 한 번 제대로 고치면 앞으로 어떤 콘텐츠가 들어와도 같은 버그가 재발하지 않는다. 배포 환경에서만 재현된 문제를 로컬에서 억지로 재현하려 하지 않고, 실제 프로덕션 데이터를 그대로 로컬에 임시 주입해서 검증한 뒤 원상복구하는 방식을 썼다. dev/prod DB 분리라는 원칙은 건강한 구조이고, 그 원칙 때문에 발견이 늦어졌다고 해서 원칙을 깨는 게 아니라 검증 방법을 그에 맞게 조정하는 쪽을 선택했다.
이번에 정리한 패턴은 다른 도메인에도 그대로 적용 가능하다.
flex 자식의 min-width: auto 함정은 이 프로젝트뿐 아니라 flex 레이아웃을 쓰는 어떤 웹 서비스에서도 반복될 수 있는 문제다. "텍스트를 자르는 CSS(truncate)를 걸었는데도 안 잘린다"는 증상이 보이면, 부모 체인 전체에서 flex 컨테이너를 의심하고 min-w-0을 확인하는 게 표준 진단 절차가 될 수 있다. 로컬-프로덕션 데이터 불일치로 인한 재현 실패는 dev/prod DB를 분리하는 모든 프로젝트가 겪는 구조적 리스크다. "로컬에서 통과했으니 안전하다"고 단정하지 않고, 실제 프로덕션 데이터의 극단적 케이스(긴 텍스트, 특수 마크다운 문법 등)를 로컬에 재현해보는 습관이 재발 방지에 직접적으로 도움이 된다. 증상이 같아 보여도 원인이 하나라는 보장은 없다는 게 이번 트러블슈팅 전체를 관통하는 교훈이다. 첫 번째 원인을 고치고 넘어갔다면 두 번째, 세 번째 원인은 다음 배포 때 또 "버그 재발"로 보고됐을 것이다. 매번 수정 후 여러 페이지·여러 데이터 조합으로 재검증하는 절차 자체가, 코드 한 줄보다 더 재사용 가능한 자산이었다.
관련 프로젝트
프로젝트 개요 기획자(PM)로서 AI를 활용한 업무 자동화(AX) 사례를 문서화하는 개인 포트폴리오 사이트입니다. 국내 기업의 AX 기획자/AI PM 직군으로의 커리어 전환을 목표로, 사이트 자체가 채용 지원용 스토리텔링 자료로 실사용되고 있습니다. 핵심 패턴: 업무 병목 발견 → AI로 워크플로우 재설계 → Before/After·근거·재현 가능성 문서화 전체 서사는 '실행하지 않은 아이디어 나열'이 아니라, 하나의 검증된 자동화 패턴과 도메인별 확장 블루프린트를 갖춘 재사용 가능한 엔진을 보유하는 방향으로 수렴하고 있습니다. 기술 스택 Next.js 16, Tailwind CSS v4, TypeScript Supabase (개발/운영 환경 분리), Vercel, Resend Claude API 기반 기술 자문 및 프롬프트 설계 보안 아키텍처 관리자 CRUD는 세션 기반 인증과 RLS(Row Level Security)로 보호 공개 읽기 전용 경로는 별도의 익명 클라이언트로 분리 서비스 롤 키는 애플리케이션 코드에서 완전히 배제 권한 검증은 마이그레이션 파일 및 대시보드 검토를 통해서만 진행 작업 방식 (에이전틱 IDE 협업 워크플로우) AI 에이전트 기반 IDE가 파일/버전관리 작업을 담당하고, LLM은 기술 자문 및 프롬프트 작성 역할을 수행하는 협업 구조를 운영합니다. AI 자문 → 에이전트용 프롬프트 작성 → 실행자가 붙여넣기 → 계획 확인 → 자문 검토 → 실행 승인 → 로그 검토 → 직접 클릭 테스트 → 명시적 지시 시에만 커밋 통제 규칙 실행 전 계획 검토 필수 요약 보고가 아닌 직접 클릭 테스트로 검증 개발 환경 우선 적용 후 명시적 승인 하에 운영 환경 반영 커밋은 명시적 지시가 있을 때만 수행 DB 자격증명 직접 연결 및 범위 외 삭제 금지 브랜치 전략: 개발 브랜치에서 작업 후 운영 브랜치는 배포 전용으로 직접 커밋 금지, 병합 전 변경 범위 검증 현재 진행 상황 고객사 미팅 브리핑 자동화 사례: 1단계 완료, 개발/운영 환경 배포 및 실데이터 테스트 완료 범위 변경 감지 자동화 사례: 상태 확인 진행 중 리스크 조기 경보 자동화 사례: 운영 환경 배포 완료 보안 사고 관련 포스트: 'AI 리스크 거버넌스 사례'로 재구성 예정 AI 활용 관련 콘텐츠 시리즈 초안 작성 완료, 게시 미확정 핵심 학습 원칙 보고가 아닌 검증: 버그·보안 이슈는 항상 직접 로그/브라우저 검토를 통해서만 발견되며, 에이전트의 자체 결과 요약을 그대로 신뢰하지 않음 보안 사고의 콘텐츠화: 실제 발생한 권한 관련 이슈 사례를 케이스 스터디로 재구성하여 콘텐츠화 커밋 의미 분리: 기능 단위/변경 유형별로 항상 분리 커밋 자동화하지 않는 것도 스토리: 저사용 빈도 기능을 의도적으로 고도화하지 않은 결정 자체를 AX 스토리텔링 소재로 활용