Claude가 코드를 작성하면 테스트가 실패하고, 에러를 다시 당신에게 넘겨 처리하게 합니다.
하지만 self-fixing agent는 다릅니다. 스스로 실패를 읽고, 원인을 파악해 수정한 후, 다시 실행해 모든 테스트가 통과할 때까지 반복합니다.
한 번 설정해두면, 더 이상 에이전트의 무급 디버거 역할을 하지 않아도 됩니다.
전체 설정 방법은 아래와 같습니다 👇
본격적으로 들어가기 전에, AI와 바이브 코딩에 대한 daily note를 제 Telegram 채널에서 공유하고 있습니다: https://t.me/zodchixquant🧠
한 번의 실행으로는 충분하지 않은 이유
기본적으로 Claude는 작업을 한 번 실행합니다. 테스트가 실패하면 에러를 보고하고 기다립니다. 당신이 그 에러를 읽고, 다시 붙여넣고, 다시 시도하라고 지시해야 합니다. 디버깅은 당신이 하고, Claude는 단지 타이핑만 하는 셈이죠.
Self-fixing agent는 이 구조를 뒤집습니다. 스스로 실패를 읽고, 어떤 종류의 버그인지 파악한 후, 그 원인을 수정하고 다시 실행합니다. 마치 디버거가 사고하는 방식과 같습니다. 당신은 테스트가 통과하거나 에이전트가 진짜로 막혔을 때만 개입하면 됩니다.
파일 1: fix 명령어
이것은 실제로 실행할 루프입니다. .claude/commands/fix.md 파일을 만드세요:
1---2description: 작업을 실행하고 모든 테스트가 통과할 때까지 자가 수정3argument-hint: <task>4allowed-tools: Read, Write, Edit, Glob, Grep, Bash5model: sonnet6---78Task: $ARGUMENTS910Loop:111. 작업을 구현합니다.122. 테스트 스위트를 실행합니다: `npm test` (또는 pytest, cargo test).133. 모든 테스트가 통과하면: 중단하고 결과를 보여줍니다.144. 테스트가 실패하면: 에러 유형을 분류하고, 근본 원인을 명명한 후,15 그 원인을 수정하고 2단계로 돌아갑니다.165. 최대 5회 시도합니다. 각 라운드마다 시도 번호를 알립니다.1718분류 후 수정 순서가 핵심입니다. 매 라운드 진단 후 편집하세요.19테스트를 약화시켜 통과시키지 말고, 코드를 수정하세요.
/fix users 엔드포인트에 페이지네이션 추가 라고 입력하면 에이전트가 코드를 작성하고, 테스트하고, 모든 테스트가 통과할 때까지 스스로 수정합니다.
파일 2: 자동 검사 훅
명령어는 요청 시 작동합니다. 훅은 모든 편집 시 자동으로 자가 점검을 수행하게 만듭니다.
.claude/settings.json 파일에 추가하세요:
1{2 "hooks": {3 "PostToolUse": [4 {5 "matcher": "Write|Edit",6 "hooks": [7 { "type": "command", "command": "npm test --silent 2>&1 | tail -5 || echo 'TESTS FAILING, fix before continuing'" }8 ]9 }10 ]11 }12}
이제 Claude가 파일을 편집할 때마다 테스트가 실행되고, 결과가 다시 에이전트의 뷰에 표시됩니다.
실패가 즉시 나타나므로, 에이전트는 다음 작업으로 넘어가거나 깨진 코드 위에 변경 사항을 쌓아 올리지 않고, 같은 흐름 내에서 문제를 수정합니다.
파일 3: 에러 읽는 방법 가르치기
이 파일이 진짜 디버거와 추측성 수정을 구분짓는 핵심입니다. 대부분의 에이전트는 "테스트 실패"를 보고 무작위로 편집을 시작합니다.
하지만 좋은 에이전트는 먼저 에러 유형을 읽습니다. 각 유형이 서로 다른 원인을 가리키기 때문입니다. 이 내용을 CLAUDE.md 파일에 넣으세요:
1## 수정 전 실패를 읽는 방법23항상 먼저 에러 유형을 명명하세요. 각각은 다른 의미를 갖습니다:45- Assertion 실패 (예상 X, 실제 Y): 로직이 잘못되었습니다.6 assertion 지점부터 값이 생성된 위치까지 거슬러 올라가세요.7 테스트의 기대치가 아니라 계산 자체를 수정하세요.89- Type error / undefined is not a function: 형태 불일치입니다.10 어떤 값이 null이거나, 잘못된 타입이 해당 라인에 도달했습니다.11 그 값이 어디서 유래했는지 찾아서, 그곳에서 가드하거나 수정하세요.1213- Timeout / hang: await 누락 또는 promise가 해결되지 않음입니다.14 await 없이 호출된 비동기 함수나, 절대 전환되지 않는 조건을 찾으세요.1516- Import / module not found: 경로나 의존성 문제로, 로직 문제가 아닙니다.17 경로를 수정하거나 설치하세요. 해당 코드를 건드리지 마세요.1819- Flaky (가끔 통과): 공유 상태나 타이밍 문제로, 절대 무작위가 아닙니다.20 순서 의존적인 테스트나, 모킹되지 않은 시간/네트워크를 찾으세요.2122규칙: 편집하기 전에 유형과 한 문장으로 된 근본 원인을23명확히 말로 표현하세요. 원인을 명명할 수 없다면 추측하는 것입니다. 중단하세요.
Type error와 assertion 실패는 정반대의 접근이 필요합니다. 하나는 상류의 데이터 형태 문제이고, 다른 하나는 해당 지점의 잘못된 로직입니다. 먼저 분류하면 에이전트가 올바른 대상을 수정합니다.
분류를 건너뛰면 빨간색이 사라질 때까지 무작위로 편집하게 되고, 결과적으로 조용히 망가진 테스트 스위트만 남게 됩니다.
실제로 보게 되는 화면
한 줄만 입력하면 됩니다:
1/fix 날짜 포맷터가 잘못된 시간대를 반환함
그러면 에이전트가 스스로 작업합니다:
1시도 12 테스트 실행 → 실패3 유형: assertion (예상 5, 실제 11)4 원인: 쿼리에 페이지 크기가 적용되지 않음5 LIMIT 절 수정67시도 28 테스트 실행 → 실패9 유형: type error (offset이 undefined)10 원인: 페이지 1은 offset을 보내지 않아, 기본값 설정 오류11 offset = (page-1)*size 추가1213시도 314 테스트 실행 → 모두 통과 (7/7)15163번 시도 후 수정 완료. diff를 검토하시겠습니까?
에러를 다시 붙여넣을 필요가 전혀 없었습니다. 에이전트가 스스로 실패를 읽고, 각 원인을 명명한 후, 모든 테스트가 통과할 때까지 수정했습니다.
자주 하는 실수
진단 전 수정. 가장 큰 실수입니다. 에러 유형을 명명하기 전에 편집하는 에이전트는 추측하는 것이며, 추측으로 빨간색을 초록색으로 만드는 것은 운에 의존한 것이지, 수정한 것이 아닙니다. 분류 우선 규칙이 유일한 방어책입니다.
모든 에러를 동일하게 처리. Timeout과 assertion 실패는 공통점이 전혀 없지만, 에러 유형 가이드가 없는 에이전트는 둘 다 "뭔가 잘못됨"으로 처리하고 가장 가까운 라인을 편집합니다. 수정의 절반이 잘못된 파일에 적용됩니다.
증상만 패치. throw를 발생시키는 호출을 try/catch로 감싸면 테스트는 통과하지만 버그는 남습니다. 프로토콜은 정확히 이 이유로 에러를 침묵시키는 것을 금지합니다.
테스트를 약화시키는 것. 에이전트가 테스트를 편집할 수 있게 허용하면, 결국 통과를 위해 실패하는 테스트를 삭제할 것입니다. 아무것도 증명하지 못하는 통과 테스트 스위트는 최악의 결과이므로, 이 규칙은 절대 협상 대상이 아닙니다.
5분 설정
2분: .claude/commands/fix.md 파일 생성.
1분: settings.json에 PostToolUse 훅 추가.
1분: CLAUDE.md에 self-debug 프로토콜 추가.
1분: 알려진 버그에 대해 /fix를 실행하고, 에이전트가 시도별로 원인을 해결하는 과정을 지켜보세요.
더 이상 에러를 중계하는 인간이 될 필요가 없습니다. 에이전트가 스스로 빨간색을 읽고, 초록색이 될 때까지 수정합니다. 에이전트가 더 똑똑해진 것이 아니라, 문제를 다시 당신에게 넘기는 것을 멈춘 것뿐입니다.
읽어주셔서 감사합니다!
AI, 금융, 바이브 코딩에 대한 daily note를 제 Telegram 채널에서 공유하고 있습니다: https://t.me/zodchixquant
