Anthropic이 자사 Claude Code의 시스템 프롬프트에서 80% 넘게 지운 이유와, 여러분의 CLAUDE.md·스킬 파일에서 지금 당장 무엇을 지워야 하는지 알 수 있습니다.
지난 며칠 사이 AI 개발자 커뮤니티에서 가장 많이 회자된 문장이 있습니다. "우리는 Claude Code 시스템 프롬프트의 80% 이상을 지웠고, 코딩 평가 점수에는 측정 가능한 손실이 없었다." Anthropic이 Claude Opus 5, Claude Fable 5 같은 최신 모델을 위해 실제로 한 일입니다.
여기서 핵심은 "무엇을 지웠나"가 아니라 "왜 지울 수 있게 됐나"입니다. 그동안 시스템 프롬프트에 빽빽하게 넣던 규칙 상당수가, 사실은 예전 모델의 부족한 판단력을 메우기 위한 가드레일이었다는 것입니다. 모델이 똑똑해지자 그 가드레일이 오히려 판단을 방해하는 짐이 됐습니다.
Anthropic은 이 전환을 6가지 원칙으로 정리했습니다. 아래에서 각 원칙을 '예전 방식 → 새 방식'으로 대비하고, 여러분의 CLAUDE.md와 스킬에 바로 적용할 방법을 붙였습니다.
1. 규칙을 더 넣기 → 판단을 맡기기
가장 큰 철학 전환입니다. 예전 시스템 프롬프트에는 이런 모순된 지시가 공존했습니다. "적절하게 문서를 남겨라"와 "주석을 절대 달지 마라(DO NOT add comments)"가 한 프롬프트 안에 동시에 들어 있던 겁니다. 모델은 이 충돌을 해소하느라 매번 불필요하게 고민해야 했습니다.
새 방식은 이 규칙들을 원칙 하나로 압축합니다. "주변 코드처럼 읽히는 코드를 써라. 주석 밀도, 이름 짓기, 관용구를 주변에 맞춰라." 세세한 금지 규칙 대신 판단 기준을 주고, 나머지는 모델이 맥락에서 읽어내게 합니다.
적용법: CLAUDE.md에서 "절대 ~하지 마라" 형태의 미시 규칙을 찾아보세요. 그 규칙이 정말 모델이 맥락에서 유추할 수 없는 것인지 자문합니다. 유추 가능한 것이라면 지우고, 대신 "이 저장소는 이런 스타일을 따른다"는 원칙 한 줄로 바꿉니다.
2. 예시를 잔뜩 주기 → 인터페이스를 설계하기
예전에는 도구 사용법을 알려주려고 사용 예시를 잔뜩 붙였습니다. 문제는 예시가 모델의 탐색을 특정 패턴에 가둔다는 점입니다.
새 방식은 도구의 파라미터와 스키마 자체가 설명이 되도록 설계합니다. 원문에 나온 Todo 도구 예시가 명료합니다. 상태값을 pending, in_progress, completed로 열거해두면, 이 열거만으로 "작업은 이 세 단계를 거친다"는 동작이 모델에게 암묵적으로 전달됩니다. 별도 설명 문단이 필요 없습니다.
적용법: MCP 도구나 커스텀 함수를 정의할 때, 사용 예시를 늘리기 전에 파라미터 이름과 enum 값부터 자명하게 만드세요. status: string보다 status: "pending" | "in_progress" | "completed"가 훨씬 많은 것을 말해줍니다.
Photo by Nubelson Fernandes on Unsplash
3. 전부 앞단에 넣기 → 점진적 공개
예전에는 모델이 알아야 할 정보를 시스템 프롬프트 맨 앞에 다 쏟아부었습니다. 컨텍스트 창이 무거워지고, 정작 필요한 순간에 정보가 묻히는 역설이 생겼습니다.
새 방식은 점진적 공개(Progressive Disclosure)입니다. 상세 정보를 스킬과 지연 로딩(deferred loading) 도구로 옮겨두고, 모델이 필요할 때만 꺼내 쓰게 합니다. Claude Code의 ToolSearch가 이 원리로 동작합니다. 도구 이름만 먼저 노출하고, 실제 스키마는 모델이 그 도구를 쓰기로 판단했을 때 불러옵니다.
적용법: 스킬을 "항상 켜져 있는 설명서"가 아니라 "필요할 때 찾아보는 가벼운 안내판"으로 생각하세요. 긴 스킬은 여러 파일로 쪼개고, 본체에는 언제 무엇을 불러올지만 남깁니다.
4. 지시를 반복하기 → 도구 설명에 한 번만
같은 사용 지침을 시스템 프롬프트 여기저기에 중복해 넣던 관행이 있었습니다. 모델이 잊을까 봐 반복한 것인데, 최신 모델에는 오히려 노이즈입니다.
새 방식은 도구 사용 지침을 그 도구의 설명(description)에 딱 한 번만 둡니다. 지침이 있어야 할 곳에 지침을 두는, 단순하지만 강력한 원칙입니다.
적용법: CLAUDE.md에 특정 도구·스크립트 사용법을 적어뒀다면, 그 설명이 도구 정의 자체에도 중복되어 있는지 확인하세요. 한쪽으로 통일하고 나머지는 지웁니다.
5. CLAUDE.md에 기억을 쌓기 → 자동 메모리 활용
예전에는 유지해야 할 맥락을 사람이 직접 CLAUDE.md에 문서화했습니다. 새 방식은 모델의 자동 메모리 기능을 활용합니다. 반복 문서화 대신, 시스템이 스스로 축적하고 참조하게 맡기는 방향입니다.
적용법: CLAUDE.md는 가볍게 유지하세요. 원문의 조언이 명료합니다. "저장소가 무엇을 위한 것인지는 짧게 설명하고, 토큰 대부분은 코드베이스 안의 함정(gotchas)에 쓰라." 프로젝트 소개는 한두 줄, 나머지는 "여기서 실수하기 쉬운 지점"으로 채우는 게 훨씬 값집니다.
6. 단순한 명세 → 풍부한 레퍼런스
마지막 전환입니다. 예전에는 참조 자료를 단순화된 마크다운 으로 정리해 넣었습니다. 새 방식은 HTML 아티팩트, 상세한 테스트 스위트, 실제 코드 예제 같은 풍부한 레퍼런스를 그대로 받아들입니다.
원문의 표현을 빌리면, 코드 안에 있는 파일을 선호하라고 합니다. 그것이 모델에게 명확하고 충실도 높은 지침을 주기 때문입니다. 잘 짜인 테스트 스위트 하나가 장황한 설명 문단보다 모델에게 더 정확한 정보를 전달합니다.
적용법: 스킬에 "이렇게 동작한다"고 글로 설명하는 대신, 실제 동작을 보여주는 코드 파일이나 테스트를 참조로 걸어두세요. 설명은 낡지만 코드는 사실이기 때문입니다.
Photo by Pawel Czerwinski on Unsplash
그래서 지금 뭘 하면 되나
Anthropic은 이 원칙들을 claude doctor 명령에 담아두었습니다. Claude Code에서 실행하면 여러분의 스킬과 CLAUDE.md를 진단해 "적정 크기"로 다이어트하도록 도와줍니다. 오늘 당장 할 수 있는 순서는 이렇습니다.
- 1단계:
claude doctor로 현재 CLAUDE.md·스킬의 과잉 지점을 진단합니다. - 2단계: "절대 ~하지 마라" 형태의 미시 규칙을 골라, 모델이 맥락에서 유추 가능한 것부터 지웁니다.
- 3단계: 긴 스킬을 여러 파일로 쪼개고, 본체에는 "언제 무엇을 불러올지"만 남깁니다.
- 4단계: CLAUDE.md의 프로젝트 설명을 줄이고, 그 자리를 코드베이스의 함정 목록으로 채웁니다.
마무리
Claude 5 세대의 컨텍스트 엔지니어링은 "모델을 더 촘촘히 통제하기"에서 "모델의 판단에 여백을 내어주기"로 방향을 틀었습니다. 6가지 원칙은 결국 하나로 모입니다. 모델이 맥락에서 스스로 알아낼 수 있는 것에는 규칙을 넣지 말고, 정말 유추 불가능한 것에만 명시적 규칙을 아끼라는 것입니다.
인사이트
한 가지 짚고 넘어갈 지점이 있습니다. "모델을 믿어라"는 조언은 개인 프로젝트와 규제가 걸린 코드베이스에서 전혀 다르게 착지합니다. 금융·의료처럼 감사(audit)가 필수인 환경에서는 리뷰어가 원하는 게 바로 "예측 가능한 규칙"입니다. 여기서 모델의 판단에 여백을 주는 순간, 그 여백이 통제 불가능성으로 읽힙니다. 그래서 이 6원칙은 "무조건 지워라"가 아니라 "모델이 유추 가능한 것만 지워라"로 읽어야 안전합니다. 유추 가능성의 경계선을 어디에 긋느냐가 실무의 진짜 판단 지점입니다.
두 번째 관점은 우리 GPTers 멤버에게 더 실질적입니다. 이 전환의 진짜 수혜자는 대규모 코드베이스를 다루는 팀이 아니라, 스킬과 CLAUDE.md를 혼자 관리하는 1인 운영자입니다. 파일이 무거워질수록 관리 비용은 사람에게 쌓입니다. 80% 다이어트는 성능 이야기이기 이전에 "내가 유지보수할 문서가 5분의 1로 줄어든다"는 운영 부담의 이야기이기도 합니다. 스킬을 새로 설계하거나 기존 것을 손볼 때, "이 규칙을 모델이 정말 몰라서 넣는가, 아니면 내가 불안해서 넣는가"를 한 번씩 물어보면 파일이 훨씬 가벼워집니다.
세 번째는 흐름에 대한 예측입니다. 이 방향이 계속되면 "프롬프트를 잘 쓰는 능력"보다 "인터페이스를 잘 설계하는 능력"이 더 중요해질 가능성이 높습니다. 3번·6번 원칙이 그 신호입니다. 좋은 파라미터 스키마와 좋은 테스트 스위트가 좋은 설명 문단을 대체하기 시작했습니다. 앞으로 AI를 잘 쓴다는 것은 말로 지시하는 기술에서, 모델이 스스로 읽고 판단할 수 있는 구조를 만드는 기술로 무게 중심이 옮겨갈 것입니다.
원문: The new rules of context engineering for Claude 5 generation models
