Claude Code prompt-audit 사용법: CLAUDE.md 정리 기준과 실전 예시

/doctor prompt-audit은 Claude Code에서 CLAUDE.md·스킬·에이전트·명령 파일의 낡거나 충돌하는 지시를 점검하고 수정안을 제안하는 명령입니다. Claude Code v2.1.283 이상에서 사용할 수 있습니다. Claude Code 공식 점검 안내

“꼼꼼하게 확인해.” “반드시 지켜.” “끝나면 처음부터 다시 검토해.”

Claude Code가 실수할 때마다 이런 문장을 하나씩 추가해 본 적 있으신가요? 처음에는 도움이 됐어도, 모델과 프로젝트가 달라진 뒤까지 같은 지시가 필요한지는 다시 살펴볼 만합니다. 검사를 더 하라는 말이 쌓이는 동안, 정작 무엇을 검사하면 작업이 끝나는지는 빠져 있을 수 있거든요.

이 글에서는 명령 실행에서 한 걸음 더 나아가, 제안을 받아들일 기준과 수정 후 확인 방법까지 다룹니다. 예시와 복사용 프롬프트는 쇼핑몰 프로젝트를 가정해 새로 구성했습니다.

prompt-audit은 무엇을 점검하나요?

CLAUDE.md는 Claude Code에 프로젝트의 배경과 작업 규칙을 전달하는 파일입니다. 예를 들어 사용하는 패키지 매니저, 수정하면 안 되는 생성 파일, 완료 여부를 확인할 명령을 적을 수 있습니다. 처음 설정한다면 CLAUDE.md·Skills·Agents·Hooks 폴더 설정 가이드를 함께 보세요.

/doctor prompt-audit은 이 지시들이 지금도 맞는지 검토합니다. 경로를 생략하면 CLAUDE.md·CLAUDE.local.md·AGENTS.md와 .claude/ 및 ~/.claude/ 아래의 규칙·스킬·명령·하위 에이전트·출력 스타일이 기본 점검 범위에 포함됩니다. 개인 설정까지 범위가 넓어질 수 있으므로, 이 글에서는 CLAUDE.md 경로를 지정해 시작합니다. 기본 점검 범위

기본 결과물은 점검 리포트와 수정 미리보기입니다. diff는 삭제할 줄과 추가할 줄을 표시하는 변경안입니다. 리포트에는 파일 위치, 문제로 본 문장, 이유, 확신 수준, 권장 조치가 담깁니다. Anthropic 공식 prompt-audit 절차

여기서 한 가지를 구분해야 합니다. 점검 대상에 포함되는 것과 평소 Claude Code가 자동으로 읽는 것은 별개입니다. 특정 지시 파일을 평소에 읽는지는 버전과 설정, 파일 위치에 따라 달라집니다. Claude Code 메모리 문서

/doctor prompt-audit과 /claude-api prompt-audit은 어떻게 다른가요?

기존 명령이 폐지된 것은 아닙니다. v2.1.283에서 지시 파일 점검을 위한 /doctor prompt-audit 진입점이 추가됐으며, 내부적으로 내장 /claude-api 스킬을 통해 실행됩니다.

이 글의 실습은 지시 파일 점검에 맞춰 /doctor prompt-audit으로 통일합니다. [path]는 선택할 파일이나 폴더 경로라는 뜻이며 대괄호를 그대로 입력하지 않습니다. 공식 명령 목록, v2.1.283 릴리스 노트

일반 터미널의 claude doctor는 설치 진단입니다. Claude Code 대화창의 /doctor는 환경 점검이며, 여기에 prompt-audit을 붙여야 지시 파일 점검을 실행합니다.

왜 잘하라고 쓴 지시가 오히려 방해될까요?

예를 들어 주문 취소 기능을 수정하는데 지시 파일에 이렇게 적혀 있다고 해 봅시다.

- 실수하면 안 된다. 모든 결과를 두 번씩 확인한다.
- 사소한 수정도 가능한 모든 대안을 조사한 뒤 시작한다.
- 어떤 작업이든 전체 코드를 다시 검토한다.

문제는 의도보다 범위와 종료 조건이 흐리다는 점입니다. 버튼 문구 하나를 고치는 일과 결제 금액 계산을 바꾸는 일에 같은 절차가 적용됩니다.

Anthropic은 최신 모델이 낡은 재확인 지시나 과도한 강조를 문자 그대로 따라, 불필요한 추론과 도구 호출을 할 수 있다고 설명합니다. 그렇다고 검증 자체를 없애라는 뜻은 아닙니다. Anthropic 비용·성능 개선 사례

