Anthropic, Claude Code 시스템 프롬프트 80% 삭제: Claude 5 세대 컨텍스트 엔지니어링 규칙 6가지

9bow · 9월 7, 2026, 10:00오후

Claude 5 세대를 위한 컨텍스트 엔지니어링 규칙 소개

Anthropic은 Claude Code의 시스템 프롬프트에서 80% 이상을 덜어내고도 자사 코딩 평가에서 측정 가능한 성능 손실이 없었다고 밝혔습니다. 2026년 7월 24일 Anthropic 기술 스태프 Thariq Shihipar가 발행한 The new rules of context engineering for Claude 5 generation models 는 그 삭제 작업에서 무엇이 근거 없는 통념으로 남아 있었는지를 6가지로 정리하고, 같은 판단 기준을 독자의 프로젝트에 옮기는 방법을 설명하는 글입니다.

이 글이 다루는 컨텍스트 엔지니어링(Context Engineering) 은 Anthropic이 2025년 Effective context engineering for AI agents에서 정리한 개념으로, 프롬프트 한 개를 잘 쓰는 문제가 아니라 모델이 매 요청에서 실제로 받는 토큰 전체를 설계하는 문제를 가리킵니다. 사용자가 입력한 프롬프트는 그중 일부일 뿐이고, 나머지는 시스템 프롬프트, 스킬(Skills), CLAUDE.md 파일, 메모리, 도구 정의, MCP(Model Context Protocol) 서버가 채웁니다. 프롬프트는 한 번의 요청에만 쓰이지만 컨텍스트는 수많은 요청에 공통으로 쓰이므로 프롬프트만큼 구체적으로 쓸 수 없고, 사용자가 어떤 요청을 보낼지 모르는 상태에서 일반적인 지침을 써야 한다는 어려움이 여기서 나옵니다.

문제를 어렵게 만드는 쪽은 모델 자체의 변화입니다. Anthropic은 Claude Opus 5와 Claude Fable 5 같은 최신 세대에서 프롬프트를 쓰는 방식이 크게 달라졌다고 설명합니다. 이전 모델을 안전하게 쓰려고 넣어 둔 강한 지시가 새 모델에서는 오히려 판단을 막는 제약으로 작동하기 때문입니다. 원문은 이 변화를 "Claude의 족쇄를 푸는 일(Unhobbling Claude)" 로 표현하고, 그 결과를 claude doctor 라는 명령에 담아 사용자가 자기 스킬과 CLAUDE.md 파일의 크기를 직접 조정할 수 있게 했다고 밝히고 있습니다.

한국 개발자 입장에서 이 글이 실용적인 이유는 삭제 대상이 Anthropic 내부 시스템 프롬프트에 국한되지 않는다는 점입니다. 6가지 통념 대부분은 커뮤니티가 지난 1년 동안 좋은 설정으로 공유해 온 것들이고, 그중 몇 가지는 Claude Code 커스터마이징 팁 형태로 널리 퍼져 있습니다. 아래에서는 원문의 6가지 항목을 하나씩 살펴본 뒤, 2025년 가이드와 비교해 무엇이 실제로 뒤집혔고 무엇이 그대로 유지되는지를 따로 정리했습니다.

과잉 제약이 만든 문제, 한 컨텍스트에 모인 지시가 서로 충돌한다

Anthropic이 삭제를 시작한 계기는 성능 지표가 아니라 자사 직원들의 Claude Code 사용 기록이었습니다. 하나의 요청 안에서 시스템 프롬프트, 스킬, 사용자 요청이 각자 다른 방향을 지시하는 장면이 반복해서 나타났습니다. 한쪽은 "문서화는 적절한 수준으로 남겨라" 라고 하고 다른 쪽은 "주석을 절대 추가하지 말라" 고 하는데, 사용자는 또 다른 것을 요구하는 식입니다.

위 그림은 그 상황을 한 장으로 보여줍니다. 시스템 프롬프트 영역에 "leave documentation as appropriate", 스킬 영역에 "do not add comments", 사용자 요청 영역에 "just make it work like the old one" 이 각각 강조돼 있고, 그림 아래에는 "하나의 컨텍스트다. Claude는 이것을 전부 읽고, 전부 맞춰야 한다" 는 설명이 적혀 있습니다. 원문은 이 문구들이 실제 프롬프트를 그대로 인용한 것이 아니라 상황을 보여주기 위한 예시라고 각주로 밝혀 두었습니다.

물론 Claude가 이런 충돌을 풀지 못하는 것은 아닙니다. 원문의 표현대로 Claude는 사용자의 의도를 해석해 옳은 답에 도달할 수 있습니다. 문제는 그 과정에서 겹치고 충돌하는 지시들을 먼저 정리해야 한다는 데 있습니다. 판단 능력이 낮은 모델에게는 이 비용을 감수하고서라도 최악의 상황을 막는 가드레일(Guardrail)이 필요했지만, 판단 능력이 올라간 모델에서는 그 가드레일이 순수한 낭비로 남습니다.

