AI 코딩 결과를 merge 가능한 상태로 바꾸는 테스트 증거 루틴

AI 코딩 도구가 "수정 완료"라고 말하면 잠깐 안심됩니다. 하지만 터미널에 테스트 출력이 없고, GitHub 체크도 보지 않았다면 아직 merge할 근거가 부족합니다. 이때 바로 push하거나 merge하면 다음 오류가 어디서 시작됐는지 잃기 쉽습니다. AI의 완료 메시지는 결과 보고가 아니라 검증을 시작하라는 신호로 보는 편이 안전합니다.

가장 먼저 할 일은 새 기능을 더 시키는 것이 아닙니다. 바뀐 파일, 실행한 명령, 통과하거나 실패한 출력 세 가지를 남기는 일입니다. developers.openai.com의 OpenAI 프롬프트 엔지니어링 가이드는 모델에게 명확한 지시와 필요한 맥락을 주는 방식을 강조합니다. AI 코딩에서도 같습니다. "다시 확인해줘"보다 "이 명령을 실행했고, 이 로그가 나왔고, 이 파일만 고쳐라"가 더 좁고 안전한 요청입니다.

이 글은 테스트를 완벽하게 설계하는 글이 아닙니다. AI가 고친 코드를 merge하기 전에 초보자가 5분 안에 만들 수 있는 최소 증거를 정리합니다. 이미 AI가 파일을 너무 넓게 바꾼 상태라면 먼저 AI가 파일을 너무 많이 고칠 때 수정 범위를 잠그는 방법을 보고 범위부터 줄입니다. push 직전 보안 파일이 보인다면 Git 커밋 전 .env 노출을 확인하는 순서를 먼저 처리합니다.

완료 메시지보다 변경 범위를 먼저 봅니다

AI가 고친 코드가 작을수록 검증도 쉬워집니다. 반대로 버튼 문구 하나를 요청했는데 설정 파일, 라우터, 의존성, 테스트 파일까지 같이 바뀌었다면 "완료"라는 말보다 변경 범위가 더 중요합니다.

터미널에서 먼저 확인할 것은 파일 목록입니다.

git status --short
git diff --stat

여기서 요청과 관련 없는 파일이 보이면 merge 판단을 멈춥니다. 새 패키지가 추가되었거나 lockfile이 바뀌었거나 환경 변수 파일이 보이면 이유를 먼저 확인합니다. 이 단계에서 목표는 모든 diff를 이해하는 것이 아닙니다. 요청한 문제와 무관한 변경이 섞였는지 찾는 것입니다.

변경 범위가 넓으면 AI에게 바로 이렇게 다시 보냅니다.

방금 수정은 아직 merge하지 않습니다.
요청한 문제와 직접 관련 있는 파일만 남기고, 나머지 변경은 되돌리는 계획을 먼저 제시하세요.
새 패키지 추가, 설정 파일 변경, 환경 변수 변경은 금지합니다.
수정 후 실행해야 할 검증 명령도 함께 적어 주세요.

package.json에서 프로젝트의 검증 명령을 찾습니다

초보자가 자주 막히는 지점은 "무슨 테스트를 돌려야 하지"입니다. 정답은 프로젝트마다 다릅니다. docs.npmjs.com의 npm run 문서는 npm run이 package.json의 scripts 객체에 있는 명령을 실행한다고 설명합니다. 그래서 AI가 "테스트했습니다"라고 말했는지보다, 이 프로젝트에 실제로 어떤 script가 있는지 먼저 봐야 합니다.

npm run

목록에서 test, lint, typecheck, build 중 있는 것을 확인합니다. 작은 문구 수정이면 npm run lint만으로 충분할 때도 있습니다. TypeScript 오류를 고쳤다면 npm run typecheck가 더 직접적입니다. Next.js 배포 오류를 고쳤다면 npm run build가 더 의미 있습니다.

명령을 고를 때는 다음 순서로 좁힙니다.

오류를 재현했던 명령이 있으면 그 명령을 다시 실행합니다.
재현 명령이 없으면 npm run test, npm run lint, npm run typecheck, npm run build 중 프로젝트에 있는 것을 고릅니다.
명령이 너무 오래 걸리면 먼저 가장 관련 있는 하나만 실행하고 결과를 남깁니다.
명령이 없으면 AI에게 "이 프로젝트에서 검증 명령을 어디서 찾아야 하는지"부터 묻습니다.