독자가 바로 적용할 수 있는 원칙은 이것입니다.

“얼마나 열심히 할지” 대신 “어떤 조건을 충족해야 끝난 것인지”를 적어 보세요.

예를 들어 “두 번 확인해”보다 “주문 금액 계산을 바꾸면 쿠폰·배송비 경계값 테스트를 실행하고 결과를 보고해”가 이 프로젝트의 의도를 더 명확하게 전달합니다.

비용 9% 감소라는 숫자는 어떻게 나온 건가요?

Anthropic은 고객지원 벤치마크에서 낡은 패턴을 하나씩 넣은 프롬프트 6개를 비교했습니다. 실험에는 반복 확인뿐 아니라 충돌하는 환불 규칙, 오래된 설정 등도 포함됐습니다.

이 실험에서 사용한 명령 표기는 /claude-api prompt-audit입니다. /doctor prompt-audit에 대해 새로 측정한 결과가 아닙니다.

따라서 쇼츠에서 소개한 “같은 모델인데 비용은 줄고 정확도는 올랐다”는 두 번째 비교에 해당합니다. 정확도 2%p는 예컨대 90%에서 92%로 오르는 차이를 뜻합니다.

이 수치는 특정 실험의 평균입니다. 개인의 CLAUDE.md를 정리하면 구독료가 9% 내려간다는 의미도, “두 번 확인해” 한 줄만 지우면 같은 성과가 난다는 의미도 아닙니다. 실험 조건과 결과 원문

실행 전에 정할 것: 지울 문장보다 남길 기준

처음부터 “쓸데없는 지시를 전부 삭제해 줘”라고 요청하면, 프로젝트에 필요한 규칙까지 한꺼번에 바뀔 수 있습니다. 먼저 아래처럼 판단 기준을 세워 두세요. 다음 표는 이 글에서 제안하는 실무용 분류입니다.

문장에 이유가 없다고 곧바로 삭제하지 마세요. 이유를 생략했을 뿐 중요한 규칙일 수도 있습니다. 특히 데이터 삭제, 배포, 인증, 결제처럼 잘못 바꾸면 영향이 큰 규칙은 담당자나 실제 코드에서 필요성을 확인하는 편이 좋습니다.

중복 문장도 마찬가지입니다. 서로 다른 상황에서 각각 필요한 규칙일 수 있으므로, 같은 말이 두 번 보인다는 이유만으로 합치지 않습니다.

Claude Code에서 prompt-audit 실행하기

1. 버전과 원본을 확인합니다

먼저 일반 터미널에서 버전을 확인합니다.

claude --version

이 글에서 사용하는 /doctor prompt-audit의 최소 버전은 v2.1.283입니다. 낮다면 설치 방식에 맞게 업데이트하세요. 네이티브 설치 등 자체 업데이트를 지원하는 방식에서는 다음 명령을 사용합니다. Homebrew·WinGet 등으로 설치했다면 해당 패키지 매니저의 업데이트 방법을 따릅니다. Claude Code 업데이트 안내

claude update

점검할 프로젝트 폴더로 이동한 뒤 원본을 보관합니다. macOS·Linux에서는 기존 CLAUDE.md가 있는 위치에서 아래처럼 날짜와 시간을 붙여 복사할 수 있습니다.

cp CLAUDE.md "CLAUDE.md.before-audit-$(date +%Y%m%d-%H%M%S)"

Windows에서는 파일 탐색기로 복사본을 만들어도 됩니다. 여러 규칙 파일까지 수정할 예정이라면 그 파일들도 함께 보관하세요. Git을 사용한다면 현재 미커밋 변경이 무엇인지 먼저 확인해 두면 좋습니다.

git status --short
git diff -- CLAUDE.md
git diff --cached -- CLAUDE.md

이제 프로젝트 폴더에서 Claude Code를 실행합니다.

claude

2. 첫 점검은 CLAUDE.md 하나로 시작합니다

다음은 터미널 명령이 아니라 Claude Code 대화 입력창에 넣는 명령입니다.

/doctor prompt-audit CLAUDE.md

처음에는 파일 하나만 지정하면 결과를 읽기 편합니다. 위의 기본 명령과 아래 복사용 프롬프트 중 하나를 골라 실행하면 됩니다.

prompt-audit은 Claude가 지침에 따라 작업하는 스킬입니다. 모든 환경에서 같은 결과를 내는 고정된 검사기는 아니며, 공개 저장소의 최신 절차와 설치 버전에 포함된 절차가 다를 수 있습니다.