여기에 Claude Code 자체의 변화가 더해집니다. 예전에는 CLAUDE.md 파일이 메모리, 정보, 지침을 모두 떠맡는 유일한 창구였습니다. 지금은 자동 메모리, 아티팩트(Artifacts), 스킬이 각각 따로 있고, Claude가 세션을 넘어 컨텍스트를 적재하고 공유하는 경로를 스스로 만들 수 있습니다. 한 파일에 모든 것을 적어 둘 이유가 구조적으로 사라진 셈입니다.

지우는 쪽이 이득인 이유, 어텐션 예산은 유한하다

Anthropic이 지시를 덜어내는 쪽으로 움직인 배경에는 충돌 문제만 있는 것이 아닙니다. 컨텍스트 자체가 유한한 자원이라는 관찰이 함께 깔려 있습니다. 2025년 가이드는 LLM에게 어텐션 예산(Attention Budget) 이라는 개념을 두고, 컨텍스트에 새로 들어오는 토큰마다 그 예산을 조금씩 소모한다고 설명합니다. 사람의 작업 기억(Working Memory)이 유한한 것과 같은 성질입니다.

이 성질은 구조에서 나옵니다. LLM은 트랜스포머(Transformer) 구조를 기반으로 하고, 모든 토큰이 컨텍스트 전체의 다른 모든 토큰을 참조할 수 있습니다. 토큰이 n 개면 토큰 쌍(Pair) 관계가 n^2 개 생깁니다. 컨텍스트 길이가 늘어날수록 모델이 이 쌍 관계를 포착하는 능력이 떨어지고, 컨텍스트 크기와 어텐션 집중 사이에 상충 관계가 생깁니다.

학습 데이터의 분포도 같은 방향으로 작용합니다. 짧은 시퀀스가 긴 시퀀스보다 흔하기 때문에 모델은 컨텍스트 전체에 걸친 의존 관계를 다룬 경험이 적고, 그 용도로 특화된 파라미터도 적습니다. 위치 인코딩 보간(Position Encoding Interpolation) 같은 기법이 원래 학습한 길이보다 긴 시퀀스를 다루게 해 주지만, 토큰 위치를 이해하는 정확도는 조금 떨어집니다.

2025년 가이드는 이 요인들이 급격한 단절이 아니라 점진적인 성능 기울기를 만든다고 정리합니다. 모델은 긴 컨텍스트에서도 여전히 유능하지만, 정보 검색과 먼 거리의 추론(reasoning)에서는 짧은 컨텍스트일 때보다 정밀도가 떨어집니다. 컨텍스트 부패(Context Rot) 연구가 관측한 것도 같은 현상으로, 컨텍스트 윈도우의 토큰 수가 늘면 그 안의 정보를 정확히 회상하는 능력이 떨어집니다.

그래서 좋은 컨텍스트 엔지니어링의 목표는 원하는 결과를 낼 가능성을 가장 크게 만드는 신호가 높은 최소 토큰 집합을 찾는 것이 됩니다. 시스템 프롬프트 80% 삭제는 그 목표를 Claude Code 자신에게 가장 큰 규모로 적용한 사례입니다. 지운 지시가 담고 있던 정보를 모델이 이미 판단으로 대체할 수 있다면, 그 토큰은 예산만 쓰고 아무것도 더하지 않습니다.

뒤집힌 6가지 통념, 규칙에서 판단으로

원문은 그동안 모범 사례로 통했지만 이제는 통념에 가까워진 항목 6가지를 나란히 놓습니다.

위 그림의 왼쪽이 취소선으로 지워진 이전 방식이고 오른쪽이 새 방식입니다. 각 항목이 무엇을 바꾸라고 말하는지 정리하면 아래 표와 같습니다.

이전 방식 (Then)	새 방식 (Now)	바뀐 내용
규칙을 준다 (Give Claude Rules)	판단에 맡긴다 (Give Claude Judgement)	항상 참이 아닌 강한 지시를 지우고 주변 컨텍스트로 결정하게 함
예시를 준다 (Give Claude Examples)	인터페이스를 설계한다 (Design Interfaces)	도구 사용법을 예시로 알려주는 대신 파라미터 자체를 표현력 있게 설계
앞쪽에 다 넣는다 (Put it all upfront)	점진적 공개를 쓴다 (Use Progressive Disclosure)	필요한 시점에 필요한 컨텍스트만 적재, 스킬과 지연 로딩 도구 활용
반복해서 적는다 (Repeat Yourself)	도구 설명을 간결하게 (Simple Tool Descriptions)	시스템 프롬프트와 도구 설명에 중복해 적던 지침을 도구 설명 쪽에만 남김
`CLAUDE.md` 에 메모리를 쌓는다 (Memory in Claude.MDs)	자동 메모리 (Auto-memory)	사용자가 직접 저장하는 대신 Claude가 관련 있는 것을 알아서 기록
단순한 명세 (Simple Specs)	풍부한 참조 (Rich References)	마크다운 계획 파일을 넘어 HTML 아티팩트, 테스트 스위트, 루브릭까지 참조로 활용

