03-실전

03. 실전 — --debug로 들여다보기

직접 보는 법

claude --debug

이 플래그는 매 턴 (a) 합성된 시스템 프롬프트, (b) 사용 가능한 도구 목록, (c) 모델 응답의 raw tool_use 블록, (d) 디스패치된 도구 결과 — 를 stderr에 덤프한다. 한 번이라도 이 출력을 끝까지 스크롤해 보는 것이 1챕터의 멘탈 모델을 근육 기억으로 바꾸는 가장 빠른 길이다.

작은 실험 셋

1. 시스템 프롬프트 비교 — 빈 디렉터리에서 claude --debug, 그리고 CLAUDE.md가 있는 디렉터리에서 동일 명령. 두 출력의 시스템 프롬프트 길이/섹션 차이를 본다.
2. 도구 호출 횟수 측정 — “tests/ 폴더의 모든 파일을 읽고 요약해 줘” 같은 작업을 시키고, 한 응답 안에서 tool_use가 몇 번 나오는지 센다.
3. stop_reason 관찰 — end_turn이 언제 찍히는지. 모델이 스스로 종료하지 않고 한참 더 도구를 부르는 경우가 보일 것이다 → 챕터 03의 종료 조건 주제로 이어진다.

자주 묻는 질문

Q. CLAUDE.md를 길게 쓰면 매번 비싸지나? 그렇다. 시스템 프롬프트는 매 messages.create마다 다시 보내진다. Anthropic의 prompt caching이 이 비용을 상당 부분 흡수하지만, 캐시 적중을 위해서도 바뀌지 않는 부분을 앞쪽에 두는 구조가 유리하다.

Q. MCP 도구를 100개 등록하면 어떻게 되나? 도구 카탈로그가 시스템 프롬프트의 일부로 직렬화돼 토큰을 먹고, 모델의 도구 선택 정확도도 떨어진다. SWE-agent 논문이 ACI 단순성을 강조하는 이유와 같다.

Q. 내가 만든 도구를 끼워 넣을 수 있나? 직접 코어를 패치할 수는 없지만, MCP 서버로 도구를 노출하면 디스패처가 동일한 인터페이스로 흡수한다. Part 8 (MCP 생태계) 참고.