개발 계획 스킬 — 스킬 프로젝트 소개

빌드는 통과했는데 모바일에서 글이 밀렸다

2026년 8월 30일, 이 사이트의 일부 글이 모바일에서 가로로 밀린다는 제보를 받았습니다. 정적 빌드는 통과했지만 작은 화면에서는 표와 긴 코드가 본문 밖으로 튀어나왔습니다. 제목과 문장까지 옆으로 움직이니 글을 읽으려면 화면을 계속 좌우로 옮겨야 했습니다.

일반 게시글 46편과 인사이트 7편, 총 53편을 화면 폭별로 확인했습니다. 320px에서는 29편, 375px에서는 19편, 390px에서는 17편에서 문서 전체 폭이 넘쳤습니다. 390px 화면에서는 최대 161px까지 더 넓어졌습니다. 일부 글의 문제가 공통 레이아웃에 걸려 있었던 것입니다.

화면을 고친 뒤에는 같은 문제를 다음 작업에서 놓치지 않을 기준이 필요했습니다. 새 상세 페이지를 만들 때도 빌드 통과만 확인하면 모바일에서 다시 글이 밀릴 수 있습니다. 그래서 원인과 확인 방법을 개발 교훈으로 남기고, 후속 계획에서 다시 찾아 쓰도록 연결했습니다.

코드에 스크롤을 줬는데 부모가 먼저 넓어졌다

표와 코드 블록에는 이미 overflow-x:auto가 있었습니다. 긴 내용은 그 안에서 스크롤될 것 같지만, 바깥 Grid 열이 1fr이고 항목의 최소 폭이 기본값 auto인 상태였습니다. 자식의 긴 내용 때문에 부모가 먼저 넓어지면 내부 스크롤만으로는 문서 폭을 지킬 수 없습니다.

저는 글마다 표를 줄이는 대신 공통 레이아웃을 수정했습니다. Grid 열은 minmax(0,1fr)로 바꾸고, Grid 항목과 본문에 min-width:0을 적용했습니다. 코드 블록은 최대 폭을 제한해 자기 영역 안에서 스크롤하도록 두고, 긴 링크와 인라인 코드는 줄바꿈하도록 했습니다.

표의 모든 열을 억지로 좁히는 방법은 읽어야 할 정보를 훼손할 수 있습니다. 문서 전체 폭은 화면 안에 두되, 넓은 표와 코드는 그 영역 안에서 읽을 수 있게 하는 쪽을 택했습니다. 수정 뒤에는 53편을 모바일 3개 폭에서 다시 확인한 159건과 데스크톱 1440px의 53편 모두에서 문서 전체 넘침이 없어졌습니다.

“모바일을 확인하자”보다 구체적으로 남기기

교훈을 한 줄로 줄이면 “모바일 화면을 확인하자”입니다. 하지만 그 문장만으로는 다음 작업자가 어떤 코드를 살피고 어디까지 검사해야 하는지 알기 어렵습니다. 저는 적용 대상, 관측한 증상, 원인, 예방 방법, 확인한 화면 폭을 나눠 남겼습니다.

이번 교훈의 적용 대상은 표와 코드를 포함한 Grid 상세 화면입니다. 의도적으로 가로 스크롤하는 데이터 그리드나 편집기까지 같은 기준으로 막지는 않습니다. 화면 전체가 넘친 것과 한 영역 안에서 넓은 내용을 탐색하는 것은 구분해야 합니다.

스킬에서도 변경할 파일과 작업 범위로 관련 교훈을 찾도록 했습니다. 찾은 항목은 adopted, not-applicable, waived로 구분합니다. 채택한다면 예방 조치를 어느 작업에 넣고 어떤 테스트로 확인할지 함께 정합니다. 교훈이 있다는 사실보다 이번 변경에 어떻게 적용하는지가 계획에 남도록 한 것입니다.

새 상세 페이지를 만들 때 다시 꺼낸 기준

9월 30일에는 이 사이트에 프로젝트 랩과 AI 스킬 랩을 추가했습니다. 두 작업 모두 새로운 상세 페이지를 만드는 일이어서, 8월의 모바일 교훈을 개발 계획에서 채택했습니다.