규칙에서 판단으로, 주석 지침이 사라진 이유

Claude Code를 처음 내놓을 때 Anthropic이 가장 걱정한 것은 파일 삭제 같은 최악의 상황이었습니다. 그래서 항상 참은 아니지만 사고를 막아 주는 강한 지시를 시스템 프롬프트에 넣었습니다. 주석에 관한 지시가 대표적입니다.

In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don't create planning, decision, or analysis documents unless the user asks for them — work from conversation context, not intermediate files.

코드에서는 주석을 쓰지 않는 것을 기본값으로 하고, 여러 문단짜리 독스트링이나 여러 줄 주석 블록은 절대 쓰지 말고 한 줄로 끝내라 는 내용입니다. 원문은 이 지시가 일부 요청에서는 틀렸다고 인정합니다. 문서화에 대해 사용자가 자기 취향을 갖고 있을 수도 있고, 아주 복잡한 코드의 특정 부분에는 여러 줄 주석 블록이 정말 필요할 수도 있습니다.

그런데도 이전 모델에서는 가드레일을 빼면 Claude가 쓰는 주석이 여러 경우에 틀렸기 때문에, Anthropic은 이 교환을 받아들여야 했습니다. 새 세대 모델은 판단 능력이 더 좋아서 명시적인 규칙 없이도 이런 결정을 잘 처리한다는 것이 이번 변경의 근거입니다. 바뀐 시스템 프롬프트에는 같은 자리에 한 줄만 남았습니다.

Write code that reads like the surrounding code: match its comment density, naming, and idiom.

주변 코드처럼 읽히는 코드를 써라. 주석 밀도, 이름 짓기, 관용 표현을 주변에 맞춰라 는 문장입니다. 금지 목록을 나열하는 대신 판단 기준 하나를 주고, 그 기준을 적용할 재료(주변 코드)는 Claude가 이미 읽고 있는 컨텍스트에서 가져오게 한 형태입니다. 시스템 프롬프트가 세대별로 어떻게 줄어들었는지 실물로 비교한 자료로는 커뮤니티에 정리된 Opus 4.6과 4.7 사이의 시스템 프롬프트 변경 사항이 참고가 됩니다.

예시에서 인터페이스 설계로, TodoWrite가 보여주는 것

도구 사용에서 첫 번째 규칙은 오랫동안 사용법 예시를 준다 였습니다. 원문은 최신 모델에서 이 규칙이 역효과를 낸다고 말합니다. 예시를 주면 모델이 특정한 탐색 공간(Exploration Space)에 갇힌다는 것입니다.

위 그림 왼쪽이 언제 쓰는지에 대한 목록과 완성된 예시들로 채워졌던 이전 설명이고, 분량이 약 9,100자로 표시돼 있습니다. 오른쪽은 그것을 대체한 짧은 인터페이스입니다. "현재 세션의 작업 목록을 만들고 갱신한다" 로 시작하는 한 문장, status 파라미터가 가질 수 있는 값 세 가지(pending, in_progress, completed), 그리고 한 번에 하나의 작업만 in_progress 로 둔다 는 지시가 전부입니다.

예시 대신 무엇을 하라는 것인지가 이 항목의 핵심입니다. 원문은 도구, 스크립트, 파일의 설계 자체를 더 고민하라고 말합니다. Claude가 쓸 수 있는 파라미터가 무엇이고, 그 파라미터를 어떻게 더 표현력 있게 만들 수 있는지를 묻는 쪽입니다. 즉 status 를 자유 문자열로 두면 사용법을 예시로 설명해야 하지만, 세 값의 열거형(Enumeration)으로 두면 그 자체가 사용법을 알려줍니다. 한 번에 하나만 진행 상태로 둔다는 한 줄이 우리가 원하는 동작을 정의하는 방식도 같습니다.

이 조언은 Anthropic이 Writing tools for AI agents에서 정리한 도구 설계 원칙과 이어집니다. 도구는 자기완결적이고, 오류에 강하고, 용도가 아주 분명해야 하며, 입력 파라미터도 서술적이고 모호하지 않아야 한다는 내용입니다.

앞쪽 적재에서 점진적 공개로, 스킬과 지연 로딩 도구

Claude Code가 코딩에 집중하던 시절, 시스템 프롬프트에는 코드 리뷰와 검증을 어떻게 하는지에 대한 상세한 정보가 들어 있었습니다. 항상 필요한 정보는 아니었지만 필요한 순간에는 결정적인 정보였기 때문입니다.

지금은 Claude Code가 필요한 시점에 필요한 컨텍스트를 적재하는 점진적 공개(Progressive Disclosure) 를 잘 다루게 되면서, 검증과 코드 리뷰를 각자의 스킬로 옮겨 Claude가 필요할 때만 호출하게 했습니다. Claude Code의 코드 리뷰 기능이 그렇게 분리된 사례입니다.