검토 전에 파일이 바뀌지 않도록, 아래 요청을 명령과 함께 입력하는 것을 권합니다. 대괄호 부분에는 지시를 실제로 사용할 대상 모델을 넣으세요. 이 글처럼 CLAUDE.md를 점검한다면 평소 프로젝트에서 쓰는 모델입니다. 현재 세션 모델은 /status로 확인할 수 있습니다. 기준 모델을 글로 적는 것과 세션 모델을 변경하는 것은 별개입니다. Claude Code 모델 설정

복사용 프롬프트 — 수정 없이 진단받기

/doctor prompt-audit CLAUDE.md

이 지시를 사용할 기준 모델은 [실제 대상 모델 이름]이야.
이번에는 CLAUDE.md만 점검해 줘.
사실 확인에 필요한 프로젝트 코드는 관련 부분만 읽고 수정하지 마.
백업 파일, 자격 증명, .env, .mcp.json, .claude/settings*.json은 읽지 마.
파일을 수정하지 말고 리포트와 제안 diff만 보여 줘.

시작할 때 점검 대상 파일과 기준 모델을 밝혀 줘.
각 제안에는 번호, 파일·줄 번호, 원문, 근거, 확신 수준을 붙여 줘.
삭제했을 때 사라지는 프로젝트 규칙도 설명해 줘.
현재 코드나 공식 문서에서 확인하지 못한 근거는 그렇게 표시해 줘.

리포트의 기준 모델과 실제 점검 파일 목록을 확인하세요. 이 예시에서는 CLAUDE.md만 지정했습니다. 경로 없이 /doctor prompt-audit을 실행하면 ~/.claude/의 개인 지침도 기본 범위에 포함됩니다. 공식 점검 범위 안내

3. 리포트는 확신 수준보다 근거부터 읽습니다

High·Medium·Low는 제안의 근거 수준입니다. High라고 해서 삭제해도 안전하다는 보증은 아닙니다. 실제 프로젝트에서 유지할 필요가 있는지는 별도로 판단해야 합니다.

공식 절차의 확신 수준은 다음처럼 읽습니다.

flag도 자동 삭제 표시가 아닙니다. 근거가 부족하거나 안전 규칙과 충돌하는 등 바로 고칠 수 없는 항목을 알리는 표시입니다. 리포트·수정안 기준

다음은 공식 출력 형식의 재현이 아니라, 제안을 읽으며 작성할 수 있는 검토 메모 예시입니다.

특히 “최신 모델은 알아서 한다”는 설명만 있고, 내 프로젝트에서 어떤 행동이 중복되는지 설명이 없다면 추가 근거를 요청하세요.

1번 제안의 근거를 더 구체적으로 설명해 줘.
이 지시가 막으려던 오류와, 삭제 후 그 오류를 확인할 방법을 알려 줘.
반복 작업이 실제로 관찰된 것인지 가능성만 있는 것인지 구분해 줘.
아직 파일은 수정하지 마.

CLAUDE.md 수정 예시 4가지

아래는 가상의 쇼핑몰 프로젝트를 위한 예시입니다. 명령과 경로는 독자의 프로젝트에 실제로 존재하는지 확인한 뒤 사용하세요. 코드와 테스트는 그대로 두고 지시만 바꾼 예시입니다.

예시 1. “반드시 두 번 확인”을 실패 조건으로 바꾸기

수정 전

- 결과를 반드시 두 번 확인하고 문제가 없을 때까지 다시 검토한다.

수정 후

- 주문 금액 계산을 바꾸면 쿠폰·배송비·반올림 테스트를 실행한다.
- 테스트가 실패하거나 실행되지 않으면 완료로 보고하지 않는다.
- 통과한 검사는 변경 사항·환경 변화·불안정한 테스트 등 재검사 이유가 있을 때 반복한다.

수정 미리보기는 다음처럼 읽으면 됩니다. -는 삭제할 줄, +는 추가할 줄입니다.

- 결과를 반드시 두 번 확인하고 문제가 없을 때까지 다시 검토한다.
+ 주문 금액 계산을 바꾸면 쿠폰·배송비·반올림 테스트를 실행한다.
+ 테스트가 실패하거나 실행되지 않으면 완료로 보고하지 않는다.
+ 통과한 검사는 변경 사항·환경 변화·불안정한 테스트 등 재검사 이유가 있을 때 반복한다.

검사 횟수를 늘리는 대신, 놓치면 안 되는 조건과 재검사가 필요한 시점을 적었습니다. 금액 계산처럼 틀렸을 때 영향이 큰 부분의 검증은 그대로 남습니다.

예시 2. “절대로 수정 금지”에 대상과 이유 넣기

수정 전

- 중요!!! 자동 생성 파일은 절대로 건드리지 마!!!

