5. 컨텍스트 엔지니어링

“5. 컨텍스트 엔지니어링” 챕터 컨셉 일러스트

한 줄 정의. 컨텍스트 엔지니어링은 추론 매 순간 모델에게 무엇을 보여줄지를 고르고 유지하는 작업이다 — 프롬프트 한 번을 잘 쓰는 일이 아니라, 유한한 토큰 예산을 매 턴 다시 큐레이션하는 반복 작업이다.

컨텍스트 윈도우 구성 요소 분해도 — 시스템 프롬프트·도구 정의·검색 결과·대화 기록·동적 입력이 토큰 예산 하나에 쌓이고, 한계에 다가가면 컴팩션으로 요약해 새 윈도우를 여는 그림

정의: 프롬프트 엔지니어링과 무엇이 다른가

두 용어는 자주 섞여 쓰이지만 가리키는 대상이 다릅니다. 프롬프트 엔지니어링은 “최적의 결과를 얻기 위해 LLM에게 줄 지시문(instructions)을 쓰고 조직하는 방법”입니다. 분류·요약·추출 같은 이산적인(discrete) 1회 과제를 어떻게 한 번에 잘 풀어낼지를 다루는, 본질적으로 작성의 기술입니다.¹

컨텍스트 엔지니어링은 더 넓습니다. Anthropic은 이를 “LLM 추론 도중 최적의 토큰(정보) 집합을 큐레이션하고 유지하는 전략”이라고 정의합니다.

여기서 핵심은 “토큰 집합”의 범위입니다 — 프롬프트만이 아니라 그 프롬프트 바깥에서 컨텍스트 윈도우로 들어오는 다른 모든 정보가 포함됩니다. 도구 정의, 검색해 온 문서, 이전 도구 호출의 출력, 메모리에서 끌어온 노트, 대화 기록까지 전부 큐레이션 대상입니다.¹

결정적 차이는 반복성입니다. 프롬프트 엔지니어링이 시작 시점에 한 번 일어나는 일이라면, 컨텍스트 엔지니어링에서는 “큐레이션 단계가 모델에 무엇을 넘길지 결정할 때마다 매번” 일어납니다.

에이전트가 도구를 한 번 호출하고 결과를 받을 때마다, 다음 추론에 그 결과를 넣을지 버릴지·요약할지를 다시 판단해야 합니다. 그래서 컨텍스트 엔지니어링은 정적인 글쓰기가 아니라 매 턴 돌아가는 루프에 가깝습니다.¹

왜 중요한가: 주의 예산과 컨텍스트 부패

컨텍스트 윈도우는 무한한 메모장이 아니라 유한한 자원입니다. Anthropic은 이를 모델의 “주의 예산(attention budget)“이라 부릅니다. 토큰을 많이 넣을수록 좋아지는 것이 아니라, 윈도우의 토큰 수가 늘수록 “모델이 그 컨텍스트에서 정확히 회상하는 능력이 떨어지는” 컨텍스트 부패(context rot) 현상이 나타납니다.¹

이 부패에는 서로 다른 세 가지 메커니즘이 겹쳐 작동합니다.

아키텍처: n² 쌍 관계의 희석. 트랜스포머의 주의 메커니즘은 n개 토큰에 대해 n²개의 쌍(pairwise) 관계를 만듭니다. 토큰이 늘면 모델이 이 쌍 관계를 포착하는 능력이 “얇게 늘어납니다(stretched thin)” — 같은 표현력을 점점 더 많은 관계에 나눠 써야 하므로, 임의의 두 토큰 사이의 연결이 흐려집니다.

토큰 수를 두 배로 늘리면 추적해야 할 관계는 네 배가 됩니다.¹

훈련 분포: 짧은 시퀀스 편향. 모델은 데이터에서 주의 패턴을 학습하는데, 그 데이터에는 “짧은 시퀀스가 긴 시퀀스보다 흔합니다”. 결과적으로 모델은 멀리 떨어진 토큰 사이의 장거리 의존성(long-range dependency)을 다루는 데 “경험이 적습니다(less experienced)”. 아키텍처가 길이를 허용해도, 훈련 경험이 그 길이를 충분히 뒷받침하지 못하는 것입니다.¹