점진적 공개는 스킬만의 이야기가 아닙니다. Claude Code의 일부 도구는 지연 로딩(Deferred Loading) 으로 제공됩니다. 에이전트가 ToolSearch 로 전체 정의를 검색한 뒤에야 그 도구를 쓸 수 있는 방식입니다. 이렇게 두면 도구를 더 많이 두면서도 쓰이기 전까지는 컨텍스트를 차지하지 않습니다. 원문은 Task 계열 도구를 예로 들었습니다. MCP 도구 검색 문서에 같은 메커니즘이 설명돼 있는데, 세션 시작 시점에는 도구 이름과 서버 지침만 적재되므로 MCP 서버를 추가해도 컨텍스트 윈도우(Context Window)에 미치는 영향이 작습니다.

같은 원칙을 사용자의 CLAUDE.md 와 SKILL.md 에도 적용할 수 있습니다. 원문이 지목하는 통념은 이것입니다. Claude가 알아서 찾지 못할 것이라고 생각해 이 파일들을 마주칠 수도 있는 모든 관행의 중앙 저장소로 만들려는 습관입니다. 대신 필요한 시점에 적재되는 파일의 트리를 두라는 것이 원문의 제안이고, 그 문장에 Claude Code 동적 워크플로우 ( Claude Code 동적 워크플로우(Dynamic Workflows): 작업마다 하네스를 직접 짜는 병렬 오케스트레이션) 글을 링크해 두었습니다.

CLAUDE.md 가 여전히 앞쪽에 적재되는 이유도 같은 자리에서 설명됩니다. 2025년 가이드는 Claude Code를 하이브리드 전략의 예로 들면서, CLAUDE.md 파일은 앞쪽에 그대로 적재되고 glob과 grep 같은 원시 도구가 나머지를 필요할 때 가져온다고 정리했습니다. 속도를 위해 일부를 미리 넣고 나머지는 에이전트가 스스로 탐색하게 하는 절충입니다. 앞쪽에 적재되는 층이 있으니 그 층은 얇아야 하고 나머지는 찾아갈 수 있게 두면 된다는 것이, CLAUDE.md 를 가볍게 유지하라는 조언의 근거입니다.

심화 학습: 점진적 공개와 방금 적재하기(Just in Time)

Effective context engineering for AI agents (영문)

Claude Code 스킬 공식 문서 (영문)

MCP 도구 검색으로 컨텍스트 사용량 줄이기 (영문)

반복에서 간결한 도구 설명으로

이전 Claude 모델은 같은 지시를 여러 번 받아야 따르는 경우가 있었고, 컨텍스트 윈도우의 시작보다 끝에 있는 지시를 더 잘 듣는 경향도 있었습니다. 그래서 Anthropic의 시스템 프롬프트에는 도구에 대한 언급이 본문에도 있고 도구 설명에도 있는 이중 구조가 남아 있었습니다.

최신 세대에서는 이 반복을 지울 수 있었습니다. 도구를 어떻게 쓰는지에 대한 지침은 시스템 프롬프트가 아니라 도구 설명 쪽에 두고, 중복된 예시는 삭제했다는 것이 원문의 설명입니다. 앞의 인터페이스 설계 항목과 짝을 이루는 변경입니다. 도구 설명이 사용법의 유일한 출처가 되면, 도구를 고칠 때 시스템 프롬프트도 같이 고쳐야 하는 유지보수 부담이 사라집니다.

`CLAUDE.md` 메모리에서 자동 메모리로

예전에는 # 핫키로 CLAUDE.md 에 자동으로 기록하게 해서 사용자가 직접 Claude의 메모리를 채우는 방식을 권장했습니다. 지금은 Claude가 작업과 사용자에게 관련 있는 것을 알아서 메모리에 저장합니다.

Claude Code 메모리 문서를 보면 두 체계가 어떻게 나뉘는지 분명합니다. CLAUDE.md 는 사용자가 쓰는 지시와 규칙이고, 자동 메모리는 Claude가 쓰는 학습과 패턴입니다. 자동 메모리는 네 종류로 분류돼 저장됩니다.

user: 사용자의 역할, 전문성, 작업 선호
feedback: 사용자가 Claude에게 준 교정과 확인된 접근 방식
project: 코드나 Git 히스토리에서 끌어낼 수 없는 진행 중인 작업, 마감, 결정 사항
reference: 이슈 트래커나 대시보드처럼 프로젝트 밖에 있는 정보의 위치

여기서 눈여겨볼 것은 자동 메모리가 저장하지 않는 것들입니다. 아키텍처, 파일 경로, 디버깅 수정처럼 코드베이스에서 끌어낼 수 있는 것과 CLAUDE.md 가 이미 말하고 있는 것은 건너뜁니다. 저장 위치는 저장소별로 ~/.claude/projects/<project>/memory/ 이고, 세션 시작 때 실제로 적재되는 것은 색인 파일 MEMORY.md 의 앞부분(200줄 또는 25KB 중 먼저 닿는 쪽)뿐입니다. 개별 주제 파일은 Claude가 필요할 때 파일 도구로 직접 읽습니다. 색인은 얇게, 상세는 별 파일로 두는 점진적 공개가 메모리 계층에도 그대로 들어가 있는 구조입니다.

