Claude Code의 prompt-audit를 활용한 CLAUDE.md 건강 진단 결과와 개선점

• Claude Code의 prompt-audit가 무엇을 체크해주는지(대상 파일, 관점, 나오는 결과물) - 개인 개발 중인 Godot 제작 게임 'SLOTS QUEST'의 CLAUDE.md에 실제로 적용해 본 결과 및 지적된 3가지 사항

• '옛 모델용으로 작성한 지시사항'이 현재 모델에서는 역효과가 될 수 있다는 생각과 그 개선 방법

• CLAUDE.md를 작성할 때 남겨야 할 것과 삭제해도 되는 것 구분하기

prompt-audit는 CLAUDE.md, 스킬(skill), 서브 에이전트 정의 등 '오래된 지시사항'을 찾아내어 지적 보고서와 수정 diff 제안을 해줍니다. 파일은 임의로 수정하지 않습니다. - 가장 효과가 좋았던 지적 사항은
**'기획은...'. 현재 모델은 지시에 순응적이어서 오타 수정만으로도 53KB 분량의 기획서를 읽게 만드는 원인이 될 수 있다. → '사양과 관련된 변경에서는 해당 절을 반드시 참조할 것.'로 약화시켰다. docs/GDD.md
두 번째는 CLAUDE.md의 정보가 오래되었다는 점입니다. 작성 당시에는 테스트 케이스가 1개였는데, 지금은 약 45개가 있습니다. → '어떤 것을 실행할지는 대응표를 참고할 것.'로 수정했습니다. - 세 번째는 사고 발생 날짜 같은 경위 서술입니다. 규칙의 이유로 필요한 것은 '무슨 일이 일어나는가'이며, '언제 일어났는지'는 필요하지 않습니다.

• 반대로, 환경의 사실/이유/절차는 삭제하지 않는 것이 원칙입니다. 전체적으로는 '줄이는 것'을 위한 감사라기보다는 '현재 모델과 현재 리포지토리에 적합한가'를 보는 감사가었습니다.

SLOTS QUEST는 Godot 4(GDScript)로 제작하는 개인 개발의 퀘스트형 슬롯 게임입니다. 개발은 거의 Claude Code와 함께 진행하고 있으며, 리포지토리 직하단의 CLAUDE.md와 프로젝트 전체 공통의 ~/.claude/CLAUDE.md에 작업 규칙을 작성하고 있습니다.

이러한 파일들은 작성 당시의 모델이나 상황을 전제로 하고 있기 때문에 시간이 지나면 다음과 같은 문제가 발생합니다.

• 당시 모델의 습관에 맞춰 작성된 강한 어조가 현재 모델에게는 너무 효과적이다.
• 리포지토리가 성장하면서 작성된 사실이 오래된다.
• 여러 파일에서 언급하는 내용이 서로 모순된다.

이를 종합적으로 점검해주는 것이 prompt-audit입니다.

Claude Code에 포함된 claude-api 스킬의 서브 커맨드입니다. 이번에는 Claude Code 데스크톱 앱에서 /doctor prompt-audit로 실행했습니다.【확인 필요: 실행 방법 표기법. /claude-api prompt-audit로도 동일하게 작동함】
대상으로 한 것은 Claude Code 세션에 로드되는 설정만입니다.

• 프로젝트의 CLAUDE.md (부모 디렉토리나 서브 디렉토리에 있는 것, CLAUDE.local.md, AGENTS.md 포함) ~/.claude/CLAUDE.md
• .claude/와 ~/.claude/ 아래의 rules / skills / commands / agents / output-styles - 설치된 플러그인 스킬 등(보고만 하고 수정은 제안하지 않음)

settings 관련 파일, .mcp.json, ~/.claude.json는 프롬프트가 아니라 비밀 정보가 포함될 수 있으므로 읽지 않는다는 선 긋기도 되어 있었습니다.

SLOTS QUEST는 Claude API를 호출하는 코드를 가지고 있지 않기 때문에 그룹 3, 4는 '대상 제외'로 판정되었습니다.

• 지적 보고서: 파일:행

、該当テキスト、どのパターンか、なぜ古いか、確度（High / Medium / Low）、対応（remove / rewrite / flag など） -
제안 diff: 지적 사항별로 1 hunk. 포함할지 여부는 사람이 결정함

확도가 Low인 것은 「flag(보고만 함)」이 되어 diff에는 들어가지 않습니다. 감사 방침으로 「아무것도 발견되지 않으면 아무것도 바꾸지 않는다」가 명시되어 있는 것도 좋은 인상을 받았습니다.

-企画は `docs/GDD.md` を必ず参照すること。
+ゲームの仕様や企画に関わる変更では `docs/GDD.md` の該当する節を参照する。

조건 없는 「반드시」는, 지금 모델에게는 글자 그대로 효력이 있습니다. GDD는 53KB가 되기 때문에, 관계없는 작업이라도 매번 이것을 읽으러 가면 시간과 토큰이 소모됩니다.

