/doctor로 Claude 작업 환경 진단, 안 쓰는 skill과 지시문 정리

Claude Code가 예전보다 느리거나 엉뚱한 결과를 낸다면 모델보다 그 모델에 얹어 둔 지시문과 설정을 먼저 의심해 볼 만합니다. Anthropic은 Claude Code의 system prompt(모델이 작업 전에 늘 읽는 기본 지침)를 80% 넘게 덜어 냈는데도 코딩 benchmark에서 측정할 만한 성능 저하가 없었다고 밝혔습니다. 사용자 쪽도 마찬가지입니다. 실수할 때마다 덧붙인 규칙, 쓰지 않는 skill, 다른 폴더에서 새어 들어오는 지시문이 쌓이면 Claude는 매 세션 그 짐을 지고 일합니다. Claude Code에 들어 있는 /doctor 명령은 바로 이런 짐을 찾아 주는 진단 도구입니다.

지시문을 덜어 내도 성능이 떨어지지 않은 이유

예전 모델은 정해 주지 않으면 장황해지기 쉬워서 system prompt에 ‘긴 주석을 쓰지 말라’ 같은 금지 규칙이 많았습니다. Anthropic은 Opus 5, Fable 5, Fable 5.1 같은 새 세대 모델에서 이런 규칙을 걷어 내고, 주석 규칙은 ’주변 코드와 같은 주석 밀도, 이름 짓기, 관용구를 따르고 스스로 판단하라’는 한 문장으로 바꿨습니다. 새 모델은 판단력이 좋아져 촘촘한 울타리가 오히려 발목을 잡는다는 판단입니다.

Claude Code를 만든 Boris Cherny는 coding agent를 쓰는 개발자에게 여섯 달마다 CLAUDE.md, skill, hook을 지워 보라고 권합니다. 새 모델이 스스로 해낼 수 있는 일이 무엇인지 확인하려는 것입니다. 지난 실수를 막으려고 그때그때 넣은 규칙이 모델이 바뀐 뒤에도 남아 있는 상태를 ’지시 부채(instruction debt)’라고 부를 수 있습니다. 웹사이트 색이 틀렸을 때 CLAUDE.md에 넣은 ‘파란색만 쓸 것’ 같은 규칙이 대표적입니다.

맥락이 많을수록 좋다는 생각도 근거가 약합니다. 2025년에 모델 다섯 개를 대상으로 한 연구에서는 필요한 정보가 모두 context window(모델이 한 번에 읽는 입력 범위) 안에 있어도 입력이 길어질수록 수학, 질의응답, 코딩 성능이 13.9%에서 85%까지 떨어졌습니다. 다만 이 수치는 1년 반도 더 전의 모델로 한 통제 실험이라 개인의 CLAUDE.md를 줄였을 때 그대로 나타나지는 않을 수 있습니다.

Anthropic은 도구 정의에도 같은 원칙을 적용했습니다. MCP(AI가 외부 도구와 데이터에 연결하는 규격) 도구 정의를 처음부터 모두 싣지 않고 tool search로 필요할 때 찾아 쓰게 하자 결과가 이렇게 달라졌습니다.

token 사용량은 85% 줄었고 정확도는 오히려 올랐습니다.

▲ 필요할 때만 불러오는 도구

적게 주되 꼭 필요한 것은 남기기

Anthropic의 Applied AI 팀은 기대하는 동작을 온전히 정하는 최소한의 정보를 목표로 하라고 권합니다. 최소한이 필요한 기술 정보를 빼라는 뜻은 아닙니다. 덜어 낼 것은 절차를 하나하나 지시하는 부분이고, 지킬 것은 모델이 스스로 알아낼 수 없는 사실입니다. 정리하면 가장 좋은 맥락은 가장 낮은 비용으로 가장 좋은 결과를 내는 가장 작은 맥락입니다.

새 모델에 일을 맡길 때는 세 Ghazi만 분명히 하면 됩니다.

• 결과: 끝났을 때 무엇이 있어야 하는가
• 이유: 왜 이 일을 하는가
• 제약: 반드시 지켜야 할 조건

이유를 밝히는 효과는 작지 않습니다. 인터뷰 녹취를 학습 자료로 바꾸는 작업을 두 방식으로 비교한 사례가 있습니다. 서식, 브랜드 템플릿, 링크 규칙, 구조 지시를 잔뜩 넣은 쪽은 브랜드 머리글까지 갖춘 깔끔한 문서를 냈습니다. 반면 ’학생용 자료로 바꿔 달라’는 의도만 준 쪽은 내용 구성이 더 낫고 기술 설명이 더 깊었으며 시간 표시도 정확했습니다. 이처럼 학생용이라는 목적을 밝히면 Claude는 비유, 직관적인 설명, 친근한 예시를 스스로 골라 씁니다. 겉모양이 깔끔하다고 내용까지 좋은 것은 아니라는 점을 보여 주는 사례로 보입니다.