위치 인코딩: 보간의 대가. 모델을 원래 훈련된 것보다 긴 시퀀스에 적용하기 위해 position interpolation 같은 기법이 쓰입니다. 이는 긴 시퀀스를 원래의 작은 컨텍스트 범위에 맞춰 다루게 해 주지만, “일부 성능 저하(degradation)“를 동반합니다.

즉 컨텍스트를 늘리는 일 자체가 공짜가 아니라 회상 정밀도를 조금씩 갉아먹습니다.¹

그래서 일을 잘하는 에이전트는 “다 넣기”가 아니라 “필요한 토큰만, 그 순간에”를 추구합니다. 길어진 컨텍스트가 일으키는 구체적 성능 저하의 양상은 자매 주제인 컨텍스트 실패모드(별도 볼트)에서 더 깊게 다루고, 이 장은 윈도우를 어떻게 구성하고 관리하는가에 집중합니다.

시스템 프롬프트: 적정 고도와 구조화

시스템 프롬프트는 역할과 규칙을 정하는 가장 안정적인 층입니다. 여기서 흔히 빠지는 두 함정이 있습니다.

한쪽 극단은 하드코딩된 분기 논리를 잔뜩 박아 넣어 부서지기 쉬운(brittle) 프롬프트를 만드는 것이고, 다른 극단은 막연한 고수준 지침만 줘서 모델이 무엇을 해야 할지 짐작하게 두는 것입니다. Anthropic은 그 사이의 적정 고도(right altitude) — 두 실패 모드 사이의 “골디락스 존(Goldilocks zone)“을 겨냥하라고 권합니다.¹

목표는 “행동을 효과적으로 안내할 만큼 구체적이되, 모델에 강한 휴리스틱을 줄 만큼 유연한” 지점입니다. 모든 엣지케이스를 if-then으로 명시하면 부서지고, 너무 추상적이면 안내가 되지 않습니다. 적정 고도는 모델에게 판단의 방향을 주되 그 판단을 빼앗지 않는 높이입니다.¹

구조화. 긴 시스템 프롬프트는 구별되는 섹션으로 나눠 XML 태그나 마크다운 헤더로 표시하는 것이 좋습니다. 예를 들어 <background_information>, <instructions>, ## Tool guidance, ## Output description 같은 명시적 구획을 두면, 모델이 어느 부분이 배경이고 어느 부분이 지시인지 분간하기 쉬워집니다.¹

<background_information>
이 에이전트는 사내 결제 시스템의 변경을 돕는다. 코드베이스는 Go다.
</background_information>

<instructions>
- 변경 전 반드시 관련 테스트를 먼저 읽는다.
- 결제 흐름을 건드리는 변경은 plan 모드로 진행한다.
</instructions>

## Tool guidance
- 파일 검색은 grep을, 패턴 매칭은 glob을 쓴다.

## Output description
- 변경 요약은 3줄 이내로.

여기서 핵심 단서가 하나 더 있습니다. Anthropic이 권하는 것은 “기대 행동을 온전히 설명하는 최소 정보 집합”이지만, “최소(minimal)가 곧 짧음(short)을 뜻하지는 않습니다”. 모델이 올바르게 행동하는 데 진짜로 필요한 맥락이라면 길어도 담아야 하고, 없어도 같은 행동이 나오는 군더더기는 길이와 무관하게 빼야 합니다.

줄여야 할 것은 글자 수가 아니라 불필요한 정보입니다.¹

예제 큐레이션: 천 마디 말보다 그림 한 장

시스템 프롬프트로 행동을 가르치는 가장 효과적인 도구 중 하나가 예제(few-shot)입니다. Anthropic은 “LLM에게 예제는 천 마디 말과 같은 그림(pictures worth a thousand words)“이라고 표현합니다 — 규칙을 길게 서술하는 것보다, 기대 행동을 보여 주는 사례가 더 잘 전달됩니다.¹

다만 흔한 실수가 있습니다. “모든 가능한 규칙을 articulate하려고 엣지케이스 목록을 프롬프트에 쑤셔 넣기(laundry list of edge cases)“입니다.

