CLAUDE.md 점검 명령 — 옛 모델용 강조 문구가 과잉 반응을 부름

예전 모델에게 도구를 쓰게 하려고 「반드시」, 「꼭」, 「애매하면 일단」을 적어 두셨다면, 지금 모델은 그 말을 너무 잘 듣습니다. 클로드 코드에 그런 문구를 찾아 주는 점검 명령이 생겼습니다.

9월 하순에 나온 2.1.283판에서 진단 명령에 지시문 점검 기능이 붙었습니다. 프로젝트 지침 파일과 스킬, 에이전트, 명령 정의를 훑어서, 이전 세대 모델에 맞춰 써 둔 지시 패턴을 짚어 줍니다. 몇 달 전에 공들여 쓴 지침일수록 한 번 돌려 볼 만한데, 이유는 앤트로픽의 프롬프트 작성 가이드에 꽤 분명하게 적혀 있습니다.

짧게 정리하면

• 진단 명령 뒤에 지시문 점검을 붙이면 지침 파일·스킬·에이전트·명령에서 옛 모델용 표현을 찾아 보고합니다.
• 지금 모델은 지시를 더 충실히 따르기 때문에, 예전에 모자란 반응을 끌어올리려던 강한 표현이 이제는 과한 반응을 부릅니다.
• 보고서 앞쪽에는 없어진 경로·명령과 서로 어긋나는 지침 파일이 먼저 오고, 문서에 적힌 사고 유도 키워드는 지우지 않고 남깁니다.

변경 기록 2.1.283의 두 항목, 명령어 문서의 진단 명령 설명, 공식 프롬프트 작성 가이드를 대조했습니다. 점검기가 찾는 패턴의 전체 목록은 문서에 없어서, 가이드가 직접 짚은 예만 옮겼습니다.

무엇을 찾아 주나

부르는 법은 진단 명령 뒤에 지시문 점검을 붙이는 것이고, 진단 명령의 별칭인 점검 명령으로도 됩니다. 대상은 네 가지입니다. 프로젝트 지침 파일, 스킬, 에이전트 정의, 사용자 명령입니다. 한 곳에 적은 지시가 여러 곳에 흩어져 있는 경우가 많으니, 파일 하나만 보는 것보다 이렇게 한 번에 훑는 쪽이 빠릅니다.

같은 판에서 보고서 순서도 손봤습니다. 옛 모델용 문장보다 더 급한 문제가 먼저 나오도록 바뀌었습니다.

2.1.283 변경 기록 기준, 보고서에서 먼저 짚는 것

항목	왜 앞에 오나
이미 없는 경로	옮긴 폴더를 가리키면 모델이 헛걸음을 함
이미 없는 명령	바뀐 빌드·시험 명령을 계속 시도함
서로 어긋나는 지침 파일	어느 쪽을 따를지 모델이 매번 다르게 고름
옛 모델용 표현	동작은 하지만 과하게 반응하게 만듦

셋째 줄은 요즘 특히 생기기 쉽습니다. 클로드 코드가 여러 도구가 함께 쓰는 공용 지침 파일까지 직접 읽게 된 뒤로, 개인 파일·공용 파일·하위 폴더 파일이 한꺼번에 실리는 일이 늘었습니다. 한쪽에는 「시험은 매번 전부 돌려라」, 다른 쪽에는 「바뀐 파일의 시험만 돌려라」가 적혀 있는 식입니다.

옛 표현이 왜 문제가 되나

앤트로픽 가이드의 설명은 이렇습니다. 최근 모델은 이전보다 시스템 지시에 더 민감하게 반응합니다. 그래서 예전에 도구를 잘 안 쓰던 모델을 움직이려고 넣은 강한 문장이 지금은 도구를 지나치게 자주 쓰게 만듭니다. 가이드가 직접 드는 해법은 공격적인 말투를 누그러뜨리라는 것입니다.

공식 프롬프트 작성 가이드의 예를 우리말로 옮김

예전에 쓰던 말	지금 권하는 말
중요: 이럴 때는 반드시 이 도구를 써야 한다	이럴 때 이 도구를 쓴다
애매하면 일단 이 도구를 써라	문제를 이해하는 데 도움이 될 때 쓴다
더 철저하게, 빠짐없이 조사하라	부추기는 문장을 줄이고 필요하면 노력 수준을 낮춤
생각할 분량을 숫자로 못 박음	노력 수준으로 조절, 최근 모델에서 고정 값은 오류

셋째 줄이 체감으로 가장 큽니다. 가이드는 요즘 모델이 시키지 않아도 먼저 더 많이 살펴본다고 적고 있습니다. 여기에 「빠짐없이」를 얹으면 파일을 필요 이상으로 열고, 답이 늦어지고, 토큰이 늘어납니다. 공개된 AI 지시문에서 어떤 말을 피하는지 살펴본 적이 있는데, 제조사 쪽 지시문도 점점 이런 말을 덜어 내는 방향이었습니다.

