설정한 대로 동작하지 않을 때

CLAUDE.md의 지침을 모델이 절대 실행하지 못합니다

무엇이 보이는가. CLAUDE.md에 “예외 없이 이 명령을 실행하라”고 써 뒀는데, 실제로는 한 번도 실행되지 않습니다. 문서만 읽으면 지침에는 아무 문제가 없어 보입니다.

왜 그런가. 그 지침이 가리키는 명령이나 스킬이 수동 호출 전용으로 설정돼 있으면, 모델 자신에게는 애초에 보이지 않습니다. 모델이 지침을 무시하는 것이 아닙니다. 그 명령을 자율적으로 호출할 방법 자체가 하네스 설정에서 차단돼 있는 것입니다. 지침은 그대로 있고 문서는 정상으로 읽히기 때문에 원인을 찾기 어렵습니다.

어떻게 확인하는가. 지침이 참조하는 명령이나 스킬이 모델에게 자율 호출 가능한 상태로 등록돼 있는지 설정을 직접 확인하십시오. 문서를 다시 읽는 것으로는 이 문제를 찾을 수 없습니다.

어떻게 고치는가. 지침을 쓸 때 그 지침이 참조하는 도구가 실제로 모델에게 보이는지 함께 확인하십시오. 수동 호출 전용으로 남겨야 하는 이유(부작용이 있는 동작)가 있다면, 그 사실을 지침에도 반영해 자동 실행을 기대하지 않도록 하십시오. 메커니즘은 CLAUDE.md 실전 가이드를 참고하십시오.

세션 중간에 등록한 MCP 서버의 도구가 안 보입니다

무엇이 보이는가. 세션 도중에 새 MCP 서버를 등록했는데, 그 서버가 제공하는 도구가 같은 세션에서 호출되지 않습니다.

왜 그런가. MCP 서버는 세션 시작 시점에 로드됩니다. 세션 도중에 등록한 서버는 재시작 전 까지는 그 세션에 도구로 반영되지 않습니다.

어떻게 확인하는가. 등록 직후 도구 목록에 새 서버의 도구가 나타나는지 확인하십시오. 나타나지 않는다면 설정 문제가 아니라 로드 시점 문제입니다.

어떻게 고치는가. 세션을 재시작하십시오. 메커니즘은 MCP를 참고하십시오.

훅을 걸었는데 프롬프트가 조용히 막힙니다

무엇이 보이는가. UserPromptSubmit 훅을 등록한 뒤부터, 특정 상황에서 프롬프트를 입력해도 아무 반응이 없거나 처리되지 않습니다.

왜 그런가. UserPromptSubmit 훅이 0이 아닌 종료 코드로 끝나면 프롬프트 자체가 차단됩니다. 훅 스크립트가 없는 파일을 참조하거나 예외를 던지면, 그 훅이 걸리는 모든 프롬프트가 막힙니다.

어떻게 확인하는가. 훅을 등록하기 전에 stdin으로 입력을 직접 먹여 파이프 테스트를 하십시오. 파일이 있을 때, 없을 때, 무관한 입력일 때 세 경우 모두 정상 종료하는지 확인하십시오.

어떻게 고치는가. 파일 존재 여부를 가드로 감싸고([ -f "$f" ] && ... || true), 스크립트 내부도 예외를 전부 잡아 항상 exit 0으로 끝나게 만드십시오. 훅은 어떤 이유로도 사용자를 막아서는 안 됩니다. 메커니즘은 Hooks를 참고하십시오.

훅이 몇 밀리초로 측정됐는데 실제 체감은 훨씬 느립니다

무엇이 보이는가. 훅 스크립트 자체의 실행 시간을 재면 몇 밀리초 수준인데, 실제로 매 프롬프트마다 체감되는 지연은 그보다 훨씬 큽니다.

왜 그런가. 스크립트 내부 로직만 측정하면 프로세스 기동 비용이 빠집니다. 매 프롬프트마다 새 프로세스를 띄우는 구조라면, 그 기동 비용이 실제 지연의 대부분을 차지할 수 있습니다.

어떻게 확인하는가. 스크립트 내부 타이머가 아니라, 훅이 호출되는 시점부터 완료되는 시점까지를 외부에서 측정하십시오.

어떻게 고치는가. 훅 성능은 프로세스 기동을 포함해 측정하십시오. 내부 로직만 잰 값을 실제 지연으로 오인하지 마십시오.

CLAUDE.md에 규칙을 써 뒀는데 지켜지지 않습니다

무엇이 보이는가. CLAUDE.md에 반드시 지켜야 할 규칙을 명시적으로 적었는데, 시간이 지나면 지켜지지 않는 경우가 늘어납니다.

왜 그런가. CLAUDE.md의 지침은 강제되지 않는 권고입니다. 매번 모델이 그 지침을 다시 떠올려 적용해야 하므로, 조건이 복잡하거나 빈도가 낮은 규칙일수록 잊히기 쉽습니다.

어떻게 확인하는가. 그 규칙이 어겨졌을 때 실제로 무언가가 실패하거나 차단되는지 확인하십시오. 아무것도 막지 않는다면 문서로만 존재하는 규칙입니다.

어떻게 고치는가. 반드시 지켜져야 하는 규칙은 문서에만 남기지 말고 훅으로 기계적으로 강제하십시오. 문서는 설명을 위해 남기십시오.