이렇게 하면 프롬프트가 부풀고 부서지기 쉬워지며, 정작 핵심 패턴은 잡음에 묻힙니다. 권장은 그 반대로, “에이전트의 기대 행동을 효과적으로 그려내는 다양하고 정전적인(diverse, canonical) 예제 집합”을 고르는 것입니다.

모든 경우를 나열하는 대신, 서로 다른 전형적 상황 몇 개로 패턴의 윤곽을 보여 주면 모델이 나머지를 일반화합니다.¹

도구 정의: 최소 실행 가능 도구 세트

도구 정의 역시 컨텍스트의 일부라는 점을 놓치기 쉽습니다. 도구 스키마는 모델이 추론을 시작하기도 전에 윈도우를 차지하고, 잘못 설계되면 매 호출마다 모델의 판단을 흔듭니다.

Anthropic은 좋은 도구의 조건을 셋으로 요약합니다. 도구는 “자족적(self-contained)이고, 오류에 견고(robust to error)하며, 의도된 용도에 극도로 명확(extremely clear)“해야 합니다.

자족적이라는 것은 외부 맥락 없이도 무엇을 하는지 알 수 있다는 뜻이고, 오류에 견고하다는 것은 잘못된 입력이 와도 무너지지 않고 의미 있는 에러를 돌려준다는 뜻입니다.¹

대표적 실패 모드는 “너무 많은 기능을 덮거나 어떤 도구를 쓸지 모호한 결정 지점을 낳는 비대한 도구 세트(bloated tool sets)“입니다. 도구가 많고 기능이 겹칠수록, 모델은 매 순간 “이 상황에서 어느 도구를 써야 하나”라는 결정에 토큰과 주의를 소모합니다.¹

이를 판별하는 간단한 테스트가 있습니다 — “인간 엔지니어가 특정 상황에서 어느 도구를 써야 할지 확실히 말하지 못하면, AI 에이전트도 더 잘할 수 없습니다”. 도구 세트가 사람에게도 헷갈린다면 그것은 설계 결함이지 모델의 한계가 아닙니다.¹

최적화 목표는 최소 실행 가능 도구 세트(minimal viable set of tools)입니다. 과제를 수행하는 데 꼭 필요한 도구만 큐레이션하면, 긴 상호작용에서도 컨텍스트를 신뢰성 있게 유지하고 가지치기하기 쉬워집니다.¹

적시 검색과 점진적 공개

데이터를 미리 전부 전처리해 컨텍스트에 박아두는 대신, 에이전트는 적시(just-in-time) 전략을 씁니다. 파일 경로·저장된 쿼리·웹 링크 같은 가벼운 식별자만 들고 있다가, 도구로 런타임에 필요한 데이터를 동적으로 불러오는 방식입니다.¹

구체적 예가 명료합니다. Claude Code가 대형 데이터베이스를 분석할 때, 전체 데이터 객체를 컨텍스트에 올리지 않습니다.

대신 타깃 쿼리를 작성해 결과를 파일에 저장하고, head나 tail 같은 Bash 명령으로 필요한 부분만 들여다봅니다. 100만 행짜리 테이블 전체를 윈도우에 쏟아붓는 대신, 그 테이블을 가리키는 방법과 훑는 명령만 컨텍스트에 두는 것입니다.¹

이 발상은 점진적 공개(progressive disclosure)와 같은 뿌리를 둡니다. 에이전트는 탐색을 통해 관련 컨텍스트를 점진적으로 발견하며, “각 상호작용이 다음 결정을 알리는 컨텍스트를 산출”합니다.

한 번에 모든 것을 보는 대신, 한 걸음 내디딘 결과가 다음 걸음의 입력이 됩니다. 같은 원리가 스킬 기본형의 3단계 로딩에도 흐릅니다.¹

탐색을 떠받치는 신호가 메타데이터입니다. 폴더 계층, 명명 규칙, 타임스탬프는 그 자체로 “언제 어떻게 이 정보를 쓸지”를 모델에게 알려 줍니다. tests/ 아래에 있고 _spec.ts로 끝나는 파일은 테스트라는 사실이, 최근 타임스탬프는 그 파일이 현재 작업과 관련 있을 가능성이 높다는 사실이 별도 설명 없이 전달됩니다.¹

