AI가 만든 코드가 안 돌아갈 때, 다시 질문할 오류 4칸

AI 코딩 도구가 만든 프로젝트를 실행했는데 터미널이 빨갛게 길어졌다. 이때 고쳐줘만 다시 보내면 AI는 실패한 명령도, 오류가 시작된 파일도 모른 채 추측해야 한다. 필요한 답은 긴 설명이 아니다. 실행 명령, 첫 오류, 관련 파일, 실행 환경 네 칸이다.

Tap to zoom

네 칸을 채운 뒤에는 전체 재작성을 요구하지 않는다. 가장 가능성 높은 원인, 먼저 볼 파일 하나, 최소 수정 범위를 요청한다. 수정안을 받으면 바로 붙이지 않고 변경 파일을 확인한 다음 같은 명령을 다시 실행한다.

고쳐줘 대신 네 칸을 먼저 만든다

오류를 다시 묻기 전에 아래 형식을 복사한다. 모르는 칸은 추측하지 말고 확인하지 못함이라고 적는다.

작업 목적:
[만들거나 고치려는 결과]

실행한 명령:
[예: npm run build]

첫 오류와 앞뒤 맥락:
[구체적인 오류가 처음 나타난 줄부터 위아래 10줄]

관련 파일과 실행 환경:
[파일 경로와 관련 코드]
[프레임워크, Node.js 버전, 패키지 매니저]

요청:
원인 후보를 세 개 이내로 좁혀 주세요.
가장 먼저 확인할 파일 하나와 최소 수정안만 보여 주세요.
새 파일, 새 패키지, 구조 변경이 필요하면 이유를 먼저 설명해 주세요.

이 형식의 목적은 AI를 설득하는 것이 아니라 재현 조건을 한 화면에 모으는 것이다. 오류 문구만 보내면 어떤 명령에서 실패했는지 빠진다. 코드만 보내면 실제 출력이 빠진다. 네 칸은 그 두 공백을 함께 메운다.

첫 오류 줄과 실패한 명령을 함께 잡는다

터미널 마지막의 exit code 1이나 Command failed는 실패 상태를 보여 주지만 원인 문장이라고 단정할 수 없다. Node.js Process 문서(Node.js)는 정상 종료가 보통 상태 코드 0을 쓰고 다른 상황에서 별도 코드를 쓴다고 설명한다. 따라서 종료 코드만 떼어 보내지 말고 그보다 먼저 나온 파일 경로, 줄 번호, 모듈 이름, 오류 메시지를 함께 잡는다.

npm run build가 실패했다면 입력한 명령도 그대로 남긴다. npm-run-script 문서(npm)에 따르면 npm run-script <command>는 package.json의 scripts 객체에 있는 명령을 실행한다. AI에게 npm이 안 된다고 쓰는 대신 build 스크립트를 실행했더니 app/page.tsx에서 이 오류가 났다고 범위를 좁힐 수 있다.

Tap to zoom

복사 순서는 다음과 같다.

1. 방금 입력한 명령을 적는다.
2. 구체적인 오류가 처음 등장한 줄을 찾는다.
3. 그 줄의 위아래 맥락을 함께 복사한다.
4. 파일 경로와 줄 번호를 별도 줄에 남긴다.

관련 파일과 실행 환경을 좁혀 붙인다

처음부터 프로젝트 전체를 붙이지 않는다. 오류에 app/page.tsx, src/components/Form.tsx, lib/api.ts 같은 경로가 나오면 해당 파일의 관련 함수나 컴포넌트부터 붙인다. 호출하는 쪽이 필요하다는 답을 받았을 때만 인접 파일을 추가한다.

타입 오류와 실행 오류도 구분한다. TypeScript noEmit 문서(Microsoft)는 JavaScript, 소스맵, 선언 파일을 출력하지 않으면서 TypeScript를 타입 검사기로 쓸 수 있다고 설명한다. 프로젝트에 typecheck 스크립트가 있다면 먼저 package.json에서 실제 명령을 확인한다. 스크립트가 없는데 이름만 추측해 실행하지 않는다. 여러 타입 오류를 좁혀야 한다면 Next.js 타입 에러의 원인부터 줄이는 순서도 함께 쓸 수 있다.

