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에 기본으로 들어 있고, 슬래시 명령으로 직접 부를 수 있습니다.

1. Claude Code를 최신 버전으로 올리고, 점검할 프로젝트 폴더에서 실행합니다.
2. 아래처럼 명령을 입력합니다. 범위를 적으면 그 파일만, 적지 않으면 작업 폴더 전체의 프롬프트를 훑습니다.
3. 결과로 나온 보고서와 수정안(diff)을 읽습니다. 항목마다 위치, 원문, 해당 패턴, 이유, 확신도가 붙습니다.
4. 확신도 높은 항목부터 하나씩 적용합니다. 한 번에 다 바꾸면 무엇이 효과를 냈는지 알 수 없습니다.

/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를 돌려 볼 가치가 충분합니다. 지시 파일은 요청마다 함께 읽히니, 줄어든 만큼 매번 한도도 덜 씁니다.