AI 코딩 에이전트가 스스로 버그를 잡아내는 피드백 루프를 만드는 법

AI 코딩 에이전트가 겉보기엔 맞지만 조용히 무언가를 망가뜨리는 코드를 작성할 때, 문제는 대개 모델이 아니다. 에이전트가 그 실패를 본 적이 없다는 것이 문제다. 에이전트는 변경을 작성하고, 성공을 선언하고, 다음으로 넘어간다. 테스트 스위트가 이제 빨간불이 켜졌다는 것을 아무도 알려주지 않았기 때문이다. 해결책은 루프를 닫는 것이다. 에이전트 자신의 도구가 결과를 자동으로 다시 보고하게 만드는 것이다.

이 가이드는 당신보다 먼저 에이전트가 자기 실수를 잡아내도록 그 피드백 루프를 구축하는 방법을 보여준다.

핵심 아이디어: 오류는 다시 컨텍스트로 흘러들어가야 한다

신뢰할 수 있는 에이전트 워크플로에는 네 박자가 있다. 탐색, 계획, 구축, 그리고 검증이다. 대부분의 사람은 "구축"에서 멈춘다. 검증 단계야말로, 작동하는 코드를 만들어내는 에이전트와 그럴듯해 보이는 코드를 만들어내는 에이전트를 가르는 지점이다.

검증이란 모든 변경 이후에 실제 검사를 실행하는 것을 뜻한다. 당신의 테스트 러너, 린터, 타입 체커를 돌리고 그 출력을 에이전트에 다시 전달하는 것이다. 검사가 실패하면 오류 메시지가 에이전트의 컨텍스트에 도착하고, 모델은 그것을 다른 지시와 똑같이 다룬다. 즉, 실패를 읽고 고친다. 지루한 왕복 작업에는 사람이 끼어들 필요가 없다.

이를 두 가지 방식으로 할 수 있다. 프로젝트 지시문에서 요청하거나, 건너뛸 수 없도록 자동화하는 것이다.

옵션 1: 프로젝트 설정에서 그냥 요청하기

가장 노력이 덜 드는 방식은 CLAUDE.md나 AGENTS.md(대부분의 에이전트가 시작 시 읽는 평문 지시 파일)에 한 줄을 넣는 것이다:

## Verification
After any code change, run `npm run typecheck && npm test`.
If either fails, fix the cause and re-run before reporting done.

이 방법은 놀랍도록 잘 작동한다. 하지만 어디까지나 권고 사항이다. 바쁜 에이전트는 잊어버릴 수도 있고, 어떤 변경이 검증하기에 "너무 작다"고 판단할 수도 있다. 정말로 신경 쓰는 것이라면, 검증을 결정론적으로 만들어라.

옵션 2: 훅으로 자동화하기

Claude Code 훅을 사용하면 모델이 기억하든 말든 상관없이, 생애주기 이벤트에 반응해 셸 명령을 실행할 수 있다. 여기서 관련된 것은 PostToolUse로, 에이전트가 파일을 편집한 이후에 실행된다. 한 실용적인 훅 가이드가 설명하듯, PostToolUse는 반응을 위해 만들어졌다. 포매팅, 로깅, 테스트 실행 같은 것들이며, 그 출력은 에이전트의 컨텍스트로 다시 주입되어 다음 단계에 영향을 준다.

다음은 모든 파일 편집 이후에 타입 체커를 실행하고 실패를 에이전트에 다시 넘겨주는 최소한의 훅이다. .claude/settings.json에 작성한다:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run typecheck"
          }
        ]
      }
    ]
  }
}

이제 사이클이 자동으로 돌아간다: 에이전트가 코드를 작성하고 → 훅이 tsc를 실행하고 → 타입 오류가 있으면 메시지가 컨텍스트로 다시 흘러들어가고 → 에이전트가 그것을 고치고 → 훅이 다시 실행된다. 훅 레퍼런스는 0이 아닌 종료 코드와 출력이 어떻게 모델에 노출되는지 문서화하고 있다. 이 루프는 모든 쓰기마다 실행되며, 별도의 프롬프트가 필요 없다.

루프를 빠르고 범위를 좁게 유지하라

피드백 루프는 빨라야만 도움이 된다. 몇 가지 경험칙은 다음과 같다:

• 저렴한 검사는 매 편집마다, 비싼 검사는 덜 자주 실행하라. 변경된 파일에 대한 타입 체크나 린터는 빠르다. 전체 통합 스위트는 그렇지 않으니, 그것은 Stop 훅(에이전트가 한 턴을 마칠 때)이나 수동 명령 뒤에 두고, 매 입력마다 돌리지 마라.
• 변경된 부분으로 범위를 좁혀라. 한 줄짜리 CSS 수정 후에 전체 테스트 스위트를 돌리는 것은 시간을 낭비하고 컨텍스트를 가득 채운다. 도구가 허용하는 한, 영향을 받은 파일만 대상으로 삼아라.
• 실패를 읽을 수 있게 만들어라. 에이전트는 읽을 수 있는 것만 고친다. 명확하고 위치가 표시된 오류 메시지(file:line: message)를 주는 린터와 타입 체커는 모델에게 정확히 필요한 것을 제공한다. 두루뭉술한 "build failed"는 그렇지 못하다.

구체적인 전후 비교

루프가 없을 때: 당신이 에이전트에게 함수 이름을 바꾸라고 요청한다. 에이전트는 호출 지점 세 곳을 수정하지만, 열어보지 않은 파일에 있는 네 번째 호출 지점을 놓치고는 완료를 보고한다. 당신은 한 시간 뒤 런타임에서 깨진 import를 발견한다.

루프가 있을 때: 같은 이름 변경이 저장 시 typecheck을 촉발한다. tsc는 놓친 호출 지점에서 Cannot find name 'oldFn'을 보고한다. 그 오류가 컨텍스트에 도착하고, 에이전트는 네 번째 파일을 열어 참조를 고치며, 다음 검사가 통과한다. 이 모든 일이 에이전트가 끝났다고 당신에게 말하기 전에 일어난다.

핵심 교훈

AI 에이전트는 코드를 만들어내는 데는 능하지만, 그것이 틀렸을 때 알아차리는 데는 서툴다. 당신은 그들에게 당신이 의지하는 것과 같은 신호를 줌으로써 그 간극을 메운다. 빨간 테스트, 타입 오류, 실패한 린트 규칙을, 변경 직후 자동으로 전달하는 것이다. 프로젝트 지시문에 한 줄을 넣는 것으로 시작한 다음, 가장 중요한 검사는 모델이 기억하든 말든 실행되도록 훅으로 승격하라. "똑똑하게" 느껴지는 에이전트는 보통 그저 촘촘한 피드백 루프에 연결된 에이전트일 뿐이다.