03-실전

03. 실전 — 하네스 관점으로 다시 보기

시나리오: “Claude Code가 갑자기 멍청해졌어요”

흔한 신고다. 모델 탓을 하기 전에 하네스 관점으로 진단해 보자.

1) 컨텍스트 층을 의심한다

• 세션을 너무 오래 끌어 컨텍스트가 80% 이상 찼는가? Matsuoka의 관찰처럼, Claude Code는 컨텍스트가 가득 차면 추론 품질이 급락한다. → /compact 또는 새 세션.
• CLAUDE.md에 모순된 지시문이 쌓였는가? → Part 3/02 CLAUDE.md 디렉티브 설계 참고.

2) 도구 층을 의심한다

• 최근에 MCP 서버를 추가했는가? 도구 카탈로그가 부풀면 모델이 잘못된 도구를 고른다.
• 도구 설명(description)이 모호하면 모델은 추측으로 호출한다. SWE-agent 논문이 강조하듯, ACI(Agent-Computer Interface) 설계가 결과를 좌우한다.

3) 권한 층을 의심한다

• acceptEdits 모드인가, default인가? 권한 모드가 다르면 모델의 “행동 자유도”가 달라지고, 주저함이 출력에 새어 나온다.

4) 루프 층을 의심한다

• Plan Mode를 켜고 끄는 것을 잊었는가? Plan Mode는 루프의 종료 조건을 바꾼다.

이 4단계를 거치고 나서야 비로소 “모델 자체가 회귀했나” 하는 가설이 의미가 있다. 대부분의 체감 저하는 하네스 층에서 일어난다.

시나리오: “ChatGPT에서는 잘 되던 게 왜 Claude Code에서는?”

같은 모델이라도 시스템 프롬프트, 도구 카탈로그, 응답 형식 강제, 출력 길이 정책이 다르다. 같은 모델 ≠ 같은 결과. 하네스가 다르기 때문이다. 반대도 성립한다 — Claude Code의 에이전트 동작은 모델만 가져다 API에 붙여서는 재현되지 않는다.

손에 잡히는 정신 모델

다음 한 문장을 외워두면 본 파트 나머지가 쉬워진다.

“내 LLM이 멍청해 보이면, 십중팔구 모델이 아니라 내 하네스가 멍청한 것이다.”

이 문장은 sshh의 글을 비롯해 하네스 엔지니어링 진영이 반복해서 강조하는 명제다. 본 파트의 나머지 7개 챕터는 이 명제를 실제로 디버깅 가능한 형태로 풀어낸다.

다음 챕터 예고

• 02-Claude-Code-하네스-내부 — 시스템 프롬프트와 도구 루프를 직접 들여다본다.
• 08-하네스-디버깅-체크리스트 — 위 4단계 진단을 정식 체크리스트로 만든다.