AI가 만든 모바일 화면 깨짐, 수정 범위 좁히는 법

AI 코딩 도구가 만든 화면은 노트북에서는 괜찮은데 휴대폰 폭으로 줄이면 카드가 오른쪽으로 밀리고 버튼 글자가 찌그러질 수 있다. 이때 반응형으로 고쳐줘라고만 쓰면 AI가 원인을 찾기보다 레이아웃 전체를 다시 짤 수 있다. 독자가 먼저 해야 할 일은 CSS 속성을 추측하는 것이 아니다.

문제가 보이는 화면 폭 하나와 깨진 요소 하나를 고정해야 한다. 그다음 viewport 설정, 고정 폭, flex·grid, 긴 문자열 중 어느 갈래인지 나누고 해당 파일의 최소 변경만 요청한다. 이 순서가 멀쩡한 데스크톱 화면을 지키면서 모바일 넘침을 줄이는 가장 짧은 경로다.

데스크톱에서는 맞지만 휴대폰 폭에서는 가격 카드가 오른쪽으로 넘치는 비교 화면

같은 폭과 같은 요소에서 먼저 재현한다

Device Mode로 모바일 기기 시뮬레이션하기 (Chrome Developers)는 브라우저에서 모바일 뷰포트와 일부 기기 조건을 흉내 낼 수 있다고 설명한다. 다만 실제 휴대폰에서 코드를 실행하는 것은 아니므로 첫 진단 도구로 쓰고, 공개 전에는 실제 기기에서도 확인해야 한다.

DevTools의 기기 도구 모음을 열고 문제가 보이는 폭에서 멈춘다. 390px은 재현 예시일 뿐 정답인 모바일 기준점은 아니다. 아래 네 줄을 먼저 적으면 AI가 추측해야 할 범위가 줄어든다.

확인한 화면 폭: 390px
깨진 위치: 가격 카드가 있는 섹션
증상: 세 번째 카드가 오른쪽으로 밀려 가로 스크롤이 생김
기대 동작: 작은 화면에서는 카드가 한 줄에 하나씩 쌓임

스크린샷만 보내는 것보다 요소 이름과 기대 동작을 함께 적는 편이 낫다. 화면에 보이는 결과와 코드에서 찾을 위치가 연결되기 때문이다. 이 네 줄을 채우기 전에는 전체 반응형 재작성을 요청하지 않는다.

원인은 네 갈래로 나누면 수정 파일이 보인다

모바일 넘침을 한 속성으로 고칠 수는 없다. 아래 네 갈래를 순서대로 확인하면 HTML 설정 문제인지, 컨테이너 폭 문제인지, 자식 요소 문제인지 구분할 수 있다.

React·Vite와 Next.js의 viewport 기본값을 구분한다

viewport 메타 값 (MDN)은 width=device-width가 레이아웃 viewport를 기기의 CSS 픽셀 폭에 맞추는 값이라고 설명한다. 일반 HTML이나 React·Vite 앱은 index.html의 <head>에서 이 설정을 확인한다.

현재 Next.js는 다르다. Metadata와 OG 이미지 시작하기 (Next.js)에 따르면 기본 viewport 메타가 자동으로 생성된다. Next.js 앱에서 모바일 화면이 넘친다고 같은 태그부터 중복 추가하지 말고, 브라우저에서 실제 <meta name="viewport">를 확인한 뒤 다음 CSS 갈래로 넘어간다.

고정 폭과 최소 폭을 찾는다

width: 900px, min-width: 640px, Tailwind의 w-[900px]처럼 화면보다 큰 값을 찾는다. 부모가 max-width: 100%여도 자식의 min-width 때문에 가로 스크롤이 생길 수 있다. AI에게는 해당 선언이 있는 파일과 요소 이름을 함께 보낸다.

flex·grid가 한 줄을 고집하는지 본다

flex-wrap 속성 (MDN)은 기본값 nowrap이 flex 항목을 한 줄에 두어 컨테이너가 넘칠 수 있다고 설명한다. 그렇다고 무조건 flex-wrap: wrap을 붙이지 않는다. 모바일에서 세로로 쌓여야 한다면 flex-direction, grid라면 작은 폭의 열 개수까지 기대 동작과 비교한다.

URL과 코드처럼 끊기지 않는 문자열을 확인한다

overflow-wrap 속성 (MDN)은 끊기지 않는 문자열이 줄 밖으로 나갈 때 브라우저가 줄바꿈을 넣도록 할 수 있다. 카드 폭은 정상인데 긴 URL·이메일·코드만 튀어나온다면 레이아웃 전체가 아니라 텍스트 컨테이너를 고친다.