여기서 흥미로웠던 점은, 예전에는 강하게 쓰지 않으면 읽어주지 않던 지시가, 지금은 강하게 쓸수록 너무 많이 읽는다는 역전 현상이었습니다. 강조하려면 「언제(どのときに)」를 덧붙이는 것이 현재 모델에 맞는 작성법이었습니다.

-# マップ生成ロジックのテスト
+# テスト（tests/test_*.gd を1本ずつ実行。どれを回すかは docs/tuning.md の対応表に従う）
godot --headless --path . -s tests/test_map_generator.gd

git blame

으로 보면, 이 줄을 작성한 것은 프로젝트 초기에였고, 당시에는 테스트가 맵 생성의 단 하나만 있었습니다. 지금은 tests/test_*.gd가 약 45개나 있고, 어떤 파라미터를 건드리면 어떤 테스트를 실행해야 하는지는 docs/tuning.md에 정리되어 있습니다.

적혀 있는 내용 자체는 틀리지 않지만, 「테스트 = 이 단 하나」로 읽힐 수 있다는 점. 거짓은 아니지만 오래된 가장 알아차리기 어려운 유형의 노후화였습니다.

공통 설정인 ~/.claude/CLAUDE.md에 이런 규칙을 적었습니다.

공유 작업 트리의

git stash

를 사용하지 않음.(중략) git stash -u

한 stash를 drop

하면, 추적되지 않은 파일은 git fsck --unreachable

에서만 복구할 수 있게 된다(20XX-XX-XX에 실제로 소실 사고가 발생함).【확인 필요: 날짜를 제시할지】

지적 사항은 괄호 안의 「언제 사고가 발생했는지」는 경위 기술이므로 불필요하다는 것이었습니다. 금지 이유만 「복구가 매우 어려워진다」로 충분히 전달됩니다. 금지 규칙 자체는 남기고, 경위만 삭제하는 제안이었습니다.

참고로, 이 규칙 자체는 같은 리포지토리에서 여러 Claude 세션을 병렬로 돌리는 사람에게는 상당히 추천할 만합니다. stash는 다른 세션의 작업 중인 파일까지 끌어들입니다.

• 「다단계 작업을 할 때는 처음에 태스크 리스트를 만든다」: 현재 모델은 말하지 않아도 계획을 짜지만, 이 줄은 「사람이 추적할 수 있도록 하는 것」이 목적이고 이유도 적혀 있으므로 남겨도 좋다는 판정
• 플러그인 스킬 본문에 MUST/NEVER 등이 고밀도로 들어 있는 경우: 스스로는 수정할 수 없으므로 보고만 함

여기서 가장 참고가 되었습니다.

파일 간의 충돌처럼 보이지만, 실제로는 덮어쓰기: 공통 설정에서는 PR 본문에 Closes #123이라고 쓰는 규칙이고, 프로젝트 측에서는 Closes <owner>/<다른 리포지토리>#123이라고 쓰는 규칙. 언뜻 모순되지만, 프로젝트 측에 「Issue는 다른 리포지토리에서 관리하고 있으므로 #123으로는 닫히지 않는다」라는 이유가 적혀 있기 때문에, 정당한 덮어쓰기로 취급되었습니다. -
내용이 같은 중복은 남긴다: 플러그인의 스킬과 CLAUDE.md 양쪽에 Godot의 헤드리스 테스트 절차가 쓰여 있었지만, 내용이 일치했기 때문에 「작동하는 중복」으로 그대로 두었습니다. - CLAUDE.md에 나오는 경로나 툴 이름은 실재 여부까지 확인되었습니다.

감사의 기준을 자신 나름대로 정리하자면 다음과 같습니다.

남길 것 (모델이 스스로 알 수 없는 것)

• 환경의 사실 (예: 「이 PC는 Win과 Ctrl이 바뀌어 있다」)
• 규칙의 이유 (「왜 안 되는가」)
• 절차가 1개밖에 안전하지 않은 조작에 대한 구체적인 명령어

검토할 것

조건이 없는 '반드시', '절대'(→ 어떤 때에, 를 덧붙여야 함)

• 작성했을 때는 정확했지만, 리포지토리가 성장하며 구식이 된 사실
• 사고의 날짜나 PR 번호 같은 경위(→ 규칙과 이유만 남기는 것이 좋음)
• 현재 모델이라면 말하지 않아도 해야 할 것

'짧게 만들기 위한 감사'가 아니라, 현재 모델과 현재 리포지토리에 적합한지를 보는 감사가 가장 큰 깨달음이었습니다.

• CLAUDE.md는 그대로 두면, 모델 세대교체와 리포지토리 성장이 모두 되어 구식이 됩니다.
• prompt-audit

은 그 열화를 '왜 오래되었는지'를 포함하여 지적하고 diff까지 제안해 줍니다. 모델이 새로워진 타이밍에 주기적으로 실행하는 것이 좋을 것 같습니다.