721 ／ 733
Opus 5.5에 맞게 CLAUDE.md와 스킬을 점검하는 prompt-audit 명령
앤트로픽의 Lance Martin이 X에 클로드 Opus 5.5를 더 잘 쓰는 요령을 하나 올렸다. 클로드 코드에서 /claude-api prompt-audit를 실행하라는 것이다. 이 명령은 스킬, CLAUDE.md, 프롬프트 같은 기존 지시문을 최신 모델 기준으로 점검하고, 바꿀 부분을 보고서와 diff로 제안한다. 파일을 직접 고치지는 않는다. 사용자가 명시적으로 요청할 때만 수정한다.
화제가 된 게시물과 실제 동작
Lance Martin의 게시물은 이 명령이 스킬, agent.md, CLAUDE.md, 프롬프트를 살펴 최신 모델의 발목을 잡는 안티패턴을 걷어 낸다고 소개했다. 자신이 Opus 5.5의 최신 지침을 반영해 스킬을 업데이트했다는 말도 덧붙였다. 이 게시물은 공개된 그 주에 조회수 20만 회를 넘기며 화제가 됐다.
wmedia.es는 2026년 9월 25일 이 명령을 직접 돌려 본 리뷰를 냈다. 리뷰어는 명령이 실제로 있고 제대로 동작한다고 확인했다. 다만 두 가지를 바로잡았다. 이 명령은 아무것도 지우지 않는다. 그리고 새 기능도 아니다. 클로드 코드 v2.1.221에 이미 들어 있었다. 리뷰어는 v2.1.282에서 Opus 5.5로 세 번 실행해 실제 동작을 확인했다.
명령이 일하는 순서
/claude-api는 클로드 코드에 기본으로 들어 있는 스킬이고, prompt-audit는 그 하위 명령이다. 실행하면 클로드가 약 39KB 분량의 내부 가이드(shared/prompt-audit.md)를 불러와 다음 순서로 작업한다.
- 텍스트로 모델에 전달되는 모든 것을 목록으로 만든다.
CLAUDE.md,SKILL.md, 규칙 파일, 도구 설명이 대상이고, 코드가 API를 호출한다면 요청을 만드는 코드도 포함한다. - git 기록이 있으면
git blame을 실행해 강조 표현이 들어간 줄이 언제, 왜 추가됐는지 확인한다. - 모든 지시에 “모델이 이미 이걸 알고 있는가?”라는 질문을 하나씩 던진다.
- 발견 사항마다 위치(
file:line), 정확한 원문, 해당 패턴, 낡았다고 보는 이유, 신뢰도를 적은 보고서와 변경 제안을 담은 diff를 건넨다.
가이드는 마지막 단계에 대해 분명하게 적어 둔다. 제안만 하고, 사용자 동의 없이는 적용하지 않는다. 파일 수정은 사용자의 요청에 수정 지시가 명시적으로 들어 있을 때만 한다. 리뷰어가 세 번 실행하는 동안 바뀐 파일은 하나도 없었다(저장소를 점검할 때는 편집 도구도 빼 두었다).
짚어 내는 패턴
명령이 지적하는 대표 패턴과 제안은 다음과 같다.
| 기존 지시 | 제안 |
|---|---|
CRITICAL: YOU MUST ALWAYS..., IMPORTANT!!! |
같은 규칙을 평범한 어조로 쓰고 이유를 붙인다 |
Think step by step, <scratchpad>, <thinking> |
지운다. 추론 깊이는 effort가 정한다 |
Be thorough. Don't stop early. |
지운다. 지금 모델은 기본으로 그렇게 한다 |
| 판단이 필요한 일에 번호 붙인 단계 | 목표와 확인 방법을 설명한다 |
| 예시 답변 하나 | 지우거나, 예시임을 밝힌 여러 개를 준다 |
| 서로 충돌하는 두 규칙 | 하나로 다시 쓴다 |
가이드가 드는 이유는 이렇다. 지금 모델은 그 지시문이 처음 겨냥했던 모델보다 지시를 더 글자 그대로 따른다. 말을 안 듣던 모델을 위해 대문자로 쓴 규칙이 이제는 과하게 적용된다. 그리고 모든 것이 중요하면 아무것도 중요하지 않다.
Opus 5.5에 대해서는 가이드가 두 가지를 따로 짚는다. 이 모델은 생각하기가 늘 켜져 있어서, 더 생각하라거나 덜 생각하라는 문장은 아무것도 조절하지 못한다. 조절 손잡이는 effort 하나뿐이다. 또 답변에 추론 과정을 드러내라고 요구하면 거부(reasoning_extraction)가 나올 수 있다.
건드리지 않는 것
가이드에는 패턴에 걸리더라도 지적하지 않는 항목 목록이 있다. 이 목록 덕분에 이 명령은 단순히 프롬프트를 짧게 줄이는 도구가 되지 않는다.
- 맥락. 제품, 환경, 규칙을 둔 이유처럼 모델이 다른 곳에서는 얻을 수 없는 정보다.
- 위험한 작업의 정확한 절차. 파괴적인 명령, 배포, 인증 흐름이 여기에 든다.
- 아직 제 몫을 하는 금지 규칙. 현재 모델에서도 그 실패가 재현되면 규칙은 남긴다.
- 문제없는 파일. 찾은 게 없으면 아무것도 바꾸지 않는다.
세 번 돌려 본 결과
리뷰어는 Opus 5.5에서 claude -p로 세 번 실행했다. 비용은 API 정가 기준 total_cost_usd 값이다.
| 점검 대상 | 발견 | 변경 제안 | 시간 | 비용 |
|---|---|---|---|---|
테스트 프로젝트(나쁜 습관을 전부 넣은 CLAUDE.md 1개와 스킬 1개) |
8 | 7 | 2분 14초 | $2.11 |
리뷰어의 스킬 저장소(SKILL.md 14개와 참조 파일) |
16 | 11 | 5분 39초 | $5.10 |
리뷰어의 전역 ~/.claude/CLAUDE.md |
5 | 4 | 2분 22초 | $1.28 |
테스트 프로젝트에서는 일부러 심어 둔 문제를 모두 잡아냈다. “답변은 3줄 이내로”와 “모든 변경을 근거와 함께 자세히 설명하라”가 부딪히는 것도 찾았다. 이유가 붙은 규칙 하나, “묻지 않고 테스트를 실행하지 말 것”은 그대로 두었다.
스킬 저장소는 결과가 달랐다. 애초에 “think step by step”도, 대문자를 늘어놓은 규칙도 없었다. 신뢰도가 높은 발견은 하나뿐이었는데, 더는 존재하지 않는 폴더를 가리키는 검증 경로였다. 문체 습관이 아니라 망가진 절차였다. 나머지는 어긋나 버린 참조, 바로 다음 문장이 뒤집어 버리는 규칙, 그리고 Opus 5.5를 과잉 점검으로 모는 “시간과 토큰은 제약이 아니다”라는 문장이었다. 게시 전 승인 절차는 모두 그대로 남았다.
전역 파일에서는 가장 엄격한 규칙(승인 없이 커밋 금지)을 문장에만 맡기지 말고 settings.json의 ask 권한 규칙으로 옮기라는 제안이 핵심이었다.
쓰는 방법
첫째, 프로젝트 루트에서 실행한다.
/claude-api prompt-audit
인자 없이 실행하면 작업 디렉터리 전체를 점검한다. 사용자 전역 설정인 ~/.claude/CLAUDE.md는 기본 범위에 들어가지 않는다.
둘째, 파일 하나를 지정할 수도 있다.
/claude-api prompt-audit ~/.claude/CLAUDE.md
경로를 주면 그 파일만 점검 범위가 된다. 리뷰어가 이렇게 실행했을 때는 프로젝트 자체의 CLAUDE.md에 나쁜 습관이 남아 있어도 건드리지 않고 끝에 언급만 했다.
셋째, diff보다 보고서를 먼저 읽는다. 보고서는 어떤 모델을 기준으로 삼았는지, 어떤 파일이 범위에 들어갔는지 같은 전제부터 밝힌다. 발견 사항은 신뢰도순으로 정렬되고, 신뢰도가 낮은 항목은 보고서에만 남고 diff에는 들어가지 않는다.
넷째, 납득한 변경만 적용한다. diff는 별도 파일이나 보고서 안에 담겨 오고, 어느 부분을 반영할지는 사용자가 고른다. 명령은 적용 결과를 테스트하지 않는다. 평가(eval)가 없으면 모든 변경은 가설일 뿐이라고 보고서도 밝히고, 변경 전후를 비교해 보라고 권한다.
언제 돌리나
모델을 바꿀 때마다 돌리면 된다. 가이드의 설명대로 프롬프트는 특정 모델에 묶여 있고, 한 세대에서 무언가를 받쳐 주던 문장이 다음 세대에서는 짐이 된다.
/doctor와는 다른 명령이다. /doctor는 비대해진 CLAUDE.md와 클로드가 코드만 보고도 알아낼 수 있는 내용을 찾는다. prompt-audit는 이제 쓰지 않는 모델을 위해 써 둔 지시를 찾는다.
출처
- Lance Martin, X 게시물. https://x.com/RLanceMartin/status/2102575471502528989
- wmedia.es, 「/claude-api prompt-audit: your CLAUDE.md and skills, optimized for Opus 5.5」(2026-09-25). https://wmedia.es/en/tips/claude-code-prompt-audit-claude-md