수정 후

- src/generated/는 스키마에서 생성되는 파일이다.
- 타입을 변경할 때는 원본 스키마를 수정하고 npm run generate를 실행한다.
- 생성 파일을 직접 편집하면 다음 생성 과정에서 변경이 사라지므로 직접 수정하지 않는다.

금지 자체는 유효합니다. 어떤 파일이 대상인지, 변경이 필요하면 어디로 가야 하는지까지 알려 주면 작업이 막히는 상황을 줄일 수 있습니다.

예시 3. 사소한 변경에 붙은 전체 점검 절차 줄이기

수정 전

- 모든 작업 전에 전체 폴더와 문서를 읽는다.
- 가능한 구현 방식을 모두 비교한 뒤 계획을 작성한다.
- 코드를 고치고 전체 테스트를 두 번 실행한다.

수정 후

- 변경할 기능과 연결된 코드·테스트·프로젝트 규칙을 먼저 확인한다.
- 여러 기능에 영향을 주는 변경은 영향 범위와 검증 계획을 먼저 정리한다.
- 단순 문구 변경은 해당 화면을 확인한다.
- 주문·결제 로직 변경은 관련 테스트와 빌드를 확인한다.

여기서는 작업의 영향 범위에 맞춰 확인 강도를 조절했습니다. 반면 백업 → 마이그레이션 → 결과 검증처럼 순서 자체가 중요한 운영 절차는 유지해야 합니다.

예시 4. 서로 충돌하는 완료 기준 정리하기

수정 전

- 테스트가 실패하면 작업을 끝내지 않는다.
- 테스트가 깨져 있어도 사용자에게 완료했다고 짧게 보고한다.

수정 후

- 테스트 결과를 통과·실패·미실행으로 구분해 보고한다.
- 기존 실패와 이번 변경으로 생긴 실패를 구분한다.
- 요청한 기능이 동작해도 필수 검증이 끝나지 않았다면 그 상태를 함께 알린다.

이 경우에는 표현을 부드럽게 바꾸는 것보다 어떤 상태를 완료라고 부를지 합의하는 것이 먼저입니다. 어느 규칙이 현재 팀의 기준인지 모르면 임의로 한쪽을 지우지 않습니다.

필요한 항목만 적용하고 효과 확인하기

검토가 끝났다면 번호로 적용 범위를 정하세요. 아래는 예시이므로 실제 리포트 번호로 바꿔 사용합니다. Low·flag 항목은 선택하지 말고, 먼저 필요한 근거와 담당자의 판단을 보충하세요.

복사용 프롬프트 — 선택한 변경만 적용하기

리포트의 1번과 2번만 CLAUDE.md에 적용해 줘.
나머지 항목과 다른 파일은 수정하지 마.
새로운 수정이 필요하면 적용하지 말고 별도 제안으로 남겨 줘.

적용 후 최종 diff와 남아 있는 주의점을 보여 줘.
운영 DB 접근 제한, 검증 실패 보고 기준이 보존됐는지도 확인해 줘.

Git에서 추적 중인 파일이라면 터미널에서도 변경 내용을 볼 수 있습니다. 첫 번째 명령은 아직 스테이징하지 않은 변경, 두 번째는 스테이징한 변경을 보여 줍니다.

git diff -- CLAUDE.md
git diff --cached -- CLAUDE.md

두 결과에는 점검 전부터 있던 변경도 섞일 수 있습니다. 이번 점검으로 바뀐 부분만 보려면 보관한 원본과 비교하세요. Git이 추적하지 않는 새 파일도 원본과 직접 비교해야 합니다. Git diff 공식 문서

전후 비교는 같은 과제로 합니다

지시가 짧아졌다는 사실만으로 개선을 판단하지 마세요. 같은 작업을 맡겼을 때 필요한 결과를 더 적은 낭비로 얻는지가 기준입니다.

수정 전후에 각각 새 세션을 열고, 같은 모델·설정·작업 시작 상태에서 비교하는 편이 좋습니다. 이전 작업으로 코드가 이미 고쳐진 상태라면 공정한 비교가 어려우므로, 별도 복사본이나 동일한 Git 기준점을 사용하세요.

작업 성공 여부를 먼저 보고, 그다음 소요 시간·도구 호출·사용량을 비교하세요. 비용을 비교할 때는 캐시 사용 여부도 기록하고, 점검 자체에 든 사용량과 이후 반복 작업에서 줄어든 사용량을 구분하세요. 한 번의 실행은 우연한 차이가 클 수 있으니 중요한 변경은 같은 조건에서 몇 차례 확인하는 것이 좋습니다. 아래 프롬프트의 평가는 보조 수단입니다. 실제 테스트 결과와 변경 내용을 직접 확인하세요.