무거운 탐색 자체를 분리하는 또 다른 방법은 서브에이전트입니다. 깨끗한 컨텍스트 윈도우를 가진 전용 에이전트가 상세 검색을 맡고, 본체에는 “응축·증류된 요약(흔히 1,000~2,000토큰)“만 돌려줍니다.

상세 검색 컨텍스트는 서브에이전트 안에 격리되므로, 리드 에이전트는 결과를 종합·분석하는 데 집중하고 본체의 예산이 보존됩니다.¹

컴팩션: 윈도우 한계에 부딪힐 때

긴 작업은 결국 윈도우 한계에 다가갑니다. 컴팩션(compaction)은 한계에 근접한 대화를 요약하고, 그 요약으로 새 컨텍스트 윈도우를 재초기화하는 기법입니다.¹

관건은 무엇을 보존하고 무엇을 버리느냐입니다. Claude Code의 컴팩션 구현은 이 경계를 명시적으로 둡니다.

보존하는 것 — 아키텍처 결정, 미해결 버그, 구현 세부. 이것들은 잃으면 작업이 길을 잃는, 미묘하지만 결정적인 맥락입니다. 버리는 것 — 중복된 도구 출력과 메시지. 이미 반영됐거나 다시 볼 필요 없는 원시 출력은 요약에서 제외됩니다.¹

튜닝에는 순서가 있습니다. 먼저 회상(recall)을 최대화해 컴팩션 프롬프트가 모든 관련 정보를 빠짐없이 잡게 한 다음, 그 위에서 정밀도(precision)를 높이도록 반복해 불필요한 내용을 깎아냅니다. 처음부터 간결함을 노리면 중요한 맥락을 흘릴 위험이 있으므로, “다 담고 줄이는” 방향이 안전합니다.¹

더 가벼운 변형도 있습니다. 도구 결과 비우기(tool result clearing) — 메시지 히스토리 깊숙이 호출된 도구의 원시 결과를, 다시 볼 필요가 없다고 판단되면 제거하는 방식입니다. 전체 대화를 요약하는 컴팩션보다 오버헤드가 작으면서, 오래된 도구 출력이 차지하던 토큰을 회수합니다.¹

구조적 노트 작성: 윈도우 밖의 기억

컴팩션이 윈도우 안을 정리하는 일이라면, 노트 작성은 윈도우 밖에 기억을 두는 일입니다. 에이전트가 컨텍스트 윈도우 바깥의 메모리에 정기적으로 노트를 적어 두고, 나중에 필요할 때 다시 컨텍스트로 끌어오는 방식입니다(agentic memory).¹

전형적 패턴은 to-do 리스트나 NOTES.md 파일입니다. 복잡한 과제의 진행 상황, 핵심 컨텍스트, 의존성을 이런 파일에 적어 두면 — 윈도우를 비우거나 새로 열어도, 심지어 세션을 가로질러도 핵심 정보가 살아남습니다.

Anthropic은 이런 패턴을 1급 기능으로 지원하는 memory tool도 출시했습니다. 파일 기반 시스템으로 컨텍스트 밖 정보를 저장·참조하기 쉽게 만든 도구입니다.¹

노트 작성의 메커니즘과 운영(어디에 저장하고 언제 다시 읽을지)은 메모리와 상태 장에서 본격적으로 다룹니다. 여기서는 “윈도우가 유한하므로, 잃으면 안 되는 것은 윈도우 밖에 적는다”는 원리만 짚어 둡니다.

프롬프트 캐싱: 안정적인 것을 위에 두기

같은 접두부(prefix)를 반복해서 보내는 작업이라면, 그 부분을 캐시해 처리 시간과 비용을 크게 줄일 수 있습니다. 가격 배수는 명확합니다 — 캐시 읽기는 기본 입력 대비 약 0.1배(약 10%, 즉 90% 절약), 5분 TTL 캐시 쓰기는 1.25배, 1시간 TTL 쓰기는 2배입니다.

