예전 모델에 맞춘 지침, 이제 Claude Code가 직접 점검해줍니다

“반드시 두 번 확인해”, “CRITICAL: 절대로 빠뜨리지 마”. 예전 모델이 지시를 자주 놓치던 시절에 써둔 이런 문장이, 지금 모델에게는 오히려 불필요한 작업을 늘릴 수 있습니다.

Claude Code 2.1.283 버전에 이런 오래된 지침을 찾아주는 /checkup prompt-audit이 추가됐습니다. CLAUDE.md, 스킬, 에이전트, 커맨드 파일을 읽고 지금 모델 기준으로 손봐야 할 부분을 알려줍니다.

이미지 출처: Anthropic 공식 블로그

01. prompt-audit은 무엇을 하는 기능일까?

내가 Claude Code에 써둔 지침 파일들의 건강검진이라고 생각하면 이해하기 쉽습니다.

Claude Code를 오래 쓰다 보면 지침 파일이 계속 쌓입니다. 프로젝트마다 CLAUDE.md가 생기고, 반복 작업용 스킬과 커맨드, 특정 역할을 맡기는 에이전트 파일도 늘어납니다. 이 파일들은 대부분 작성할 당시의 모델을 기준으로 쓰였습니다.

2026년 9월 25일 공개된 2.1.283 버전 변경 내역에는 다음 내용이 추가됐습니다.

항목	내용
명령어	/doctor prompt-audit (같은 기능: /checkup prompt-audit)
점검 대상	CLAUDE.md 파일, 스킬, 에이전트, 커맨드
점검 내용	예전 모델을 위해 작성된 프롬프트 패턴
먼저 보여주는 항목	존재하지 않는 경로, 없어진 커맨드, 서로 충돌하는 지침 파일

/checkup은 설치 상태와 설정을 점검하는 /doctor의 다른 이름입니다. 여기에 지침 내용까지 점검하는 기능이 더해졌다고 보면 됩니다. 공식 변경 내역

02. 예전 지침이 왜 문제가 될까?

과거에는 AI가 지시를 놓쳐서 문제였고, 지금은 AI가 지시를 너무 충실히 따라서 문제가 됩니다.

예전 모델은 지침을 건너뛰는 일이 잦았습니다. 그래서 사람들은 대문자로 강조하고, “반드시”, “절대” 같은 표현을 붙이고, 작업 순서를 단계별로 고정했습니다.

최신 모델은 지시를 훨씬 정확하게 따릅니다. 그러면 과거의 보완책이 다르게 작동합니다.

지침	예전 모델에서	최신 모델에서
“CRITICAL: 반드시 이 도구를 써”	가끔 잊던 도구를 챙겨 씀	필요 없는 상황에서도 도구를 호출
“두 번 검증하고 답해”	대충 넘어가던 확인을 수행	이미 확인한 내용을 말 그대로 한 번 더 조회
“최대한 꼼꼼하게”	성의 없는 답변을 줄임	검색과 도구 호출이 불필요하게 늘어남

Anthropic의 공식 프롬프트 가이드도 같은 방향을 권합니다. “CRITICAL: 반드시 이 도구를 사용해야 한다”처럼 쓰던 문장을 “이럴 때 이 도구를 사용한다”처럼 평범하게 바꾸라는 것입니다. 공식 프롬프트 가이드

03. 어떤 표현을 찾아낼까?

Anthropic은 형제 기능인 /claude-api prompt-audit을 소개하며, 최신 모델의 성능을 떨어뜨리는 대표적인 패턴을 여섯 가지로 정리했습니다.

패턴	예시	최신 모델에서 생기는 일
검증 의식	“두 번 확인하고 답해”	문자 그대로 반복 확인해 토큰 낭비
강조 표현	“최대한 꼼꼼하게”, “CRITICAL: 항상…”	답변이 길어지고 도구 호출이 늘어남
고정 절차·메모 틀	“단계별로 메모장에 적으며 생각해”	모델 자체의 추론 위에 불필요한 과정이 겹침
낡은 예시	예전 모델의 실수에 맞춘 예시 답변	간단한 요청에도 긴 추론을 흉내 냄
서로 충돌하는 규칙	“규정 안이면 항상 환불” vs “승인 없이는 절대 환불 금지”	두 규칙을 모두 지키려다 판단이 흔들림
오래된 설정	예전 방식의 사고 토큰 수동 지정	새 모델에서 요청 자체가 거부될 수 있음

Claude Code용 prompt-audit은 여기에 Claude Code 환경에 맞는 점검을 더합니다. 이름을 바꾼 스크립트 경로나 이미 없어진 커맨드처럼, 지침에 적혀 있지만 실제로는 틀린 정보를 보고서 맨 앞에 보여줍니다.

다만 Claude Code 공식 문서에 나오는 사고 관련 키워드는 오래된 패턴으로 지적하지 않도록 조정됐습니다. 공식 변경 내역

04. 실제로 얼마나 차이가 날까?