복사용 프롬프트 — 비교 기록 평가하기

아래 수정 전·후 작업 기록을 비교해 줘.

[수정 전 기록]
여기에 작업 결과와 검증 결과를 붙여 넣기

[수정 후 기록]
여기에 같은 과제의 결과와 검증 결과를 붙여 넣기

1. 요청한 기능과 필수 검증의 성공 여부를 먼저 비교해 줘.
2. 반복 검색·검사·불필요한 파일 수정이 줄었는지 확인해 줘.
3. 규칙 누락으로 새로 생긴 문제를 찾아 줘.
4. 기록에 없는 비용이나 토큰 수는 추정하지 마.
5. 유지할 변경과 되돌릴 변경을 근거와 함께 제안해 줘.

되돌릴 때도 파일 전체를 덮어쓰기 전에 다른 작업이 섞였는지 확인하세요. 문제를 만든 항목만 복구하면, 나머지 개선을 유지하기 쉽습니다.

바로 응용하는 CLAUDE.md 예시

아래 템플릿은 TypeScript 쇼핑몰에서 Vitest를 사용하고, package.json의 test 스크립트가 vitest인 경우를 가정합니다. build와 generate 스크립트도 프로젝트에 있어야 합니다.

npm test -- --run의 --run은 Vitest에 전달되어 테스트를 한 번 실행하게 합니다. 모든 테스트 도구에 통하는 옵션은 아니므로 다른 도구를 쓴다면 해당 프로젝트의 명령으로 바꾸세요. 기존 파일을 통째로 바꾸기보다 필요한 부분만 가져오세요. npm test 문서, Vitest 실행 옵션

# 프로젝트 배경
- 고객이 상품을 주문하고 취소할 수 있는 TypeScript 쇼핑몰이다.
- 금액은 원 단위 정수로 계산하며 쿠폰 적용 뒤 배송비를 더한다.

# 작업 환경
- 패키지 매니저는 npm이다.
- 테스트 도구는 Vitest이며 package.json의 test 스크립트는 vitest다.
- 빌드: npm run build
- 테스트: npm test -- --run
- 타입 생성: npm run generate

# 변경 기준
- 주문·결제 로직은 관련 테스트와 빌드로 검증한다.
- 단순 문구 변경은 해당 화면의 표시를 확인한다.
- src/generated/는 직접 수정하지 않고 원본 스키마에서 다시 생성한다.

# 운영 제약
- 로컬 검증에는 테스트 데이터를 사용한다.
- 운영 DB의 변경·삭제는 승인된 별도 절차를 따른다.
- 주문 취소 요청이 반복돼도 재고는 한 번만 복구한다.

# 결과 보고
- 변경 내용과 실행한 검증을 간단히 정리한다.
- 검증 결과는 통과·실패·미실행을 구분한다.
- 남은 문제가 있으면 완료 여부와 함께 명시한다.

운영 DB 보호는 지시 파일에만 맡기지 마세요. 실제 데이터베이스 접근 권한과 Claude Code의 도구 권한도 별도로 제한해야 합니다. Claude Code 권한 설정

핵심은 문장 수가 아닙니다. 프로젝트 배경, 실행 방법, 완료 조건, 운영 제약이 실제 작업에 맞게 적혀 있는지 확인하세요. 파일 구성부터 정리하고 싶다면 Claude Code 프로젝트 설정 예시로 이어서 학습할 수 있습니다.

자주 묻는 질문

오늘은 한 파일, 한 가지 변경부터

CLAUDE.md를 열고 “잘해 줘”라는 문장 옆에 무엇이 성공인지 적혀 있는지 확인해 보세요. 적혀 있지 않다면 그 부분이 첫 점검 대상입니다.

/doctor prompt-audit CLAUDE.md로 진단을 받고, 근거를 이해한 변경 하나만 적용한 뒤 같은 작업을 다시 맡겨 보세요. 필요한 규칙은 보존하면서 불필요한 행동이 줄었다면, 그때 다른 스킬과 규칙 파일로 범위를 넓히면 됩니다.

공식 자료 확인 기준: 2026년 10월 8일. /doctor prompt-audit과 기존 /claude-api prompt-audit의 지원 버전·기본 범위를 구분해 반영했습니다. 명령의 세부 동작은 버전에 따라 달라질 수 있습니다. 본문의 검토 메모·쇼핑몰 코드 블록·비교 과제는 이해를 돕기 위한 예시이며, 직접 측정한 벤치마크 결과가 아닙니다.