Claude Code /doctor prompt-audit: CLAUDE.md 낡은 지시 점검

CLAUDE.md를 한 번 잘 만들어 두면 프로젝트 설명을 매번 반복하지 않아도 됩니다. 문제는 이 파일이 시간이 지나도 저절로 최신 상태가 되지는 않는다는 점입니다. 모델은 바뀌고 폴더는 이동했는데 “단계별 사고 과정을 모두 보여줘”, “삭제된 디렉터리를 기준으로 작업해” 같은 지시가 계속 남을 수 있습니다.

Claude Code /doctor prompt-audit는 이런 프롬프트 부채를 찾는 진단 명령입니다. CLAUDE.md만 보는 것이 아니라 Skills와 Agents, Commands까지 함께 읽고, 현재 모델에 불필요한 옛 프롬프팅 패턴과 존재하지 않는 경로, 서로 충돌하는 규칙을 보고서로 정리합니다.[1][2]

이 글에서는 Claude Code 2.1.278과 2.1.283을 분리해 버전 경계를 확인합니다. 이어서 일부러 낡은 지시를 넣은 테스트 프로젝트를 전체 감사하고, CLAUDE.md만 범위를 좁혀 다시 검사한 뒤, 수정 전후 결과까지 비교합니다.

prompt-audit가 필요한 이유

프로젝트 지시는 일반 코드보다 오래 방치되기 쉽습니다. 빌드 오류처럼 즉시 실패하지 않고, Claude의 행동을 조금씩 이상하게 만들기 때문입니다.

예를 들어 다음 지시는 처음 작성할 때는 이유가 있었더라도 지금은 방해가 될 수 있습니다.

• Always think step by step처럼 이전 모델의 추론을 유도하려고 넣은 상시 문구

• 모든 답변에 scratchpad나 장문의 사고 과정을 출력하라는 지시

• src/old-api/처럼 이미 사라진 디렉터리 참조

• npm run legacy-check처럼 package.json에 없는 명령

• “수정 전 항상 허락받기”와 “질문하지 말고 알아서 수정하기”처럼 같은 범위에서 충돌하는 규칙

• 실패하면 무한 재시도하라는 위험한 자동화 지시

이런 문제를 파일 하나에서 찾는 것은 어렵지 않습니다. 하지만 실제 환경에서는 사용자 전역 CLAUDE.md, 프로젝트 규칙, 여러 Skill과 Agent가 동시에 로드됩니다. 각각은 자연스러워 보여도 합쳐 놓으면 충돌할 수 있습니다.

/doctor prompt-audit는 단순 맞춤법 검사보다 넓은 범위를 봅니다. 공식 문서는 다음 문제를 예로 듭니다.[2]

• 이전 모델에 맞춰 작성된 프롬프팅 패턴

• 현재 존재하지 않는 파일과 명령 참조

• 여러 지시 파일 사이의 모순

• 불필요하게 세세한 작업 순서와 출력 형식 강제

중요한 점은 감사와 수정이 분리된다는 것입니다. 명령을 실행하면 지적 사항과 제안 diff를 받지만, 사용자가 적용을 요청하기 전에는 파일이 바뀌지 않습니다.

지원 버전과 실행 위치

/doctor prompt-audit는 Claude Code 2.1.283에서 추가됐습니다. 같은 기능을 /checkup prompt-audit로도 실행할 수 있습니다.[1]

먼저 셸에서 버전을 확인합니다.

claude --version

확인한 출력은 다음과 같습니다.

2.1.278 (Claude Code)

기존 전역 설치를 바꾸지 않고 특정 버전만 확인하려면 npx로 분리할 수 있습니다.

npx -y @anthropic-ai/claude-code@2.1.278 --version
npx -y @anthropic-ai/claude-code@2.1.283 --version

2.1.278 (Claude Code)
2.1.283 (Claude Code)

prompt-audit 자체는 셸 하위 명령이 아니라 Claude Code 세션 안에서 입력하는 슬래시 명령입니다.

/doctor prompt-audit

버전별 실측 결과는 분명하게 갈렸습니다.

2.1.278에서 단순히 “알 수 없는 명령” 한 줄로 끝나지는 않았습니다. 일반 진단이 현재 버전 업데이트와 설정 정리를 제안했지만, 2.1.283처럼 프롬프트 감사 표와 범위별 제안 diff를 만들지는 않았습니다. 따라서 버전이 낮은데 비슷한 화면이 일부 보인다고 지원되는 것으로 판단하면 안 됩니다.

이 글의 확인일은 2026년 9월 28일입니다. 이후 명령 구조나 감사 범위가 달라질 수 있으므로 공식 릴리스와 문서를 함께 확인하는 편이 안전합니다.