Anthropic은 고객 상담 벤치마크로 Opus 4.8에서 Opus 5.5로 모델을 바꾸는 상황을 실험했습니다. 깨끗한 프롬프트에 위의 문제 패턴을 하나씩 넣은 여섯 가지 버전을 만들어 비교했습니다.

조건	결과
모델 이름만 Opus 5.5로 교체	비용 약 18% 감소 — 새 모델 단가가 더 저렴
prompt-audit으로 지침까지 정리	비용 약 9% 추가 감소, 정확도 약 2%p 상승

문제 패턴이 실제로 어떤 영향을 줬는지도 공개했습니다.

• “두 번 검증해”라는 지시 때문에 환불할 때마다 주문 조회를 중복으로 실행했습니다.
• “최대한 꼼꼼하게”라는 지시는 수십 번의 불필요한 지식 베이스 검색으로 이어졌습니다.
• 서로 충돌하는 환불 규칙 때문에 처리해야 할 환불 4건을 보류하고 고객에게 확인을 요청했습니다.
• 수동 메모장 지시가 모델의 자체 추론과 겹쳐, 3건은 도구 호출을 생각 속에만 적고 실행하지 않았습니다.

이 수치는 Anthropic이 설계한 평가에서 나온 결과입니다. 내 프로젝트에서의 개선 폭은 지침의 상태에 따라 달라집니다. Anthropic 공식 블로그

05. /claude-api prompt-audit과는 무엇이 다를까?

비슷한 이름의 기능이 두 개라 헷갈리기 쉽습니다.

구분	/claude-api prompt-audit	/checkup prompt-audit
추가 시점	2.1.221 버전	2.1.283 버전
주 용도	Claude API로 만든 앱의 프롬프트 점검	Claude Code 자체 설정 점검
점검 대상	작업 폴더의 프롬프트, 스킬, 도구 설명	CLAUDE.md, 스킬, 에이전트, 커맨드
결과	수정안을 diff로 제안	점검 보고서

Claude API로 서비스를 만드는 개발자라면 앞의 것, Claude Code를 작업 도구로 쓰는 사람이라면 뒤의 것부터 시작하면 됩니다. 공식 명령어 문서

06. 어떻게 사용하면 될까?

먼저 터미널에서 claude --version을 실행해 2.1.283 이상인지 확인합니다. 낮다면 claude update로 업데이트합니다.

prompt-audit은 현재 프로젝트가 실제로 불러오는 설정을 읽습니다. 점검하려는 프로젝트 폴더에서 Claude Code를 열고 실행합니다.

/checkup prompt-audit

보고서는 윗부분부터 읽습니다. 틀린 경로, 없어진 커맨드, 충돌하는 지침은 판단의 여지 없이 틀린 정보이므로 가장 먼저 고칩니다. 강조 표현이나 고정 절차에 대한 제안은 하나씩 읽고, 지금도 필요한 규칙인지 판단해서 반영합니다.

특히 다음과 같은 때 한 번씩 실행해보면 좋습니다.

• 새 모델로 바꿨을 때
• 스크립트나 폴더 이름을 정리했을 때
• 다른 사람이 만든 CLAUDE.md나 스킬을 가져왔을 때

적용 예시 — 원문 취지를 바탕으로 재구성

수정 전: CRITICAL: 코드를 고칠 때는 반드시 관련 파일을 전부 다시 읽고, 두 번 검증한 뒤 답해.

수정 후: 코드를 고친 뒤에는 변경한 부분의 테스트를 실행해 통과하는지 확인해.

수정 후 문장은 무엇을 확인해야 끝나는지만 알려줍니다. 얼마나 꼼꼼하게 할지는 모델에게 맡깁니다.

07. 지적받은 표현을 모두 지워야 할까?

아닙니다. prompt-audit이 찾는 것은 ’예전 모델의 약점을 메우려던 문장’이지, 모든 규칙이 아닙니다.

“배포 전에는 반드시 내 확인을 받아”처럼 작업의 경계를 정하는 규칙은 모델이 아무리 좋아져도 필요합니다. 반면 “꼼꼼하게”, “두 번 확인해”처럼 모델의 성의를 끌어내려던 문장은 정리 대상입니다.

구분이 애매하다면 다음 두 가지를 따져보면 됩니다.

확인할 점	남길 규칙	정리할 문장
무엇을 정하는가?	무엇을 할지, 어디서 멈출지	얼마나 열심히 할지
없으면 어떻게 되는가?	지금도 실제 문제가 생김	예전 모델에서만 생기던 문제

---

모델을 바꾸는 일은 설정 한 줄이면 끝나지만, 그동안 쌓아온 지침은 저절로 따라오지 않습니다. 앞서 소개한 OpenAI의 지침 재검토 가이드와 같은 흐름으로, 이제는 도구가 직접 오래된 지침을 찾아주는 단계까지 왔습니다. Claude Code를 몇 달 이상 써왔다면 한 번쯤 실행해볼 만합니다.