운영 쪽 설정도 문서에 정리돼 있습니다. 자동 메모리는 기본적으로 켜져 있고, 세션에서 /memory 를 열어 토글하거나 settings.json 의 autoMemoryEnabled 로 프로젝트 단위로 끌 수 있으며, 환경 변수 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 로도 끕니다. 저장된 파일은 평범한 마크다운이라 언제든 직접 열어 고치거나 지울 수 있고, 어떤 파일이 현재 세션에 실제로 적재됐는지는 /context 로 확인합니다. 메인 대화의 자동 메모리는 서브에이전트로 상속되지 않으므로, 서브에이전트가 자기 메모리를 갖게 하려면 memory 필드를 따로 켜야 합니다.

또한 Claude Code는 메모리 파일을 쓸 때 프론트매터에 modified 타임스탬프를 기록해 그 사실이 언제 기준인지 남깁니다. 자동 메모리 층이 생겼다고 CLAUDE.md 를 비워도 되는 것은 아닙니다. 두 체계는 쓰는 주체와 담는 내용이 다르고, 자동 메모리는 사용자가 이미 CLAUDE.md 에 적어 둔 것을 건너뛰도록 설계돼 있기 때문입니다.

단순한 명세에서 풍부한 참조로

계획 모드(Plan Mode)에서 Claude Code는 계획을 담은 마크다운 파일에 크게 의존해 왔습니다. 계획을 파일로 저장해 두면 Claude가 필요할 때 참조할 수 있었기 때문이고, 긴 프로젝트에서 명세(Specification)를 코드베이스에 저장해 두는 것도 같은 이유의 모범 사례였습니다.

원문은 Claude가 이제 훨씬 복잡한 참조를 다룰 수 있다고 말합니다. 단순한 마크다운 파일 대신 아티팩트 기능으로 만든 HTML을 참조로 쓸 수 있습니다. Claude Code의 아티팩트는 세션에서 만든 결과를 claude.ai의 비공개 URL에 살아 있는 웹 페이지로 발행하는 기능이라, 주석이 달린 diff나 대시보드처럼 텍스트로 설명하기 어려운 것을 그대로 담을 수 있습니다.

참조를 코드 형태로 줄 수도 있습니다. 명세가 상세한 테스트 스위트일 수도 있고, Claude가 이식해야 할 다른 코드베이스의 함수 한 개일 수도 있습니다. 자연어 설명보다 코드가 더 정확한 지시가 되는 자리에서는 코드를 주라는 이야기입니다.

루브릭(Rubric) 은 또 다른 형태의 참조입니다. 원문은 루브릭을 두고 동적 워크플로우로 검증자(Verifier) 에이전트를 실행하면, Claude가 특정 분야에서 사용자의 취향을 검증해 볼 수 있다고 설명합니다. 좋은 API 설계란 무엇인가 같은 질문이 그 예입니다. 동적 워크플로우는 Claude가 작업에 맞는 하네스(Agentic Harness)를 직접 구성하는 기능으로, 커뮤니티에는 관련 자료를 모은 Awesome Harness Engineering 소개 글도 있습니다.

루브릭을 참조로 쓰는 방식은 앞의 다섯 항목과 방향이 조금 다릅니다. 컨텍스트를 줄이는 것이 아니라 판단 기준을 밖으로 빼내는 쪽입니다. 시스템 프롬프트에 좋은 API 설계란 이런 것이다 를 적어 두면 모든 요청이 그 문장을 읽어야 하지만, 루브릭을 파일로 두고 검증 단계에서만 서브에이전트에게 넘기면 그 토큰은 검증할 때만 쓰입니다. 결과적으로 앞의 점진적 공개와 같은 자리에 놓입니다.

컨텍스트를 조립하는 층, 프롬프트는 그중 한 조각이다

6가지를 모두 반영해 컨텍스트를 조립하면 어떤 모습이 되는지가 원문의 두 번째 절입니다.

위 그림에서 가장 위에 강조돼 있는 것이 사용자가 입력한 프롬프트이고, 그 아래로 참조(References), 시스템 프롬프트, CLAUDE.md, 스킬, 메모리가 쌓여 있습니다. 그림 아래 설명은 "컨텍스트 윈도우다. 당신의 프롬프트는 여러 조각 중 하나다" 이며, 각 층의 크기는 예시일 뿐이라는 단서가 적혀 있습니다.

시스템 프롬프트(System Prompt): 제품 컨텍스트와 강하게 묶인 층입니다. Claude가 어떤 제품 안에서 동작하고 있고 무엇을 하는 중인지를 알려줍니다. Claude Code 사용자라면 이 층을 고칠 일이 거의 없지만, 자기 에이전트 하네스를 만드는 쪽이라면 시간을 많이 써야 하는 자리라고 원문은 말합니다. 2025년 가이드가 이 층에 대해 남긴 조언은 두 가지입니다. 깨지기 쉬운 하드코딩과 막연한 지침 사이의 적절한 고도를 찾는 것, 그리고 배경 정보, 지시, 도구 안내, 출력 설명처럼 구획을 나눠 XML 태그나 마크다운 헤더로 구분하는 것입니다. 다만 같은 가이드는 모델이 유능해질수록 정확한 서식의 중요성이 줄어들 것이라는 단서를 함께 달아 두었습니다.