Next.js에서는 오류가 난 위치도 중요하다. Next.js Error Handling 문서(Vercel)는 처리되지 않은 렌더링 오류가 가장 가까운 오류 경계로 올라가며, 이벤트 핸들러나 비동기 코드의 오류는 같은 방식으로 잡히지 않을 수 있다고 설명한다. 화면에 보이는 오류 컴포넌트만 붙이지 말고 오류가 시작된 이벤트 함수나 서버 작업의 파일 경로도 확인한다.

답변은 적용 전에 변경 범위를 확인한다

AI가 수정안을 내면 코드의 그럴듯함보다 변경 범위를 먼저 본다. 확인할 것은 세 가지다.

Tap to zoom

1. 수정 파일이 오류에 나온 파일과 연결되는가.
2. 오류 한 건에 비해 삭제되거나 바뀌는 코드가 지나치게 많지 않은가.
3. 새 패키지, 환경변수, 권한 변경을 요구하는가.

오류 한 줄을 고치는데 파일 여러 개를 새로 만들거나 패키지를 추가한다면 멈추고 이유를 먼저 묻는다. 아래처럼 범위를 다시 제한한다.

수정 범위가 큽니다.
지금 오류를 재현하는 데 필요한 최소 변경만 다시 제안해 주세요.
새 파일 생성, 패키지 추가, 전체 구조 변경은 보류하고
오류가 난 파일 안에서 먼저 확인할 부분을 보여 주세요.

적용 전후 차이는 git diff 같은 변경 비교로 확인한다. 특히 .env나 토큰처럼 저장소에 들어가면 안 되는 값이 보인다면 수정 적용보다 먼저 제외한다. Git 커밋 전 .env를 push에서 빼는 순서를 따라 변경 목록에서 비밀 파일을 분리할 수 있다.

같은 명령으로 다시 재현하고 비밀값을 지운다

수정 뒤에는 처음 실패한 명령을 다시 실행한다. 아직 안 됩니다만 보내지 말고 변경 파일, 다시 실행한 명령, 새 출력이 같은지 달라졌는지를 적는다.

제안한 수정안을 적용했습니다.
변경한 파일: [파일명]
다시 실행한 명령: [명령어]
결과: [같은 오류 / 다른 오류 / 성공]
새 오류의 첫 줄과 맥락:
[출력 붙이기]

이전 답변의 가정 중 틀렸을 가능성이 있는 부분부터 다시 확인해 주세요.

로그를 AI나 공개 게시판에 붙이기 전에는 API 키, 접근 토큰, 쿠키, 데이터베이스 주소, 사용자 경로를 지운다. 비밀정보 안전 저장 안내(GitHub)는 로그에 비밀값이 남지 않게 하고, 노출된 비밀은 즉시 폐기한 뒤 새 값으로 교체하라고 안내한다. 자동 마스킹이 모든 형태를 보장한다고 가정하지 않는다.

오늘 남길 결과물은 네 줄이면 된다.

실행한 명령:
첫 오류:
관련 파일:
실행 환경:

이 네 줄을 채운 뒤 같은 명령을 한 번 더 실행한다. 성공하면 출력과 변경 파일을 남기고, 실패하면 새 오류 맥락을 이어 붙인다.

참고 출처

• npm run-script 공식 문서: https://docs.npmjs.com/cli/v10/commands/npm-run-script/
• Node.js Process exit codes: https://nodejs.org/api/process.html#exit-codes
• TypeScript noEmit: https://www.typescriptlang.org/tsconfig/noEmit.html
• Next.js Error Handling: https://nextjs.org/docs/app/getting-started/error-handling
• GitHub 비밀정보 안전 저장 안내: https://docs.github.com/en/get-started/learning-to-code/storing-your-secrets-safely

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