중요한 것은 명령 이름을 외우는 것이 아닙니다. package.json에 있는 명령을 보고, 지금 바뀐 코드와 가장 가까운 검증을 하나 고르는 것입니다.

실패 로그는 첫 줄부터 그대로 남깁니다

검증 명령이 실패해도 바로 새 코드를 요청하지 않습니다. 실패 로그를 줄이면 AI는 추측으로 고치기 쉽습니다. 실패 출력에서 먼저 남길 것은 네 가지입니다.

실행한 명령
첫 번째 오류 줄
파일 경로와 줄 번호
마지막 실패 요약

예를 들어 npm run build가 실패했다면 "빌드가 안 돼"가 아니라 다음처럼 보냅니다.

목표: 방금 수정한 기능은 유지하고 빌드 오류만 고쳐 주세요.
실행 명령: npm run build
첫 오류: Type error: Property 'items' does not exist on type ...
파일: app/page.tsx:42
제한: 새 패키지 추가와 폴더 구조 변경은 하지 마세요.
완료 조건: 같은 명령을 다시 실행했을 때 통과 출력이 나와야 합니다.

이렇게 보내면 AI가 바꿔야 할 범위가 줄어듭니다. 실패 로그를 그대로 주는 이유는 AI를 못 믿어서가 아닙니다. 수정 대상과 완료 조건을 같은 화면에 묶어 주기 위해서입니다.

GitHub 체크는 merge 직전의 두 번째 증거입니다

로컬 명령이 통과해도 GitHub에서 다시 실패할 수 있습니다. 운영체제, Node 버전, 환경 변수, CI 캐시가 다를 수 있기 때문입니다. docs.github.com의 GitHub Docs는 status check가 커밋이 저장소 조건을 만족하는지 알려 준다고 설명합니다. 또 required status check는 성공적으로 완료되어야 하며, 브랜치가 최신 base와 맞아야 할 수 있다고 안내합니다.

따라서 pull request를 쓰는 프로젝트라면 merge 전에 다음을 봅니다.

Checks 탭이 모두 성공, skipped, neutral 중 하나인지
실패한 체크가 있다면 어떤 job과 step인지
브랜치가 base branch와 동기화되어야 한다는 안내가 있는지
로컬에서 통과한 명령과 CI에서 실패한 명령이 같은지

GitHub 체크가 실패했는데 AI에게 "CI가 실패했어"라고만 보내면 범위가 넓습니다. job 이름, 실패 step, 첫 오류 줄을 함께 붙여야 합니다. 이미 GitHub Actions 로그를 보는 법이 막힌다면 GitHub Actions 실패 로그를 3분 안에 좁히는 방법을 같이 봅니다.

merge해도 되는 상태와 멈춰야 하는 상태를 나눕니다

merge 가능한 상태는 거창하지 않습니다. 다음 네 가지가 채워지면 초보자 기준으로 충분히 판단할 수 있습니다.

git diff --stat에서 요청 범위 밖 변경이 보이지 않습니다.
프로젝트에 맞는 검증 명령 하나 이상이 통과했습니다.
실패했던 명령이 있었다면 같은 명령으로 재확인했습니다.
pull request를 쓴다면 GitHub 체크가 실패 상태로 남아 있지 않습니다.

반대로 다음 중 하나라도 있으면 멈춥니다. AI가 말한 완료와 상관없이 merge하지 않습니다.

.env, 토큰, 비밀키처럼 보이는 파일이 diff에 있습니다.
요청하지 않은 새 패키지나 설정 변경이 있습니다.
테스트가 실패했는데 AI가 실패 로그를 보지 않았습니다.
GitHub required check가 실패하거나 대기 중입니다.
바뀐 파일 설명을 본인이 한 문장으로 말할 수 없습니다.

여기서 멈추는 것은 실력이 부족해서가 아닙니다. 코딩 도구를 운영 가능한 흐름으로 쓰기 위한 최소 절차입니다. 오늘은 한 가지만 기억하면 됩니다. AI가 완료라고 말한 뒤 첫 행동은 merge가 아니라 통과 출력 만들기입니다.