CLAUDE.md: 가볍게 유지하고 저장소가 무엇을 하는 곳인지만 짧게 적습니다. 토큰의 대부분은 코드베이스 안의 함정을 적는 데 씁니다. 타입을 한 파일에만 모아 두고 다른 곳에는 두지 않는 식의 규칙이 그 예입니다. 파일 시스템이나 저장소를 보면 Claude가 알 수 있는 당연한 것은 적지 않습니다. 검증 방법에 대한 고유한 지시가 여러 개라면 검증 스킬을 만들어 CLAUDE.md 에서 이름으로만 참조하는 쪽이 점진적 공개에 맞습니다.

스킬(Skills): Claude가 필요할 때 정보를 찾아가게 해 주는 가벼운 안내서로 생각하라는 것이 원문의 표현입니다. 아주 중요한 영역을 빼고는 과도하게 제약하지 않습니다. 긴 스킬은 여러 파일로 나눠 점진적 공개를 최대한 활용합니다. 스킬이 가장 잘 작동하는 자리는 사용자, 팀, 제품에 고유한 의견과 지식과 관행을 담을 때입니다. Anthropic이 Claude Agent용 Skills 기능을 처음 공개했을 때부터 이어지는 설계 의도이기도 합니다.

참조(References): @ 로 파일을 멘션해 참조로 넣습니다. 참조는 현재 계획에 대한 깊이 있는 정보를 Claude가 들여다볼 수 있게 합니다. 명세 파일, 목업(Mockup), 심지어 코드베이스 전체가 될 수 있습니다. 원문은 일반적으로 코드로 된 파일을 선호하라고 권합니다. Claude가 아주 잘 아는 언어로 된 명확하고 충실도 높은 지시가 되기 때문입니다. 디자인의 경우 설명이나 스크린샷보다 HTML 목업이 대체로 더 좋은 결과를 낸다는 예를 들고 있습니다.

메모리(Memory): 앞에서 다룬 자동 메모리 층입니다. 사용자가 채우는 것이 아니라 Claude가 세션을 넘겨 쌓습니다.

2025년 가이드와 무엇이 달라졌고 무엇이 그대로인가

원문을 2025년의 Effective context engineering for AI agents와 나란히 놓으면, 뒤집힌 것과 유지되는 것이 갈립니다. 이 구분을 해 두면 새 글의 조언을 어디까지 확장해도 되는지 판단할 수 있습니다.

항목	2025년 가이드	2026년 새 규칙	관계
시스템 프롬프트	깨지기 쉬운 if-else 하드코딩과 너무 막연한 지침 사이의 적절한 고도(Right Altitude) 를 찾으라	항상 참이 아닌 강한 지시는 지우고 판단에 맡기라	같은 방향의 연장
예시	다양하고 전형적인 예시를 선별해 제시하라	도구 사용 예시는 탐색 공간을 좁히므로 인터페이스 설계로 대체하라	도구 영역에서 뒤집힘
컨텍스트 적재	방금 적재하기와 점진적 공개를 도입하라	스킬과 지연 로딩 도구로 실제 구현하라	원칙 유지, 구현 진전
도구	기능이 겹치지 않는 최소 집합을 선별하라	지연 로딩으로 더 많이 두어도 컨텍스트를 안 쓰게 하라	전제가 바뀜
메모리	구조화된 노트 작성을 에이전트에게 시키라	Claude가 알아서 자동 메모리에 기록한다	제품 기능으로 흡수
컨텍스트 총량	어텐션 예산(Attention Budget)은 유한하므로 신호가 높은 최소 토큰 집합을 찾으라	시스템 프롬프트 80% 이상을 삭제	같은 원칙의 적용 결과

여기서 정확히 짚어야 할 것이 예시 항목입니다. 2025년 가이드는 예시 제시를 계속 강력히 권한다 고 못 박았고, 반대한 것은 있을 수 있는 모든 규칙을 담으려고 예외 사례 목록을 프롬프트에 쏟아붓는 방식이었습니다. 새 글이 뒤집은 것은 그중 도구 사용법 예시에 한정됩니다. 원문의 문장도 "도구 사용의 첫 번째 규칙" 이라는 범위를 달고 있습니다. 따라서 분류나 서식 지정처럼 출력 형태를 맞춰야 하는 작업에서 예시를 걷어내는 근거로 이 글을 쓰기는 어렵습니다.