화면 폭, 깨진 영역, 기대 동작, 최소 수정 네 정보를 묶는 요청 흐름

AI에게는 변경할 파일과 금지 범위를 함께 준다

원인 갈래를 고른 뒤 아래 프롬프트에 실제 정보를 넣는다. 프롬프트의 목적은 AI가 정답을 보장하게 만드는 것이 아니라 변경 범위를 설명하고 검증 가능한 패치를 내게 하는 것이다.

React/Next.js 화면이 데스크톱에서는 맞지만 아래 폭에서 가로로 넘칩니다.

재현 폭: [390px]
깨진 요소: [PricingCard 목록]
증상: [세 번째 카드가 오른쪽으로 밀려 가로 스크롤이 생김]
기대 동작: [작은 화면에서는 카드가 한 줄에 하나씩 쌓임]
관련 파일: [components/Pricing.tsx, styles/pricing.css]

요청:
1. viewport, 고정 width/min-width, flex/grid, 긴 문자열 중 원인 갈래를 먼저 설명해 주세요.
2. 관련 파일 안에서 필요한 최소 변경만 제안해 주세요.
3. 새 패키지, 새 파일, 전역 CSS 변경, 컴포넌트 전체 재작성은 제외해 주세요.
4. 바뀌는 class 또는 CSS 속성과 그 이유를 보여 주세요.
5. 390px, 768px, 기존 데스크톱 폭에서 확인할 결과를 적어 주세요.

AI가 관련 없는 파일까지 고치려 하면 중단하고 다시 좁힌다. 새 패키지·새 파일·전역 CSS가 제안되면 바로 적용하지 않는다. AI가 코드를 저장하기 전 확인하는 체크리스트처럼 변경 파일과 실행 결과를 먼저 확인하면 광범위한 수정이 섞이는 일을 줄일 수 있다.

적용 전후는 작은 폭·중간 폭·기존 폭에서 비교한다

패치를 적용한 뒤에는 같은 증상만 사라졌는지 보지 않는다. 작은 화면, 중간 화면, 기존 데스크톱 화면을 차례로 확인한다.

모바일 레이아웃 수정 전 파일 범위와 고정 폭, 줄바꿈, 버튼, 패키지 변경을 확인하는 체크리스트

깨진 요소와 관련된 파일만 바뀌었는지 본다.
width, max-width, min-width 가운데 무엇이 바뀌었는지 확인한다.
flex·grid 배치와 긴 문자열 줄바꿈이 기대 동작과 맞는지 본다.
버튼·입력창의 글자와 터치 영역이 부모 너비 안에 남는지 본다.
새 패키지나 전역 CSS 변경이 들어오지 않았는지 확인한다.

390px에서 맞아도 768px에서 간격이 과하게 벌어질 수 있다. 기존 데스크톱 폭까지 같아야 최소 수정이라는 약속이 지켜진다. 결과가 다르면 안 돼요 대신 폭별 결과와 바뀐 파일을 다시 전달한다.

변경한 파일: components/Pricing.tsx
390px: 카드가 한 줄에 하나씩 쌓이고 가로 스크롤이 사라짐
768px: 카드 간격이 너무 넓어짐
1440px: 기존 배치와 같음

768px 간격 문제만 최소 변경으로 다시 제안해 주세요.
다른 파일과 전역 CSS는 바꾸지 마세요.

수정 뒤 dev 화면만 보지 말고 프로젝트의 build 명령도 실행한다. import나 class 이름을 잘못 바꿔 빌드가 멈추면 Module not found에서 패키지와 경로를 구분하는 순서로 오류 갈래를 따로 좁힐 수 있다.

오늘 남길 결과물은 수정 범위 메모다

이번 작업의 결과물은 반응형 CSS 지식 전체가 아니다. 같은 문제를 다시 만났을 때 재사용할 일곱 줄이다.

확인한 폭:
깨진 요소:
깨진 증상:
기대 동작:
관련 파일:
수정 금지 범위:
다시 확인할 폭:

지금 화면이 넘친다면 첫 줄에 문제가 보이는 폭을 적고, 두 번째 줄에 DevTools에서 선택한 요소를 적는다. 그 뒤에만 AI에게 최소 변경을 요청한다.

참고 출처

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.

AI가 만든 화면이 모바일에서 넘칠 때, 고칠 범위부터 좁히는 법