03-실전

03. 실전 — 루프 진단 레시피

진단 1: “왜 너무 일찍 끝나?”

증상: 사용자가 큰 작업을 줬는데 모델이 계획만 세우고 end_turn.

체크:

1. 사용자 요청에 “끝까지 해” 류 마무리 지시가 있는가? Plan Mode를 켠 상태는 아닌가?
2. CLAUDE.md에 “always confirm before doing X” 같은 디렉티브가 있어 모델이 사용자 확인을 기다리는가?
3. TodoWrite를 시키고 한 항목씩 진행하도록 요청하면 종료가 미뤄진다 (모델이 todo를 다 닫기 전에는 보통 end_turn을 안 한다).

진단 2: “왜 무한 루프 같아?”

증상: 같은 도구를 비슷한 인자로 반복.

체크:

1. 도구 결과가 명시적인 성공 메시지를 돌려주는가? SWE-agent는 빈 출력을 “성공” 문자열로 바꿔야 모델이 재시도를 안 한다고 보고한다.
2. 컨텍스트가 가득 차서 모델이 직전 결과를 잊었는가? /compact.
3. Bash에 출력이 너무 크게 잘리고 있어 모델이 “실패”로 오해하는가? head -n 같은 절단 정책 점검.

진단 3: “왜 max_tokens가 자꾸 나?”

체크:

1. 모델이 통째 코드 블록을 답에 출력하려는가? → “Edit 도구로 적용해” 명시.
2. 응답 형식 강제(JSON 등)가 너무 장황한가?

도구 결과 형식이 행동을 만든다

SWE-agent 논문이 강조하는 ACI(Agent-Computer Interface) 통찰을 기억해 두자.

“good ACI design leads to much better results when using agents.”

의역 — 좋은 ACI 설계가 에이전트 결과를 결정한다.

Claude Code의 내장 도구가 라인 번호 prefix, 경로 검증, 빈 출력 안내 메시지, 절단 표식 등을 신경 쓰는 이유가 여기 있다. 직접 MCP 도구를 만들 때도 동일하게 적용해야 한다 — 모델이 무엇을 다음에 할지 결정하기에 충분한 신호를 결과에 담는다.