반면 컨텍스트 총량에 대한 원칙은 그대로입니다. 2025년 가이드는 트랜스포머 구조상 토큰 수가 늘면 어텐션이 넓게 분산된다는 점과, 컨텍스트가 길어질수록 회상 정확도가 떨어지는 컨텍스트 부패(Context Rot) 현상을 근거로 컨텍스트를 유한한 자원으로 다루라고 했습니다. 시스템 프롬프트 80% 삭제는 그 원칙을 어긴 것이 아니라 가장 큰 규모로 적용한 사례입니다.

긴 작업에서 컨텍스트를 관리하는 세 가지 기법

2025년 가이드가 정리한 세 가지 기법도 새 규칙과 충돌하지 않고 그대로 남습니다. 토큰 수가 컨텍스트 윈도우를 넘어서는 작업에서 필요한 것들입니다.

압축(Compaction): 컨텍스트 윈도우 한계에 가까워진 대화를 요약해 새 윈도우로 다시 시작하는 방식입니다. Claude Code는 메시지 이력을 모델에게 넘겨 아키텍처 결정, 해결되지 않은 버그, 구현 세부를 남기고 중복된 도구 출력은 버립니다. 그 뒤로는 압축된 컨텍스트에 가장 최근 접근한 파일 다섯 개를 더해 작업을 이어갑니다. 가장 가볍고 안전한 형태는 도구 호출 결과를 지우는 것으로, Claude Developer Platform의 컨텍스트 관리 기능에도 들어가 있습니다.
구조화된 노트 작성: 에이전트가 컨텍스트 윈도우 밖의 메모리에 정기적으로 노트를 쓰고 나중에 다시 읽어 오는 방식입니다. 앞에서 본 자동 메모리가 이 기법을 제품 기능으로 흡수한 결과이고, 커뮤니티에는 이 방향을 연구로 다룬 WikiSkill 정리 글도 있습니다.
서브에이전트 구조: 하나의 에이전트가 프로젝트 전체의 상태를 유지하는 대신, 깨끗한 컨텍스트 윈도우를 가진 전문 서브에이전트가 좁은 작업을 맡습니다. 서브에이전트는 수만 토큰을 써서 탐색하고도 보통 1,000에서 2,000토큰 정도로 압축한 요약만 돌려줍니다. 상세한 탐색 컨텍스트가 서브에이전트 안에 갇혀 있고 주 에이전트는 결과를 종합하는 데 집중하는 구조로, 멀티 에이전트 리서치 시스템 글이 복잡한 리서치 작업에서 단일 에이전트보다 나은 결과를 보였다고 보고했습니다.

심화 학습: 컨텍스트 엔지니어링의 기초

Google이 발간한 세션과 메모리 기술 백서

Building effective AI agents (영문)

Claude 프롬프트 엔지니어링 개요 문서 (영문)

내 CLAUDE.md와 스킬에서 무엇을 지울까

원문은 마지막 절에서 시스템 프롬프트, 스킬, CLAUDE.md 를 걸쳐 Anthropic이 한 것처럼 단순화가 필요할 수 있다고 말하고, 그 작업을 자동으로 돕는 claude doctor 를 언급합니다. Claude Code 안에서는 /doctor 명령으로 스킬과 CLAUDE.md 파일의 크기를 적정 수준으로 맞출 수 있습니다.

Claude Code 슬래시 명령 문서에서 확인할 수 있는 관련 도구는 세 가지입니다. /doctor 는 스킬 목록이 차지하는 컨텍스트 비용의 추정치와 그 비용에 가장 크게 기여하는 항목을 알려줍니다. /skill-doctor 는 스킬별 비용과 호출 빈도를 보여주고, 한 번도 호출되지 않은 스킬과 어디서 끌 수 있는지를 함께 표시합니다. /context 는 예산이 적용된 뒤의 스킬 목록 크기를 보고하므로 모델이 실제로 받는 값과 일치합니다. 스킬 목록은 기본적으로 모델 컨텍스트 윈도우의 1%를 예산으로 쓰고, 이를 넘으면 호출 빈도가 낮은 스킬의 설명부터 잘려 나갑니다. 예산은 skillListingBudgetFraction 설정으로 조정할 수 있습니다.

원문이 링크한 동적 워크플로우 글에는 이 정리 작업 자체를 Claude에게 맡기는 예시 프롬프트가 실려 있습니다. "워크플로우를 써서 내 최근 50개 세션을 훑고, 내가 반복해서 하는 교정을 찾아 자주 나오는 것을 CLAUDE.md 규칙으로 만들어 줘" 가 그것입니다. 지울 것과 남길 것을 사람이 처음부터 고르는 대신 자기 사용 기록에서 규칙 후보를 추출하는 방향이고, Anthropic이 내부 사용 기록을 읽어 충돌을 발견한 것과 같은 접근입니다.

원문의 조언을 실제 파일 구조로 옮기면 아래와 같은 트리가 됩니다. CLAUDE.md 는 얇게 두고, 절차는 스킬로 내리고, 긴 스킬은 다시 하위 파일로 쪼개는 형태입니다.