Opus 4.8 기준으로 환산하면 기본 입력 $5/MTok에 대해 5분 쓰기 $6.25, 1시간 쓰기 $10, 캐시 히트·리프레시는 $0.50입니다.³

손익분기는 TTL에 따라 다릅니다. 5분 캐시는 두 번째 요청에서 본전을 넘기고(1.25배 + 0.1배 = 1.35배 vs 캐시 없는 2배), 1시간 캐시는 쓰기 비용이 두 배라 최소 세 번은 읽어야 이득입니다(2배 + 0.2배 = 2.2배 vs 3배).³

최소 토큰: 모델마다 다르다

캐시되려면 접두부가 최소 토큰 수를 넘겨야 하며, 이 값은 모델마다 다릅니다.³

모델	최소 캐시 토큰
Opus 4.8, Sonnet 4.6, Sonnet 4.5	1,024
Opus 4.7, Haiku 3.5	2,048
Opus 4.6, Opus 4.5, Haiku 4.5	4,096
Fable 5, Mythos 5	512 (단 Bedrock에선 1,024)

분기점·계층·자동 접두부 검사

캐싱은 본질적으로 접두부 일치(prefix match)입니다. 접두부 어디든 한 바이트가 바뀌면 그 지점 이후가 전부 무효화됩니다.

그래서 구성 순서가 비용을 좌우합니다 — 렌더 순서는 tools → system → messages이고, 각 레벨은 이전 레벨 위에 쌓입니다. 덜 바뀌는 것을 앞에(도구·시스템), 매번 바뀌는 것을 뒤에(동적 콘텐츠) 두는 것이 기본입니다.

위 도식에서 안정적인 층을 위에, 가변적인 층을 아래에 그린 이유가 이것입니다.³

cache_control 분기점은 요청당 최대 4개까지 둘 수 있습니다.

{
  "system": [
    { "type": "text", "text": "<큰 공유 프롬프트>", "cache_control": { "type": "ephemeral", "ttl": "1h" } }
  ],
  "messages": [{ "role": "user", "content": "요점을 요약해 줘" }]
}

핵심 메커니즘이 둘 있습니다. 첫째, 캐시 쓰기는 분기점에서만 일어납니다 — cache_control로 표시한 블록 하나당 정확히 한 개의 캐시 엔트리(그 블록까지의 prefix 해시)가 생기고, 그보다 앞 위치에는 엔트리를 쓰지 않습니다.

둘째, 자동 접두부 검사입니다 — 분기점에서 prefix 해시를 계산해 매칭되는 엔트리를 찾되, 없으면 한 블록씩 뒤로 걸어가며 검사합니다. 이 lookback은 “분기점당 최대 20블록(분기점 자신 포함)“까지만 진행하고, 거기서도 못 찾으면 중단합니다.³

자주 틀리는 지점: 바뀌는 블록에 분기점

가장 흔한 캐싱 실수는 매 요청마다 바뀌는 블록(예: 타임스탬프가 박힌 user 메시지)에 cache_control을 다는 것입니다. 그 블록의 prefix 해시가 매번 달라지므로, lookback이 더 앞 위치를 뒤져도 일치하는 엔트리가 없어 매 요청이 fresh write만 발생합니다.

캐시는 한 번도 읽히지 않고 쓰기 비용만 계속 나갑니다. 해결은 cache_control을 마지막 정적 블록(공유 시스템 프롬프트의 끝, 결정론적 도구 목록)에 두는 것입니다.³

같은 맥락에서 datetime.now()나 UUID를 시스템 프롬프트에 끼워 넣거나, json.dumps()를 sort_keys 없이 호출해 키 순서가 흔들리면 접두부가 매번 달라져 캐시가 깨집니다.³

무효화 매트릭스

모든 변경이 모든 것을 무효화하지는 않습니다. 캐시는 tools → system → messages 세 층으로 나뉘고, 변경은 해당 층과 그 이후만 무효화합니다.³

변경	tools 캐시	system 캐시	messages 캐시
도구 정의(추가·제거·재정렬)	무효	무효	무효
모델 전환	무효	무효	무효
`speed`·web search·citations 토글	유지	무효	무효
시스템 프롬프트 내용	유지	무효	무효
`tool_choice`·이미지·`thinking` 토글	유지	유지	무효
메시지 내용	유지	유지	무효

