Opus 5.5가 덜 똑똑해 보인다면 CLAUDE.md부터 | /claude-api prompt-audit 쓰는 법
오퍼스 5.5로 바꿨는데 확인 질문이 오히려 늘거나, 결과가 전보다 딱딱하게 느껴진다면 모델보다 먼저 CLAUDE.md를 의심해 볼 만합니다.
옛 모델에 맞춰 써 둔 강조문과 금지 목록이 새 모델에서는 과하게 먹히기 때문입니다. Claude Code에 기본으로 들어 있는 /claude-api prompt-audit가 이런 문장을 찾아 줍니다.
/claude-api prompt-audit는 Claude Code에 번들된 claude-api 스킬의 점검 기능이다. CLAUDE.md, AGENTS.md, 스킬 파일, 시스템 프롬프트에서 옛 모델용 지시(과한 MUST·NEVER, "단계별로 생각해", 긴 금지 목록 등)를 찾아 보고서와 수정안(diff)을 만든다. 사용자가 요청하지 않으면 파일을 직접 고치지 않는다.스레드에서 퍼진 "오퍼스 5.5 지시 정리" 팁
국내에서는 @qjc.ai의 글이 불을 붙였습니다. "prompt-audit를 지금 실행하라, 오퍼스 5.5를 제한하는 안티패턴을 없애 준다"는 짧은 팁이었습니다.
원래 출처는 해외입니다. 랜스 마틴이 X에 이 명령을 소개하며 스킬에 최신 오퍼스 5.5 지침을 반영했다고 적었고, 이를 써 본 댄 맥아티어는 CLAUDE.md와 AGENTS.md, 스킬에서 개선점 약 70개를 찾았다고 했습니다.
댓글의 @bot.topia 제안도 눈여겨볼 만합니다. 정리 전후로 같은 이슈 5개의 재시도 횟수를 재 보면 효과가 갈린다는 것입니다. 이 글 뒤쪽의 검증 방법과 같은 이야기입니다.
옛 지시가 왜 새 모델을 방해할까
prompt-audit 원문은 이유를 이렇게 설명합니다. 최신 클로드는 예전 모델보다 지시를 더 충실하고 문자 그대로 따르기 때문에, 남아 있는 옛 지시가 그냥 낭비가 아니라 행동을 망친다는 것입니다.
예를 들어 "CRITICAL: 반드시 이 도구를 써라"는 도구를 잘 안 쓰던 옛 모델용 처방이었습니다. 지금 모델에서는 필요 없는 순간에도 도구를 부르는 과잉 반응으로 이어집니다.
앤트로픽의 오퍼스 5.5 프롬프트 가이드에도 같은 사례가 있습니다. 채팅 서비스의 시스템 프롬프트에서 "답하기 전에 신중히 생각하라"를 빼자, 답이 더 빨리 시작됐고 품질 저하는 뚜렷하지 않았다고 합니다.
prompt-audit가 찾는 대표 패턴을 우리말로 옮기면 이렇습니다.
| 이런 문장 | 이렇게 바꾼다 | 이유 |
|---|---|---|
| CRITICAL: 반드시(MUST) 이 도구를 써라 | 이런 경우 이 도구를 써라 | 강조가 과잉 호출을 부른다 |
| 꼼꼼히 해라, 게으르지 마라, 일찍 멈추지 마라 | 삭제 | 최신 모델은 기본적으로 적극적이다 |
| 가능하면 요약을 넣어라 (실제로는 필수) | 요약을 넣어라 | "가능하면"을 빼도 된다는 허락으로 읽는다 |
| 단계별로 생각해라, <scratchpad>에 적어라 | effort 설정으로 대체 | 생각의 깊이는 문장이 아니라 설정으로 조절 |
| 하지 마라·절대·피하라가 줄줄이 나열된 목록 | 실제로 재현되는 1~2개만 이유와 함께 | 없는 실수를 오히려 떠올리게 만든다 |
| 도구 3번 쓸 때마다 진행 상황을 보고하라 | 삭제 후 다시 테스트 | 현재 모델은 스스로 적절히 알린다 |
| 글머리 기호·제목 절대 쓰지 마라 | 언제 서식을 쓸지 조건으로 설명 | 옛 모델의 과한 서식을 막던 규칙이다 |
실행하는 법
별도 설치는 필요 없습니다. 공식 문서에 따르면 claude-api 스킬은 Claude Code에 기본으로 들어 있고, 슬래시 명령으로 직접 부를 수 있습니다.
- Claude Code를 최신 버전으로 올리고, 점검할 프로젝트 폴더에서 실행합니다.
- 아래처럼 명령을 입력합니다. 범위를 적으면 그 파일만, 적지 않으면 작업 폴더 전체의 프롬프트를 훑습니다.
- 결과로 나온 보고서와 수정안(diff)을 읽습니다. 항목마다 위치, 원문, 해당 패턴, 이유, 확신도가 붙습니다.
- 확신도 높은 항목부터 하나씩 적용합니다. 한 번에 다 바꾸면 무엇이 효과를 냈는지 알 수 없습니다.
/claude-api prompt-audit
# 범위를 좁히고 싶다면
/claude-api prompt-audit CLAUDE.md와 .claude/skills 폴더만 점검해 줘중요한 점 하나. 이 기능은 기본적으로 제안만 합니다. "정리해 줘"처럼 적용을 명시적으로 요청하지 않으면 파일을 건드리지 않고, 확신도가 낮은 항목은 수정안에서 빠집니다.
지우면 안 되는 것도 있다
제가 원문을 읽으며 가장 인상 깊었던 대목은 "지우지 말 것" 목록이었습니다. 무조건 짧게 만드는 게 목적이 아니라는 뜻입니다.
프로젝트의 독자, 환경, 품질 기준처럼 작성자만 아는 맥락은 쓰레기가 아닙니다. 삭제 명령이나 인증 절차처럼 순서가 하나뿐인 위험 작업의 정확한 절차도 그대로 둡니다.
도구 설명은 오히려 늘어날 수 있고, 점검 결과 아무것도 못 찾았다면 아무것도 바꾸지 않는 게 정상이라고 원문은 강조합니다.
그래서 수정안을 받은 뒤에는 꼭 확인이 필요합니다. 평소 자주 맡기는 작업 3~5개를 골라 정리 전후로 돌려 보고, 확인 질문 횟수와 재시도 횟수, 토큰 사용량을 비교하세요.
AGENTS.md를 같이 쓴다면 한 번에 정리하자
Codex나 Cursor와 번갈아 쓰는 분이라면 AGENTS.md도 점검 대상입니다. 9월 18일 나온 Claude Code 2.1.277부터 CLAUDE.md가 없는 프로젝트에서는 AGENTS.md를 대신 읽습니다.
단, CLAUDE.md가 있으면 AGENTS.md는 여전히 무시됩니다. @theaiguana처럼 "이제 CLAUDE.md에 AGENTS.md를 보라는 한 줄을 지워도 된다"는 반응도 있지만, 그건 CLAUDE.md를 아예 없앤 경우에만 맞는 말입니다.
이 동작은 /config의 프로젝트 지침 항목에서 바꿀 수 있고, Bedrock·Vertex·Foundry에서는 아직 지원되지 않습니다.
GPT-6 아스트라를 쓰는 쪽에서도 비슷한 정리 프롬프트가 돌고 있습니다. @sujung_world가 공유한 프롬프트는 불명확하거나 충돌하는 지침을 찾되, 의도적인 안전장치는 남기고 파일을 바꾸기 전에 제안부터 하라고 요구합니다.
지금 확인할 것 하나
프로젝트 폴더에서 아래 명령 한 줄만 먼저 돌려 보세요. CLAUDE.md에 대문자 강조어가 몇 개나 박혀 있는지 셉니다.
grep -cE "MUST|NEVER|ALWAYS|CRITICAL|IMPORTANT" CLAUDE.md숫자가 두 자릿수라면 prompt-audit를 돌려 볼 가치가 충분합니다. 지시 파일은 요청마다 함께 읽히니, 줄어든 만큼 매번 한도도 덜 씁니다.