그렇다고 모든 배경을 지울 필요는 없습니다. 말투, 전략 목표, 대상 독자처럼 그 일에만 해당하는 배경은 남기고, 정해진 순서를 따르게 하는 점검표는 시험해 보고 줄이는 쪽이 합리적입니다. 영상 편집 규칙처럼 특정 작업에만 필요한 세부 지침은 그 작업을 할 때만 불러오게 나눠 둡니다. CLAUDE.md는 프로젝트의 목적, 주의해야 할 함정, 필요할 때 읽을 하위 지침 파일의 위치만 담은 짧은 출발점으로 두는 것이 좋습니다.

/doctor가 찾아내는 것

/doctor를 실행하면 Claude Code가 설정, plugin, MCP 서버, skill, 메모리, 설치 경로를 읽기만 하는 점검 열 Ghazi를 돌립니다. 결과 표에는 skill마다 범위, 설치 뒤 호출 횟수, 상주 token 추정치, 권장 조치(예: 제거)가 나옵니다. Claude Code는 skill 파일 맨 위의 YAML frontmatter(이름과 설명을 적는 머리말)만 읽어 skill을 등록하므로 본문 전체를 미리 읽지는 않지만, 이 머리말만으로도 skill마다 token을 차지합니다.

실제 작업 환경 하나를 진단한 결과는 다음과 같았습니다.

35 token은 사소해 보이지만 긴 세션에서는 이런 낭비가 금방 쌓입니다. 쓰지 않는 skill은 바로 지우지 않고 설정 파일에서 꺼 둘 수도 있습니다. 진단이 끝나면 어떤 정리를 적용할지 전부 정리, 골라서 정리, 모두 유지, 직접 조정 가운데에서 고르게 하므로 목록을 확인하고 승인하면 됩니다. 자동으로 제안된 삭제를 그대로 받아들이기보다 항목을 하나씩 살펴보는 편이 안전합니다.

▲ 작업 환경 건강 진단

작업 흐름의 중복도 같은 방식으로 찾는다

설정 점검을 넘어 작업 흐름 자체를 감사할 수도 있습니다. 영상 대본을 만드는 저장소에서 Claude Code에 ’이 저장소를 살펴보고 아이디어에서 촬영용 대본까지 가는 과정을 더 빠르게 할 가장 작은 변경을 보여 달라. 이미 있는 구조를 쓰고, 다시 쓸 파일을 정확히 짚되 아직 아무것도 고치지 말라’고 요청한 사례가 있습니다.

Claude Code는 개요를 만드는 skill과 대본을 쓰는 skill이 같은 원자료 사실 확인을 따로 하고 있다는 점을 찾아냈습니다. 프로젝트 폴더 25개 가운데 조사 근거를 담은 sources.md 파일이 있는 곳은 3개뿐이어서, 앞 단계의 조사 결과가 다음 단계로 넘어가지 않았던 것입니다. Claude는 두 skill에 세 군데를 고쳐 개요 단계에서 근거를 sources.md에 남기고 대본 단계가 그 파일을 읽게 하자고 제안했습니다. 단계 사이에 넘기는 결과물의 형식을 정해 두지 않으면 같은 확인과 호출이 되풀이된다는 점을 보여 줍니다.

정리: 분기마다, 모델이 바뀔 때마다 점검하기

Claude Code의 성능을 끌어올리는 일은 지시를 더하기보다 덜어 내는 쪽에 가깝습니다. 다음 순서로 시작해 볼 수 있습니다.

1. 프로젝트에서 /doctor를 실행해 쓰지 않는 skill, 깨진 frontmatter, 상위 폴더에서 새어 드는 CLAUDE.md를 확인합니다.
2. 결과를 하나씩 검토한 뒤 쓰지 않는 skill은 끄고, 콜론이 들어간 frontmatter 값은 따옴표로 감쌉니다.
3. CLAUDE.md에서 예전 실수 때문에 넣은 규칙과 중복 안내를 지우고, 특정 작업용 지침은 따로 떼어 냅니다.
4. 일을 맡길 때는 결과, 이유, 제약만 분명히 적고 형식과 구조는 모델에 맡겨 봅니다.
5. 설정이 자주 바뀌면 매달, 안정적이면 분기마다 점검하고, 주로 쓰는 모델을 바꿀 때는 곧바로 점검합니다. 모델마다 지시문을 받아들이는 방식이 다르기 때문입니다.

점검을 예약 작업으로 걸어 두면 /doctor와 감사가 백그라운드에서 돌고 제안만 승인하면 됩니다. 정리가 꾸준하지 못한 것이 개인 작업 환경이 지저분해지는 가장 큰 원인이라는 점에서, 사람의 기억에 맡기지 않는 이 방식이 오래 유지하기에 유리해 보입니다.