따라서 tool_choice를 요청마다 바꾸거나 thinking을 켜고 끄는 것은 tools+system 캐시를 잃지 않습니다. 반대로 도구 정의나 모델을 바꾸면 전체가 다시 쓰여집니다.³

TTL·응답 필드·동시성

TTL 리프레시. 기본 TTL은 5분이고, 캐시 내용이 읽힐 때마다 추가 비용 없이 갱신됩니다 — 트래픽이 끊기지 않으면 캐시가 살아 있습니다. 5분과 1시간 엔트리를 섞어 쓸 때는 1시간 엔트리가 5분 엔트리보다 접두부 앞쪽에 와야 합니다.³

응답 필드로 검증. 응답의 usage에서 세 값을 읽어 캐시가 듣는지 확인합니다 — cache_creation_input_tokens(이번에 새로 쓴 토큰), cache_read_input_tokens(캐시에서 읽은 토큰), input_tokens(마지막 분기점 이후의 캐시 비대상 토큰). 셋의 합이 총 입력입니다. 동일 접두부 요청을 반복하는데도 cache_read_input_tokens가 0이라면, 위에서 본 조용한 무효화 요인이 숨어 있는 것입니다.³

동시성과 프리워밍. 캐시 엔트리는 “첫 응답이 시작된 후에야” 사용 가능해집니다. 따라서 동일 접두부로 병렬 요청을 보내면 모두 full price를 냅니다 — 1개를 먼저 보내 첫 토큰이 스트리밍되기 시작하면 나머지 N−1개를 보내야 캐시를 읽습니다.

캐시 히트는 rate limit에 차감되지 않습니다. 첫 요청의 캐시-미스 지연 자체를 없애려면 시작 시점에 max_tokens: 0 요청을 보내 캐시를 미리 데웁니다(프리워밍). 단 이 프리워밍은 스트리밍·thinking enabled·structured output·강제 tool_choice·배치와는 비호환입니다.³

컨텍스트 파일: CLAUDE.md와 AGENTS.md

세션마다 컨텍스트가 초기화되는 환경에서, 영구 지침을 글로 남겨 두는 장치가 컨텍스트 파일입니다.

CLAUDE.md: 위치·로드·우선순위

CLAUDE.md는 넓은 범위에서 좁은 범위로, 발견 순서대로 로드됩니다.²

관리 정책 — macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux·WSL /etc/claude-code/CLAUDE.md, Windows C:\Program Files\ClaudeCode\CLAUDE.md
사용자 — ~/.claude/CLAUDE.md
프로젝트 — ./CLAUDE.md 또는 ./.claude/CLAUDE.md
로컬 — ./CLAUDE.local.md

로드 메커니즘은 누적입니다 — 작업 디렉터리에서 루트까지 트리를 거슬러 올라가며 발견한 CLAUDE.md·CLAUDE.local.md를 전부 이어 붙입니다(override가 아닙니다). 순서는 루트 → 작업 디렉터리이므로 launch 위치에 가까운 지시가 마지막에 읽히고, 같은 디렉터리에서는 CLAUDE.local.md가 CLAUDE.md 뒤에 붙습니다. 하위 디렉터리의 CLAUDE.md는 launch 시점에는 로드되지 않고, 그 폴더의 파일을 실제로 읽을 때 비로소 포함됩니다.²

블록 레벨 HTML 주석()은 컨텍스트 주입 전에 제거됩니다(단 코드 블록 안의 주석은 유지). monorepo에서 타팀 파일을 배제하려면 claudeMdExcludes(glob, 절대경로 매칭)를 쓰되, 관리 정책 CLAUDE.md는 제외할 수 없습니다.²

CLAUDE.md: @import·시스템 프롬프트가 아님·베스트프랙티스