강조를 전부 지우라는 뜻은 아닙니다. 같은 판의 변경 기록은 클로드 코드 문서에 적힌 사고 유도 키워드를 점검기가 지우지 않고 남긴다고 밝혔습니다. 제조사가 공식적으로 쓰라고 안내한 장치까지 옛 버릇으로 보고 걷어 내면 오히려 원하는 동작이 사라집니다. 진단 명령은 찾은 것을 먼저 보고하고 바꾸기 전에 확인을 묻는 방식이라, 제안된 수정을 한 줄씩 읽고 받아들이는 편이 안전합니다. 특히 보안이나 되돌리기 어려운 작업에 관한 금지 문장은, 표현이 세 보여도 남겨 둘 이유가 있을 수 있습니다.

진단 명령이 원래 하던 일

지시문 점검은 진단 명령에 새로 붙은 갈래입니다. 진단 명령 자체는 그 전부터 꽤 많은 일을 해 왔습니다. 중복되거나 남은 설치, 경로 문제, 읽히지 않는 설정 파일을 찾고, 거의 안 쓰는 스킬·서버·플러그인을 맥락 비용과 견줘 보여 주고, 느린 훅을 짚고, 새 판이 있는지도 봅니다.

지침 파일 쪽 기능도 이미 있었습니다. 내 로컬 지침과 저장소에 올린 지침에서 겹치는 부분을 정리하고, 저장소 지침에서 코드만 봐도 알 수 있는 내용을 덜어 내고, 늘 실리던 안내를 필요할 때만 불러오는 스킬이나 하위 폴더 파일로 옮겨 줍니다. 정리 기능은 2.1.206판부터 들어왔습니다. 짧게 잘 쓴 지침 파일 하나가 왜 화제가 됐는지 떠올려 보면, 도구가 가려는 방향도 결국 짧고 정확한 지침입니다.

덧붙여 진단 명령은 자동 모드를 기본으로 쓰겠냐고 권하거나, 자주 거절되는 읽기 전용 명령을 미리 허락해 두자고 제안하기도 합니다. 이건 지시문과는 다른 문제라 제안이 뜨면 따로 판단하셔야 합니다. 설치 상태만 보고 싶다면 터미널에서 진단 명령을 바로 실행하면 세션을 열지 않고 읽기 전용으로 결과만 보여 줍니다. 진단이 정상으로 나와도 놓치는 부분이 있다는 건 여전하니, 느림이나 파일 찾기 문제는 그 글의 방법을 함께 쓰시길 권합니다.

철저함을 부추기는 문장을 덜어 낸 다음에 볼 곳이 노력 수준입니다. 오퍼스 5.5는 기본 노력이 중간이고, 사용자 설정 맨 위에 예전 방식으로 적어 둔 노력 값은 오퍼스 5.5에 적용되지 않습니다. 노력 수준이 정해지는 순서와 모델별 저장 방식을 정리했으니, 모델을 바꾼 날 지침 파일과 함께 확인해 보세요.

자주 묻는 질문

API로 쓰는 프롬프트도 점검할 수 있나요

클로드 API용 스킬에 같은 이름의 하위 명령이 따로 있습니다. 내 프로그램의 프롬프트와 스킬, 도구 설명에서 옛 모델용 지시를 찾아 고칠 부분을 차이 형태로 제안해 줍니다.

점검 결과를 그대로 받아들여도 되나요

바꾸기 전에 확인을 묻기 때문에 한 줄씩 보고 고를 수 있습니다. 보안 관련 금지 문장처럼 의도적으로 세게 적어 둔 것은 남겨 두는 편이 나을 때가 있습니다.

공용 지침 파일도 점검 대상인가요

변경 기록에는 클로드 전용 지침 파일과 스킬, 에이전트, 명령만 대상으로 적혀 있고 공용 지침 파일은 명시돼 있지 않습니다. 확실하게 보려면 점검 후 보고서에 해당 파일이 나오는지 확인해 보세요.

명령이 없다고 나옵니다

2.1.283판에서 생긴 기능입니다. 지금 쓰는 판부터 확인하고, 판을 올린 뒤 새 세션에서 다시 시도해 보세요.

제 경우라면 이 점검은 모델을 바꾼 날 돌려 보겠습니다. 지침 파일은 한 번 써 두면 좀처럼 다시 읽지 않는데, 그 사이 모델은 두어 번 바뀝니다. 예전 모델의 부족함을 메우려고 넣은 문장이 새 모델에게는 짐이 되는 경우가 생기니까요. 보고서가 짚어 준 곳 중에서 도구를 쓰라고 몰아붙이는 문장과 「빠짐없이」류의 부추김부터 덜어 내 보고, 응답 속도와 토큰이 어떻게 바뀌는지 며칠 지켜보는 순서가 무난해 보입니다.

확인한 곳: 클로드 코드 변경 기록 2.1.283, 공식 명령어 문서의 진단 명령 항목, 클로드 플랫폼의 프롬프트 작성 가이드(도구 사용·과잉 사고·이전 세대에서 옮겨 올 때). 2026년 9월 26일 기준이며 점검 항목은 판올림에 따라 늘어날 수 있습니다.