감사하는 파일 범위

인자 없이 실행하면 현재 작업 디렉터리를 기준으로 프로젝트와 사용자 프롬프트 표면을 함께 살핍니다. 공식 문서에 명시된 범위는 다음과 같습니다.[2]

• CLAUDE.md

• CLAUDE.local.md

• AGENTS.md

• .claude/rules/

• .claude/skills/

• .claude/commands/

• .claude/agents/

• .claude/output-styles/

• 사용자 범위의 ~/.claude/ 아래 대응 파일

모든 파일을 무조건 수정 대상으로 보는 것은 아닙니다. 저장소의 실제 구조와 명령을 확인하고, 지시끼리 충돌하는지 비교한 뒤 문제 후보를 설명합니다.

특정 파일이나 디렉터리만 보고 싶다면 뒤에 경로를 붙입니다.

/doctor prompt-audit CLAUDE.md
/doctor prompt-audit .claude/skills/deploy
/doctor prompt-audit .claude/agents

전체 감사를 바로 실행하면 사용자 전역 설정까지 결과에 섞일 수 있습니다. 새 프로젝트를 정리하거나 한 Skill만 수정하는 중이라면 경로 한정 감사부터 시작하는 편이 결과를 읽기 쉽습니다.

실습용 낡은 지시 만들기

실제 업무 저장소를 바로 바꾸지 않고 작은 Git 저장소를 따로 만들었습니다. 구성은 CLAUDE.md, 배포 Skill, 리뷰 Agent, 실제 소스 파일 하나입니다.

prompt-audit-demo/
├── CLAUDE.md
├── package.json
├── src/api/health.js
└── .claude/
    ├── agents/reviewer.md
    └── skills/deploy/SKILL.md

CLAUDE.md에는 의도적으로 문제가 있는 지시를 넣었습니다.

# Project Instructions

You are working on an Express API.

- Always think step by step and show your full chain of thought before editing.
- Before every answer, write a detailed scratchpad and keep revising it until confident.
- Read every file in the repository before making any change.
- Run `npm run legacy-check` after every edit.
- Never edit files without asking for permission first.
- Make all reasonable fixes proactively without asking questions.
- Use `src/old-api/` for all route handlers.
- Keep every response under three sentences, but explain every decision in exhaustive detail.

실제 package.json에는 test만 있고 legacy-check는 없습니다. 소스도 src/old-api/가 아니라 src/api/health.js에 있습니다. 문장 자체의 낡은 패턴뿐 아니라 저장소 사실과 맞지 않는 지시를 함께 탐지하는지 보기 위한 구성입니다.

배포 Skill에는 존재하지 않는 스크립트와 무한 재시도를 넣었습니다.

# Deploy

Before deployment, read the entire repository and show your private reasoning step by step.
Run `./scripts/deploy-old.sh` three times to verify success.
If any command fails, silently retry forever.

리뷰 Agent도 관련 없는 모든 예외를 분석하고 최소 2,000단어를 강제하도록 만들었습니다. 이 세 파일을 Git에 커밋한 상태에서 감사를 실행해 파일 이력과 현재 저장소를 함께 비교할 수 있게 했습니다.

전체 프로젝트 감사

Claude Code 2.1.283 세션에서 다음 명령을 입력합니다.

/doctor prompt-audit

이번 실습의 첫 보고서는 세 파일에서 12개 항목을 지적했습니다.

보고서에는 단순 목록만 나오지 않았습니다. 각 항목마다 파일과 줄, 원문 근거, 문제 유형, 현재 모델에서 불필요한 이유, 신뢰도와 권장 조치가 붙었습니다.

Location: CLAUDE.md:9-10
Evidence: "Never edit files without asking..." /
          "Make all reasonable fixes proactively..."
Pattern: Contradicting instructions
Confidence: High
Action: flag — user must decide intent

여기서 remove, rewrite, flag를 구분해서 볼 필요가 있습니다.

• remove: 현재 모델과 작업에 불필요해 삭제 근거가 분명함

• rewrite: 목적은 남기되 과한 작업 순서나 숫자 제한을 간단한 결과 지시로 바꿈

• flag: 저장소만 보고 올바른 정책을 결정할 수 없어 사용자의 판단이 필요함

특히 src/old-api/의 대체 경로와 배포 명령은 Claude가 임의로 정하면 안 됩니다. 감사 결과도 이를 flag로 남기고 실제 경로를 확인해 달라고 요청했습니다.

CLAUDE.md만 범위 한정

같은 프로젝트에서 파일 경로를 붙여 다시 실행했습니다.