.claude/
├── CLAUDE.md              # 저장소의 목적 한두 줄 + 코드베이스의 함정
└── skills/
    ├── verify/
    │   └── SKILL.md       # 검증 절차, CLAUDE.md 에서 이름으로만 참조
    └── release/
        ├── SKILL.md       # 짧은 진입점
        └── references/
            ├── staging.md   # 필요할 때만 읽히는 하위 파일
            └── rollback.md

스킬의 진입점은 이름과 설명만 있는 프론트매터로 시작합니다. Claude가 매 턴 보는 것은 이 설명뿐이므로, 언제 이 스킬을 써야 하는지를 설명 첫머리에 적는 것이 스킬 목록 예산을 절약하는 방법이기도 합니다.

---
name: verify
description: 빌드와 스모크 테스트를 실행해 변경이 실제로 동작하는지 확인합니다. 배포 전 검증이나 빌드 확인 요청에 사용하세요.
---

무엇을 지울지 고를 때 원문이 제시한 기준을 항목으로 옮기면 다음과 같습니다.

파일 시스템을 보면 알 수 있는 것: 디렉터리 구조, 파일 경로, 사용 중인 프레임워크 이름은 Claude가 저장소를 훑어 알아냅니다. CLAUDE.md 에서 지웁니다.
항상 참이 아닌 금지 규칙: 절대 X 하지 말라 가 요청에 따라 틀리는 규칙이면, 판단 기준 한 줄로 바꿉니다. 주석 지침이 그대로 이 경우였습니다.
도구 사용 예시: 예시를 지우고 파라미터 이름과 열거형으로 사용법이 읽히게 만듭니다. 지울 예시가 많다면 그 도구의 인터페이스가 표현력이 부족하다는 신호입니다.
시스템 프롬프트와 도구 설명에 중복된 지침: 도구 설명 쪽만 남깁니다.
가끔만 필요한 상세 절차: 스킬로 내리고 CLAUDE.md 에서는 이름으로만 가리킵니다.
한 번도 호출되지 않은 스킬: /skill-doctor 가 표시해 주는 항목이며, 매 턴 컨텍스트를 차지하면서 아무 일도 하지 않습니다.

기존 프롬프트를 새 모델에 맞춰 다시 쓰는 작업 자체가 처음이라면, 커뮤니티에 정리된 Claude Fable 5 프롬프팅 가이드와 Claude Opus 5 프롬프트 작성법 및 Opus 4.8 마이그레이션 가이드를 먼저 읽어 두면 이 글의 6가지 항목이 어느 자리에 걸리는지 파악하기 쉽습니다.

이 조언이 적용되는 범위와 남는 질문

원문은 5분 분량의 짧은 글이고, 근거로 공개한 수치는 두 개입니다. 시스템 프롬프트를 80% 이상 삭제했는데 코딩 평가에서 측정 가능한 손실이 없었다는 것과, TodoWrite 도구 설명이 약 9,100자에서 짧은 인터페이스로 줄었다는 것입니다. 평가 항목, 삭제 전후의 전체 프롬프트, 개별 항목별 기여도는 공개되지 않았습니다.

다만 적용 범위에도 단서가 있습니다. 원문의 전제는 Claude Opus 5와 Claude Fable 5 같은 최신 세대이며, 오래된 모델에서 가드레일을 빼면 주석이 여러 경우에 틀렸다는 서술이 그 대비로 들어 있습니다. 소형 모델이나 이전 세대를 쓰는 파이프라인에서 같은 삭제를 하면 원문이 감수했다고 말한 그 실패가 돌아옵니다. Claude Opus 5와 Fable 5를 어떻게 나눠 써야 할까 같은 모델 선택 논의를 컨텍스트 설계와 함께 봐야 하는 이유입니다.

규칙을 지우고 판단에 맡기는 선택은 재현성과의 교환이기도 합니다. 규칙이 있으면 출력이 왜 그렇게 나왔는지 규칙으로 설명할 수 있지만, 판단에 맡기면 같은 요청에 대한 결과가 주변 컨텍스트에 따라 달라집니다. 원문도 아주 중요한 영역에서는 스킬을 과도하게 제약해도 된다고 예외를 두었습니다. 다만 어떤 영역이 거기에 해당하는지는 정해 두지 않았으므로, 감사 기록이나 규제 준수처럼 결과를 설명해야 하는 작업이라면 각 팀이 직접 선을 그어야 합니다. Claude Code 문서 역시 CLAUDE.md 와 자동 메모리를 강제 설정이 아니라 컨텍스트로 다루며, 무엇이 있어도 특정 동작을 막아야 한다면 PreToolUse 훅을 쓰라고 안내합니다.

The new rules of context engineering for Claude 5 generation models 소개 블로그

Effective context engineering for AI agents 블로그

Claude Code 공식 문서

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임은 이런 글들을 한국어로 정리해 나누고 있습니다. 회원으로 가입하시면 주요 글들을 이메일로 보내드리고, 텔레그램(Telegram)과 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

아래쪽에 좋아요를 눌러주시면 다음 글을 정리하는 데 힘이 됩니다~