프로젝트 랩 계획에는 Grid 축소 조건과 긴 URL 줄바꿈, 표·코드의 내부 스크롤을 스타일 작업에 넣었습니다. 상세 페이지 전체를 320px와 390px에서 확인하는 항목도 연결했습니다. 스킬 랩 역시 같은 교훈을 본문 스타일과 전체 상세 화면 검수에 반영했습니다.

“긴 콘텐츠를 넣어도 문서 전체 폭은 늘어나지 않아야 한다”는 조건을 작업과 검수 양쪽에 남겼습니다. CSS 값만 복사하는 데서 그치지 않고, 새 페이지에서도 무엇을 확인해야 하는지 함께 정한 것입니다.

계획 요청에 완료 조건까지 넣기

상세 페이지를 추가한다면 다음처럼 요청할 수 있습니다. 아래는 같은 상황에 적용할 수 있는 요청 예시입니다.

표와 코드가 포함된 상세 페이지를 추가하는 개발 계획을 만들어줘.
범위는 해당 상세 템플릿과 본문 스타일로 제한해.
관련 모바일 오버플로 교훈을 찾아 적용 여부와 이유를 기록해줘.
빌드 검사와 320/375/390px 실제 화면 확인을 별도 테스트로 넣어줘.

바꿀 파일과 목표를 먼저 정합니다. 관련 없는 전체 디자인 개편은 제외 범위에 둡니다.
이전 교훈의 적용 조건을 읽고 이번 화면에도 맞는지 판단합니다. 예외가 있다면 그 이유를 적습니다.
예방 조치를 구현 항목에, 확인 방법을 자체 테스트에 넣습니다. 결과를 얻은 뒤 완료 체크를 합니다.

“반응형 대응 완료”보다 “320/375/390px에서 문서 폭이 화면 폭을 넘지 않고, 긴 코드는 코드 영역 안에서 스크롤된다”가 확인하기 쉽습니다. 빌드와 화면 검수는 각각 통과해야 하므로 체크 항목도 나눕니다. 계획서가 길어지는 것보다 끝났다고 판단할 조건이 분명해지는 것이 중요합니다.

모바일 수정과 계획 적용 기록

2026-08-30 검수 기록(./docs/dev-lessons/DL-20260830T075743Z-53c3e34f.md)에서는 표·코드가 있는 글에서 문서 전체가 좌우로 늘어나는 문제가 확인됐습니다. 단일 열 Grid의 최소 폭을 줄일 수 있도록 minmax(0, 1fr)과 min-width: 0을 적용하고, 긴 URL은 줄바꿈하며 표·코드는 영역 안에서 스크롤하도록 수정했습니다. 당시 기록의 53편 × 3개 모바일 폭 검사 159건에서는 문서 전체 넘침이 없었습니다. 이는 그때의 검수 결과입니다.

이후 프로젝트 랩 계획(./dev-plan/implement_20260930_201751.md)과 스킬 랩 계획(./dev-plan/implement_20260930_205532.md)에 같은 축소 조건과 실제 모바일 검수를 완료 기준으로 넣었습니다. 소개 카드의 빌드 검사와 실제 화면 검수를 나누고, 320/390px에서 제목·코드·표 때문에 문서 전체가 늘어나는지 확인하도록 했습니다. 이 기록에서 재사용할 부분은 특정 CSS 값만이 아니라 문제를 발견한 조건과 다음 작업의 완료 기준입니다.

다음 작업을 이어갈 수 있는 계획서

스킬의 기본 산출물은 dev-plan/implement_YYYYMMDD_HHMMSS.md입니다. 새 목표는 새 파일에 적고, 같은 목표의 진행 상태는 같은 파일에서 갱신합니다. 목적과 범위, 제외할 작업, 단계별 검수 결과가 한곳에 있어야 작업을 다시 이어갈 때도 판단의 맥락을 찾을 수 있습니다.

관련 교훈은 이번 범위를 판단하는 참고 자료로 사용합니다. 검색됐다는 이유만으로 모든 교훈을 채택하거나 작업을 막지는 않습니다. 일반 계획을 만드는 것과 병렬 실행을 구성하는 것도 구분해, 계획 요청의 범위가 실제 작업 방식보다 넓어지지 않도록 했습니다.

이 사례에서는 CSS 수정과 화면 검수 조건을 함께 다음 계획으로 옮겼습니다. 제가 계획 문서에 남기려 한 것도 바꿀 코드와 그 수정을 확인할 방법입니다.