/doctor prompt-audit CLAUDE.md

이번에는 Skill과 Agent를 제외하고 CLAUDE.md에서만 7개 항목이 나왔습니다. 보고서 첫 부분에도 범위가 CLAUDE.md only라고 표시됐습니다.

범위를 좁히면 다음 상황에서 유용합니다.

• 전체 결과가 너무 길어 한 파일의 수정 근거만 보고 싶을 때

• 팀 공용 Skill은 건드리지 않고 프로젝트 지시만 정리할 때

• 새로 작성한 Agent 파일 하나를 커밋 전에 확인할 때

• 수정 후 해당 디렉터리만 빠르게 재검사할 때

경로 한정 감사도 Git 이력과 실제 파일 구조를 비교합니다. 이번 데모는 모든 문제가 한 커밋에 들어 있어 어느 규칙이 더 최신인지 판별할 수 없었습니다. 그래서 “항상 허락받기”와 “질문 없이 진행하기” 중 하나를 자동 선택하지 않고 사용자 결정 항목으로 남겼습니다.

제안 diff 읽는 법

감사 보고서 아래에는 적용 가능한 항목을 모은 제안 diff가 나옵니다. 다음은 실제 제안의 핵심입니다.

-- Always think step by step and show your full chain of thought before editing.
-- Before every answer, write a detailed scratchpad and keep revising it until confident.
-- Read every file in the repository before making any change.
+- Read the files relevant to a change before editing it.

-- Keep every response under three sentences, but explain every decision in exhaustive detail.
+- Keep responses concise; explain non-obvious decisions.

diff가 있다고 바로 전부 적용할 필요는 없습니다. 세 가지를 먼저 확인합니다.

1. 현재 저장소와 일치하는가: 경로와 명령은 실제 파일·package.json을 확인

2. 팀 정책을 보존하는가: 승인 규칙과 배포 절차처럼 저장소만 보고 추측할 수 없는 내용은 담당자가 결정

3. 원래 문제의 재발을 막는가: 단어만 줄이는 대신 검증 가능한 결과를 남김

“모든 파일을 읽어라”를 지우고 아무 지침도 남기지 않는 것보다 “변경과 관련된 파일을 먼저 읽어라”가 목적을 더 잘 보존합니다. “3문장 이하” 같은 숫자 제한도 “간결하게 답하되, 명확하지 않은 결정은 설명한다”처럼 결과 중심으로 바꿀 수 있습니다.

실제 수정 내용

CLAUDE.md는 다음처럼 짧아졌습니다.

# Project Instructions

This repository contains a small Express API.

- Put route handlers in `src/api/`.
- Read the files relevant to a change before editing.
- Ask before destructive or irreversible operations; otherwise proceed when the task is clear.
- Run `npm test` before committing.
- Keep responses concise and explain non-obvious decisions.

없던 명령은 실제 npm test로 바꾸고, 상충하던 승인 규칙은 파괴적이거나 되돌리기 어려운 작업만 묻는다는 하나의 기준으로 합쳤습니다.

배포 Skill도 실행 가능한 명령과 실패 정책만 남겼습니다.

# Deploy

Run `./scripts/deploy.sh` once. If it fails, report the command output and stop.

리뷰 Agent는 고정 분량 대신 검토 결과를 명확히 했습니다.

Review the changed files for correctness, regressions, and security risks.
Cite the relevant file and line, and state uncertainty when evidence is incomplete.

수정한 명령은 감사 전에 실제로 실행했습니다.

npm test
bash scripts/deploy.sh

# tests 0
# pass 0
# fail 0
Demo deployment check passed.

테스트가 0개인 데모이므로 이 출력은 애플리케이션 품질을 증명하지 않습니다. 다만 npm test와 배포 스크립트가 존재하지 않는 명령이 아니라 실제 실행 가능한 경로라는 점은 확인합니다.

수정 후 재검사

파일을 고친 뒤 같은 버전에서 전체 감사를 다시 실행합니다.

/doctor prompt-audit

재검사 보고서는 현재 작업 트리의 세 파일을 다시 읽고 다음처럼 정리했습니다.

Group 1 (dated prompt text): 0 findings
Group 2 (brittle config files): 0 findings
Group 3 (tool descriptions): not applicable
Group 4 (request config/architecture): not applicable
Proposed diff: None

수정 전후를 숫자로 비교하면 다음과 같습니다.

재검사는 Git diff의 삭제된 줄도 문맥으로 확인했지만, 실제 세션에 로드되는 현재 작업 트리 파일을 감사 대상으로 판단했습니다. 아직 커밋하지 않은 수정이라도 디스크에 있는 현재 내용이 깨끗하면 0건으로 나옵니다.