@path/to/import 구문으로 다른 파일을 가져올 수 있습니다 — 상대·절대 경로 모두 허용하며(상대는 import한 파일 기준), 재귀 import는 최대 깊이 4홉입니다. 코드 스팬·펜스 코드 블록 안의 @는 import 파싱에서 제외되므로 백틱으로 감싼 `@README`는 리터럴로 남고, 백틱 밖의 @README는 import로 동작합니다.

한 가지 유의점 — import한 파일도 launch 시 컨텍스트에 들어가므로, @import는 조직화를 도울 뿐 컨텍스트를 줄이지는 않습니다.²

@AGENTS.md

## Claude Code
- src/billing/ 아래 변경은 plan 모드로 진행한다.
- 커밋 전 `npm test`를 돌린다.

작성 베스트프랙티스는 분명합니다 — 200줄 이하를 목표로(초과하면 컨텍스트가 늘고 준수율이 떨어집니다), 마크다운 헤더·불릿으로 구조화하고, 검증 가능할 만큼 구체적으로 씁니다(“format properly”보다 “2-space indentation”). 서로 모순되는 규칙은 제거합니다(충돌 시 임의로 선택됩니다). 초안은 /init으로 생성하고(기존 파일이 있으면 덮지 않고 개선을 제안), /memory로 로드된 파일을 확인·편집하며, #이나 “기억해” 요청으로 항목을 추가합니다.²

AGENTS.md: 열린 포맷과 Claude Code 연동

AGENTS.md는 여러 코딩 에이전트가 함께 읽는 열린 포맷으로, GitHub code search 기준 6만 개 이상의 오픈소스 프로젝트가 채택했습니다. 지원 도구도 넓어 OpenAI Codex, Google Jules, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie(JetBrains), Amp, Cursor, Gemini CLI, Windsurf 등이 읽습니다.⁴

별도 필수 필드가 없는 “그냥 표준 마크다운”이며, 원하는 헤딩을 자유롭게 씁니다. 전형적 섹션은 프로젝트 개요·빌드/테스트 명령·코드 스타일·테스트·보안·커밋/PR 지침입니다.

역할 분담도 분명합니다 — README는 인간용으로 간결하게 유지하고, AGENTS.md가 에이전트용 상세 컨텍스트를 담습니다. 저장소 루트에 두고 하위 디렉터리에 중첩하면 “에이전트가 트리에서 가장 가까운 파일을 자동으로 읽어 가장 가까운 것이 우선(nearest-wins)“하는 규칙을 따릅니다 — 규모를 짐작하게 하는 사례로, OpenAI 메인 레포는 작성 시점에 88개의 AGENTS.md를 두고 있습니다.

어느 경우든 “명시적 user 채팅 프롬프트가 모든 것을 override”합니다.⁴

위 예제의 첫 줄 @AGENTS.md가 공용 지침을 그대로 끌어오고, 그 아래에 Claude 전용 규칙만 덧붙입니다. 가변적인 작업별 절차가 아니라 “매 세션 들고 있어야 할 사실”만 담아 짧게 유지하는 것이 핵심입니다.

요약 · 체크리스트

컨텍스트 엔지니어링이 프롬프트 바깥의 모든 정보를 매 턴 반복해 큐레이션하는 일임을, 그리고 컨텍스트 부패가 n²·짧은 시퀀스 편향·위치 인코딩 보간이라는 세 메커니즘에서 온다는 점을 안다.
시스템 프롬프트는 적정 고도로·구조화해 쓰되 “최소≠짧음”임을, 도구는 인간 엔지니어 판별 테스트를 통과하는 최소 실행 가능 세트로 좁힘을 설명할 수 있다.
적시 검색(head/tail·메타데이터·하이브리드)·컴팩션(보존/폐기·recall→precision·tool result clearing)·노트(NOTES.md·memory tool)·서브에이전트가 각각 어떻게 예산을 아끼는지 안다.
프롬프트 캐싱에서 안정적인 것을 앞에 두고, 모델별 최소 토큰·20블록 lookback·“쓰기는 분기점에서만”·무효화 매트릭스·“바뀌는 블록에 분기점” 실수를 피한다.
CLAUDE.md/AGENTS.md의 로드 순서와 관계(직접 안 읽음 → @import/심링크, user 메시지 전달이라 강제 아님)를 안다.