Claude Code 빌드 오류 분류 루프: 15분 안에 원인 좁히기

수정 요청 전에 빌드 오류를 나누기

Node나 Astro 빌드가 실패하면 전체 로그를 붙이고 Claude Code에게 모두 고쳐 달라고 하기 쉽습니다. 하지만 그러면 첫 실패 줄, 원인 후보, 불필요한 정리가 섞입니다.

이 루프는 버그 리포트 템플릿과 리뷰 체크리스트를 빌드 실패에 적용합니다. 목표는 원인을 좁히고, 작은 진단과 수정 후 증거를 남기는 것입니다.

항상 같은 순서로 증거 수집

상태, build, 필요하면 test 순서로 고정합니다.

git status --short
npm.cmd run build
npm.cmd run test -- --runInBand

첫 실행에서 성공할 필요는 없습니다. 중요한 것은 첫 실패 줄을 보존하는 것입니다. 마지막 stack trace보다 첫 실패가 원인에 가까운 경우가 많습니다.

로그를 네 가지로 분류

완벽한 분류는 필요 없습니다. dependency/import path, runtime shape mismatch, test expectation drift, permission boundary 네 가지면 일상 오류의 많은 부분을 줄일 수 있습니다.

const patterns = [
  [/Cannot find module|ERR_MODULE_NOT_FOUND/i, "dependency or import path"],
  [/TypeError:.*undefined|undefined is not/i, "runtime null or shape mismatch"],
  [/Expected.*received|AssertionError/i, "test expectation drift"],
  [/EACCES|permission denied/i, "permission or sandbox boundary"],
];

export function classifyBuildLine(line) {
  const hit = patterns.find(([regex]) => regex.test(line));
  return hit ? hit[1] : "needs manual reading";
}

이 정도만 해도 Claude Code에게 넓은 수정이 아니라 최소 진단을 요청할 수 있습니다.

복사 가능한 분류 프롬프트

이 실패한 빌드 로그를 읽어 주세요.
넓은 리팩터링은 제안하지 마세요.
반환할 내용:
1. 처음 실패한 줄
2. 가장 가능성 높은 원인
3. 최소 진단 명령
4. 최소 코드 또는 설정 수정
5. 수정 후 검증 명령

핵심은 넓은 리팩터링을 금지하는 줄입니다. 빌드 오류는 가설 하나와 증거 명령 하나로 좁히는 편이 빠릅니다.

실패 사례: 너무 빨리 의존성 올리기

“Cannot find module”을 보고 바로 패키지를 설치하거나, “undefined”를 보고 null check를 넓게 넣는 것은 흔한 실수입니다. 실제 원인이 import path, frontmatter, 생성 파일이면 변경만 늘어납니다.

공개 콘텐츠 사이트에서는 로컬 build 성공만으로도 부족합니다. 공개 URL, 올바른 h1, canonical, CTA, Gumroad 링크까지 확인해야 합니다.

다음 단계

명령이 헷갈리면 무료 cheatsheet를 받으세요. 디버깅과 리뷰 프롬프트가 바로 필요하면 50 Prompt Templates를 사용하세요. CI/CD와 운영 검증은 Setup Guide와 상담이 맞습니다.