0건이 곧 모든 지시가 완벽하다는 뜻은 아닙니다. 감사 도구는 현재 저장소에서 확인할 수 있는 충돌과 낡은 패턴을 찾습니다. 실제 팀 정책이 누락됐는지, 배포 절차가 충분한지는 사람이 별도로 검토해야 합니다.

결과가 예상과 다를 때

전용 보고서가 나오지 않음

claude --version을 먼저 확인합니다. 공식 문서 기준 2.1.283 이상이 필요합니다. 이전 버전에서는 같은 문자열을 입력해도 일반 /doctor 진단처럼 보일 수 있습니다.

bundled Skill이 꺼져 있음

공식 문서에 따르면 prompt audit는 내장 /claude-api Skill을 통해 실행됩니다. skillOverrides에서 해당 Skill을 끄거나 disableBundledSkills를 사용한 환경에서는 명령을 사용할 수 없습니다.[2]

Skills를 많이 설치해 컨텍스트를 정리한 적이 있다면 /skills나 설정 파일에서 /claude-api까지 비활성화하지 않았는지 확인합니다. Skills의 사용량과 prompt audit의 품질 검사는 서로 다른 기능입니다.

사용자 전역 파일이 결과에 없음

샌드박스나 권한 설정 때문에 ~/.claude/에 접근하지 못하면 프로젝트 파일만 검사될 수 있습니다. 보고서의 Scope 문장을 먼저 읽고 실제로 포함된 범위를 확인합니다. 필요한 경우 허용된 환경에서 사용자 경로를 명시해 별도로 실행합니다.

제안이 실제 정책과 다름

감사 결과는 근거가 있는 제안이지 정답을 강제하는 설정 마이그레이션이 아닙니다. 배포 명령, 승인 범위, 팀 규칙처럼 저장소만으로 결정할 수 없는 항목은 flag로 남기는 것이 정상입니다. 모르는 경로를 그럴듯하게 채우는 것보다 담당자가 확인한 뒤 수정하는 편이 낫습니다.

수정했는데 같은 항목이 다시 나옴

동일 문구가 다른 범위에 남아 있을 수 있습니다. 프로젝트 CLAUDE.md만 고쳤다면 다음 위치도 확인합니다.

CLAUDE.local.md
AGENTS.md
.claude/rules/
.claude/skills/
.claude/agents/
~/.claude/CLAUDE.md

먼저 경로 한정 감사로 수정한 파일을 확인하고, 마지막에 전체 감사를 실행하면 남은 출처를 찾기 쉽습니다.

정기 점검 순서

프롬프트 파일은 매 작업 전에 검사할 필요는 없습니다. 다음 시점에 한 번씩 돌리는 정도가 실용적입니다.

1. Claude Code의 주 모델 세대가 바뀐 뒤

2. 폴더 구조나 빌드·배포 명령을 크게 바꾼 뒤

3. Skills와 Agents를 여러 개 추가하거나 통합한 뒤

4. 같은 상황에서 Claude의 행동이 자주 엇갈릴 때

5. 오래된 프로젝트를 다시 시작하기 전

실행 순서는 간단합니다.

/doctor prompt-audit CLAUDE.md
/doctor prompt-audit .claude/skills
/doctor prompt-audit

범위를 좁혀 문제를 이해하고, 실제 저장소와 팀 정책을 대조해 수정한 뒤, 전체 감사로 충돌이 남았는지 확인합니다. 감사 보고서의 개수보다 왜 그 지시가 생겼고 지금도 필요한지를 확인하는 과정이 더 중요합니다.

/doctor prompt-audit는 프롬프트를 짧게 만드는 명령이 아닙니다. 현재 모델이 이미 처리할 수 있는 작업 순서는 덜어내고, 경로·명령·안전 기준처럼 프로젝트에서만 알 수 있는 사실은 더 정확하게 남기는 도구에 가깝습니다.

설치된 Skills의 컨텍스트 비용과 사용 빈도를 줄이는 작업은 Claude Code 스킬 관리: /skill-doctor로 안 쓰는 스킬과 컨텍스트 비용 줄이기에서 이어서 볼 수 있습니다. 프로젝트 지식과 응답 형식을 어디에 나눠 둘지는 Claude Code Output Styles 사용법에서 정리했습니다.

참고 자료

[1] Claude Code v2.1.283 릴리스 — /doctor prompt-audit, /checkup prompt-audit 추가
[2] Claude Code 메모리와 CLAUDE.md 공식 문서 — 감사 범위, 경로 인수, 수정 전 확인, 최소 버전 안내