컨텍스트 엔지니어링은 아키텍처입니다: 650개 파일 이후의 교훈

가이드에서: Claude Code Comprehensive Guide

제 CLAUDE.md는 50줄로 시작했습니다. 6개월 후, 그것은 7개 계층에 걸친 650개 파일의 분산 아키텍처로 성장했습니다. 이 진화 과정에서 드러난 사실은, 컨텍스트 엔지니어링이 파일이 더 많은 프롬프트 엔지니어링이 아니라 매 토큰마다 메모리가 열화되는 기반 위에서의 소프트웨어 아키텍처라는 것입니다.

컨텍스트는 AI 에이전트가 무엇을 생각할 수 있고, 무엇을 기억하며, 무엇을 잊는지를 결정합니다. 다른 모든 설계 결정은 그 하류에 있습니다. 이어지는 내용은 Claude Code를 위한 6개월간의 프로덕션 컨텍스트 엔지니어링 기록입니다: 아키텍처, 실패, 그리고 그 실패를 견뎌낸 시스템.

AI 에이전트를 위한 컨텍스트 엔지니어링은 올바른 지시를 올바른 시점에 에이전트에 전달하면서, 관련 없는 지시는 아예 로드되지 않도록 보장하는 시스템을 설계하는 실천입니다. 좋은 프롬프트 파일을 작성하는 것만으로는 부족합니다. 규칙, 스킬, 훅, 설정, 상태 파일이 각각 특정 생명주기 이벤트에서 로드되는 계층형 아키텍처가 필요합니다. 무엇을 제외하느냐는 무엇을 포함하느냐만큼 중요합니다. 관련 없는 토큰 하나하나가 에이전트가 정확성을 위해 실제로 필요로 하는 컨텍스트를 밀어내기 때문입니다.

요약

Böckeler의 컨텍스트 엔지니어링 아티클(martinfowler.com, 2026)1과 Miessler의 명확한 사고 프레임워크2는 논의를 한 단계 발전시켰지만, 두 글 모두 프로덕션 사용이 요구하는 수준을 과소평가하고 있습니다. 컨텍스트 엔지니어링은 올바른 지시가 올바른 시점에 에이전트에 도달하고, 잘못된 지시는 전혀 로드되지 않는 시스템을 설계하는 일입니다. 제 시스템은 7개 계층 구조에 분산된 9개의 규칙, 40개의 스킬, 19개의 에이전트, 84개의 훅, 14개의 설정 파일을 사용합니다. 아키텍처는 어떤 파일이 언제 로드되는지에 있습니다. 무엇을 제외하느냐는 무엇을 포함하느냐만큼 중요합니다.


컨텍스트는 파일이 아닙니다

매주 올라오는 “CLAUDE.md 작성법” 게시물은 핵심을 놓치고 있습니다. 좋은 CLAUDE.md를 작성하는 것은 필요하지만 충분하지 않습니다. 좋은 코드를 작성하는 것이 좋은 시스템을 구축하는 데 필요하지만 충분하지 않은 것과 같습니다. 아키텍처는 컴포넌트가 어떻게 상호작용하는지를 결정하는 구조입니다. 에이전트 시스템에서는 컨텍스트가 바로 그 구조입니다.

50줄로 시작한 파일은 어느새 모놀리스가 되어 있었습니다. 제 첫 CLAUDE.md는 코딩 표준, 프로젝트 구조, 선호 사항, 수정 사항, 철학, 자격 증명, 활성 프로젝트 상태를 모두 담은 200줄이었습니다. 한 달간은 잘 작동했습니다. 그러다 세 가지가 동시에 발생했습니다:

  1. 파일이 300줄을 넘어서며 자체적으로 충돌하기 시작했습니다(규칙 A는 “단순하게 유지하라”고 했고, 규칙 B는 “철저한 오류 처리를 추가하라”고 했습니다)
  2. 프로젝트 A의 컨텍스트가 프로젝트 B로 새어 들어갔습니다(iOS 전용 규칙이 웹 개발 세션을 오염시켰습니다)
  3. 에이전트가 현재 작업과 무관한 지시를 읽는 데 토큰을 소비했습니다

이 증상들은 문서화 문제가 아니라 아키텍처 문제를 가리킵니다: 결합, 스코프 누수, 자원 낭비. 소프트웨어 아키텍처 결정을 이끄는 것과 같은 힘입니다.3


7개 계층

6개월간의 리팩터링 끝에, 제 컨텍스트 시스템은 7개 계층 구조로 자리 잡았습니다. 각 계층은 고유한 목적을 가지며 특정 시점에 로드됩니다:

계층 내용 로드 시점 수량
1. 코어 CLAUDE.md: 철학, 활성 프로젝트, 수정 사항 매 세션 시작 시 1개 파일, 205줄
2. 규칙 도메인별 제약 조건(API 설계, 보안, 테스팅, Git) 매 세션 시작 시 9개 파일
3. 스킬 절차와 예제를 갖춘 재사용 가능한 지식 모듈 필요 시(호출 또는 훅에 의해 자동 활성화) 40개 디렉터리
4. 에이전트 전문 리뷰어/생성기 사양 필요 시(Task 도구를 통해) 19개 파일
5. 훅 생명주기 이벤트에서의 자동 컨텍스트 주입 이벤트 기반(세션 시작, 커밋 전, 도구 사용 후) 84개 스크립트
6. 설정 수치 매개변수(임계값, 예산, 한도) 훅과 스킬에 의해 참조 14개 JSON 파일
7. 상태 실시간 추적(에이전트 계보, 신뢰도 보정, 비용) 훅에 의해 참조 36개 파일

핵심 통찰은 계층 분리입니다. 규칙은 보편적으로 적용되므로 매 세션 로드됩니다. 스킬은 도메인별이므로 필요할 때 로드됩니다. 훅은 타이밍이 중요하므로 이벤트 시점에 실행됩니다. 650개 파일을 모두 세션 시작 시 로드하면, 에이전트가 첫 사용자 메시지를 읽기도 전에 컨텍스트 창이 소진될 것입니다.4

각 계층의 구체적인 예는 다음과 같습니다:

Layer 1 (Core):     ~/.claude/CLAUDE.md — philosophy, active projects, corrections
Layer 2 (Rules):    ~/.claude/rules/security.md — "Validate ALL user input at boundaries"
Layer 3 (Skills):   ~/.claude/skills/fastapi/SKILL.md — endpoint patterns, Pydantic models
Layer 4 (Agents):   ~/.claude/agents/security-reviewer.md — OWASP-focused review spec
Layer 5 (Hooks):    ~/.claude/hooks/pre-commit-check.sh — blocks commits with TODO/FIXME
Layer 6 (Config):   ~/.claude/config/thresholds.json — {"max_spawn_children": 12}
Layer 7 (State):    ~/.claude/state/agent-lineage.json — tracks active agent tree

계층 구조의 각 파일은 단일 책임과 명확한 로드 트리거를 가집니다. 훅(5계층)은 프로젝트 유형과 관계없이 커밋 전에 실행됩니다. 스킬(3계층)은 FastAPI 작업이 시작될 때만 로드됩니다. 이 구분이 토큰 비용을 결정합니다.


아키텍처를 형성한 세 번의 실패

실패 1: 모놀리식 CLAUDE.md

원래의 CLAUDE.md에는 iOS 규칙, 웹 규칙, API 설계 패턴, Git 규약, 자격 증명 관리, 철학적 원칙이 모두 하나의 파일에 담겨 있었습니다. 에이전트는 SwiftUI를 전혀 다루지 않는 웹 프로젝트를 구축할 때조차 매 세션 그 전부를 읽었습니다.

비용: 관련 없는 컨텍스트가 세션당 약 4,000 토큰을 소비한 것으로 추정됩니다. 50개 세션이면 에이전트가 한 번도 사용하지 않은 지시에 약 200,000 토큰을 쓴 셈입니다.

해결: 도메인별 내용을 rules/ 파일로 추출했습니다. rules/security.md는 매 세션 로드됩니다(보안은 어디에나 적용되기 때문입니다). rules/ios-security.md는 세션이 iOS 프로젝트와 관련될 때만 로드됩니다. 이 결정을 이끈 토큰 경제학은 컨텍스트 창 관리 게시물에서 다룹니다.

실패 2: 낡아버린 스킬

FastAPI 0.109의 예제를 담은 fastapi 스킬을 만들었습니다. 3개월 후, 프로젝트는 다른 패턴을 사용하는 FastAPI 0.115로 넘어가 있었습니다. 스킬은 조용히 낡은 규약을 가르쳤습니다. 에이전트는 작동하는 코드를 만들었지만, 그 코드는 현재 코드베이스와 일치하지 않았습니다.

비용: 새 엔드포인트가 왜 다른 모든 엔드포인트와 다른 의존성 주입 패턴을 사용하는지 추적하느라 45분짜리 디버깅 세션을 치렀습니다. 그 패턴은 코드베이스가 아니라 낡은 스킬에서 온 것이었습니다.

해결: 스킬이 버전이 명시된 문서를 참조하고 “마지막 검증일”을 포함하도록 했습니다. 더 중요한 것은, 품질 루프가 생성된 코드가 기존 코드베이스 패턴과 일치할 것을 요구한다는 점입니다. 이는 스킬의 내용과 관계없이 낡은 스킬로 인한 드리프트를 잡아내는 메타인지적 점검입니다.

실패 3: 서로 다른 계층에서의 규칙 충돌

CLAUDE.md는 “단순한 해결책을 선호하라”고 했습니다. 한 스킬은 “재시도 로직과 서킷 브레이커를 포함한 철저한 오류 처리를 추가하라”고 했습니다. 둘 다 따로 놓고 보면 합리적입니다. 하지만 함께 있으면, 에이전트가 해당 턴에서 어느 지시에 더 무게를 두느냐에 따라 일관성 없는 출력(때로는 최소한, 때로는 과잉 설계)이 나왔습니다.

비용: 예측할 수 없는 출력 품질. 같은 유형의 작업이 세션마다 다른 품질 수준을 만들어 내어 시스템을 신뢰할 수 없게 되었습니다. 실제로 충돌했던 지시는 다음과 같습니다:

# In CLAUDE.md (Layer 1):
- Prefer simple solutions. Avoid over-engineering.

# In skills/fastapi/SKILL.md (Layer 3):
- Add thorough error handling with retry logic and circuit breakers
  for all external API calls.

둘 다 따로 놓고 보면 옳습니다. “단순한 해결책을 선호하라”는 좋은 일반 조언입니다. “외부 호출에 재시도 로직을 추가하라”는 좋은 도메인별 조언입니다. 그러나 둘 다 읽은 에이전트는 때로는 재시도 로직을 생략하고(단순성 원칙을 따라), 때로는 단순한 함수를 과잉 설계합니다(오류 처리 지시를 따라).

해결: 명확한 우선순위 계층을 확립했습니다. CLAUDE.md는 원칙을 정합니다(“단순성 선호”). 규칙은 제약을 정합니다(“모든 사용자 입력 검증”). 스킬은 절차를 정합니다(“FastAPI 엔드포인트를 구축하는 방법은 이렇습니다”). 충돌할 때는 더 구체적인 계층이 우선합니다: 스킬의 절차는 그 스킬이 다루는 특정 작업에 한해 원칙의 지침을 오버라이드합니다. 이 해결 방식은 프로그래밍 언어가 스코프를 처리하는 방식과 같습니다: 로컬이 전역을 오버라이드합니다.5 위 예제에 대한 해결책은 스킬에 단서를 추가하는 것이었습니다: “외부 API 호출에는 재시도 로직을 추가한다(네트워크에 의존하는 코드에서는 이 지시가 일반적인 단순성 원칙을 오버라이드한다. 외부 호출은 간헐적으로 실패하며, 재시도는 과잉 설계가 아니기 때문이다).”


아키텍처 제약으로서의 컨텍스트 예산

컨텍스트 창은 무한하지 않습니다. Claude의 표준 200K 토큰 컨텍스트 창6은 무엇이 그것을 소비하는지 측정해 보기 전까지는 크게 느껴집니다. (API 헤더를 통해 1M 토큰 베타를 사용할 수 있으며, 이는 예산을 비례적으로 늘려 주지만 트레이드오프를 없애 주지는 않습니다. 650개 파일을 로드하면 1M 토큰조차 소진됩니다.)

소비 항목 일반적인 토큰 수 창 대비 비율
시스템 프롬프트 + CLAUDE.md + 규칙 8,000-12,000 4-6%
대화 이력 20,000-80,000 10-40%
파일 읽기(파일당) 5,000-20,000 2.5-10%
도구 출력(호출당) 1,000-10,000 0.5-5%
스킬/에이전트 컨텍스트(필요 시) 3,000-15,000 1.5-7.5%

토큰 소비 측정치는 제가 2025년 8월부터 2026년 2월 사이에 추적한 50개의 Claude Code 세션에서 나온 것입니다.7 90분간의 집중 세션은 일반적인 파일 읽기와 도구 상호작용만으로도 창을 소진할 수 있습니다. 200K 창은 전체 입력 용량이며, 모델의 실효 주의력(높은 충실도로 주의를 기울이는 부분)은 그와 다른, 더 작은 수치라는 점에 유의하십시오. 전체 토큰 사용량이 한도보다 훨씬 낮을 때에도 컨텍스트 예산 규율은 중요합니다. 긴 컨텍스트에서는 처음에 있는 지시가 중간에 있는 지시보다 더 안정적으로 주의를 받기 때문입니다. 컨텍스트 예산은 아키텍처적 트레이드오프를 강제합니다:

항상 로드: 핵심 철학, 활성 수정 사항, 보안 규칙. 세 가지 모두 비용이 낮고(예산의 4-6%) 보편적으로 적용됩니다. 필요 없을 때 로드하는 비용은 무시할 만한 수준입니다. 필요할 때 빠뜨리는 비용은 잘못된 출력입니다.

필요 시 로드: 스킬, 에이전트 사양, 참조 문서. 각 스킬은 창의 5-15%를 소비하며 단일 도메인에만 적용됩니다. 관련 있을 때만 로드하면 실제 작업을 위한 예산을 보존할 수 있습니다. 스킬을 로드하는 트리거는 세션 유형이 아니라 작업 유형입니다. 데이터베이스 마이그레이션을 만난 웹 개발 세션은 시작 시 로드하지 않았더라도 데이터베이스 스킬이 필요합니다.

절대 로드하지 않음: 오래된 핸드오프 문서, 폐기된 설정, 과거 상태. 오래된 파일은 모두 출력을 개선하지 않으면서 예산을 소비합니다. 더 나쁜 것은, 오래된 컨텍스트가 낡은 패턴을 가르쳐 출력을 적극적으로 저하시킨다는 점입니다. 복리 엔지니어링 패턴은 더 이상 토큰 비용만큼의 가치를 내지 못하는 컨텍스트를 주기적으로 정리할 것을 요구합니다.

컨텍스트 예산 관리는 전통적인 소프트웨어에서 데이터베이스 인덱싱, 캐싱 전략, 메모리 관리를 이끄는 트레이드오프와 같은 구조입니다.8 제약은 다르지만(바이트 대신 토큰), 아키텍처적 규율은 동일합니다.


멀티 에이전트 시스템에서의 컨텍스트 전파

메인 에이전트가 Task 도구를 통해 서브에이전트를 생성할 때, 어떤 컨텍스트를 전파할지의 선택이 다른 모든 설계 결정을 좌우합니다. 제 멀티 에이전트 심의 시스템은 10개의 리서치 에이전트를 사용합니다. 각 에이전트는 독립적으로 평가할 수 있을 만큼의 컨텍스트가 필요하지만, 공유 컨텍스트가 너무 많으면 보이드 게시물에서 기록한 수렴 문제가 발생합니다: 너무 많은 컨텍스트를 공유하는 에이전트는 동일한 결론을 내놓습니다.

전파 규칙:

컨텍스트 유형 전파 여부 이유
핵심 철학 예 에이전트 간 일관성
도메인 규칙 예 공유 품질 기준
작업별 지시 예 실제 작업
대화 이력 아니요 독립성을 위해 격리 필요
다른 에이전트의 발견 사항 아니요(종합 단계까지) 조기 수렴 방지
스킬 절차 선택적 에이전트의 역할에 관련된 스킬만

Ralph 아키텍처는 관련된 문제를 해결합니다: 에이전트(병렬 프로세스) 간이 아니라 시간(반복)에 걸친 컨텍스트 전파입니다. 둘 다 같은 원칙을 공유합니다: 제약과 원칙은 전파하고, 구현 세부 사항은 격리합니다.

실전에서의 전파

구체적인 예를 보면 트레이드오프가 분명해집니다. 메인 에이전트가 보안 리뷰어 서브에이전트를 생성할 때, Task 프롬프트에는 다음이 포함됩니다:

## Propagated Context
- Core philosophy: Quality is the only variable (from CLAUDE.md)
- Security rules: OWASP Top 10, input validation at boundaries (from rules/security.md)
- Task: Review the authentication endpoint changes in app/auth.py

## NOT Propagated
- The main agent's conversation history (50+ messages about UI layout)
- Findings from the architecture reviewer (would bias security analysis)
- The FastAPI skill (irrelevant to a security-focused review)

보안 리뷰어는 40,000 토큰이 아닌 2,000 토큰의 컨텍스트를 받습니다. UI 결정에 주의가 분산되거나 다른 에이전트의 결론에 편향되는 일 없이, 보안 기준에 따라 코드를 평가합니다. 이 격리가 독립적인 평가를 만들어 냅니다. 보안 리뷰어와 아키텍처 리뷰어가 각자 독립적으로 같은 우려를 지적한다면, 한 리뷰어가 다른 리뷰어의 보고서를 보고 동의한 경우보다 그 발견의 신뢰도가 높습니다.


컨텍스트 품질 관찰

토큰 수는 대리 지표입니다. 컨텍스트 품질의 진짜 척도는 이것입니다: 에이전트가 첫 시도에서 올바른 출력을 내놓는가?

50개 세션을 추적한 끝에, 세 가지 품질 신호를 확인했습니다:

첫 시도 성공률. 에이전트의 첫 응답이 수정 없이 통과하는 경우는 얼마나 됩니까? 모놀리식 CLAUDE.md에서는 그 비율이 대략 60%였습니다. 7계층 아키텍처 이후에는 약 80%로 올랐습니다. 개선은 관련 없는 컨텍스트의 제거(방해 요소 감소)와 도메인별 스킬의 추가(관련 지식 증가)에서 비롯되었습니다.9

추적 로그에서 뽑은 대표적인 전후 비교입니다. 작업은 동일합니다: “API 엔드포인트에 레이트 리미팅을 추가하라.”

이전(모놀리식 CLAUDE.md, 2025년 7월). 에이전트의 첫 응답은 프로젝트에서 사용하지 않는 레이트 리미팅 라이브러리를 임포트했습니다(iOS 규칙, 보안 규칙, 150줄의 무관한 내용과 함께 로드된 낡은 FastAPI 스킬의 예제를 따른 것입니다). 수정 내용은 “app/middleware.py에 있는 기존 RateLimiter 클래스를 사용하라”였습니다. 수정 1회, “사실 오류: 코드베이스 컨텍스트 누락”으로 분류되었습니다.

이후(7계층 아키텍처, 2025년 11월). 같은 유형의 작업, 다른 엔드포인트입니다. 에이전트의 첫 응답은 기존 RateLimiter 미들웨어를 사용했고, 인접 엔드포인트의 매개변수 명명 규칙에 맞췄으며, 패턴의 출처까지 밝혔습니다: “app/middleware.py:42의 레이트 리미팅 패턴을 따릅니다.” 수정은 필요 없었습니다. FastAPI 스킬(3계층)은 필요 시 로드되었고 최신 패턴을 담고 있었습니다. 세션에 iOS 작업이 없었으므로 iOS 규칙은 로드되지 않았습니다.

직접 추적하려면, 첫 응답 이후 각 에이전트 세션을 로그에 “수락” 또는 “수정”으로 태그하고 매달 그 비율을 계산하십시오. 세밀할 필요는 없습니다. 20개 이상의 세션에 걸친 방향성 추세가 정확한 백분율보다 더 유용합니다.

수정 유형. 에이전트에 수정이 필요할 때, 그 오류는 사실에 관한 것(잘못된 API, 잘못된 패턴)입니까, 아니면 판단에 관한 것(잘못된 접근, 잘못된 우선순위)입니까? 사실 오류는 컨텍스트 누락을 나타냅니다: 에이전트에게 올바른 답을 내는 데 필요한 정보가 없었던 것입니다. 판단 오류는 충돌하거나 모호한 컨텍스트를 나타냅니다: 에이전트는 정보를 갖고 있었지만 경쟁하는 지시의 가중치를 잘못 매긴 것입니다. 이 구분이 중요한 이유는 해결책이 다르기 때문입니다. 사실 오류에는 컨텍스트 추가(새 규칙이나 스킬)가 필요하고, 판단 오류에는 컨텍스트 명확화(기존 계층 간 충돌 해소)가 필요합니다. 수정 유형을 추적하면 어느 계층에 주의가 필요한지 드러납니다.

작업 완료 시점의 컨텍스트 압력. 작업이 끝났을 때 컨텍스트 예산은 얼마나 남아 있습니까? 작업이 절반도 끝나기 전에 창이 90% 찼다면, 컨텍스트 아키텍처가 관련 없는 자료를 너무 많이 로드하고 있는 것입니다. 제 훅 시스템에는 사용률이 70%를 넘으면 경고하는 컨텍스트 압력 모니터가 포함되어 있습니다.


세션 둘러보기: 무엇이 언제 로드되는가

실제 작업 중에 7개 계층이 어떻게 상호작용하는지는 구체적인 흐름을 따라가 보면 분명해집니다. 시나리오는 이렇습니다: blakecrosley.com 프로젝트에서 Claude Code에 “/api/ab/event 엔드포인트에 레이트 리미팅을 추가하라”고 요청합니다.

세션 시작(0초). Claude Code는 1계층(CLAUDE.md, 205줄, 약 800 토큰)과 2계층(9개 규칙 파일 전부, 약 3,200 토큰)을 로드합니다. 소비된 컨텍스트 합계는 약 4,000 토큰(200K 창의 2%)입니다. 이제 에이전트는 제가 무엇을 요청하든 관계없이 제 코딩 철학, 보안 요구 사항, API 설계 규약, Git 워크플로를 알고 있습니다.

작업 시작(2초). 에이전트는 작업을 읽고 FastAPI 엔드포인트 수정으로 판단합니다. 5계층(훅)이 실행됩니다: UserPromptSubmit 훅이 현재 날짜와 세션 컨텍스트(약 200 토큰)를 주입합니다. 에이전트는 SwiftUI 스킬, iOS 보안 규칙, Midjourney 프롬프트 스킬을 로드하지 않습니다. 그 파일들은 존재하지만 관련이 없습니다. 이들을 제외해 약 8,000 토큰을 절약합니다.

파일 읽기(5-30초). 에이전트는 app/main.py, 기존 엔드포인트 코드, 테스트 파일을 읽습니다. 파일 하나를 읽을 때마다 5,000-15,000 토큰의 컨텍스트를 소비합니다. 세 파일을 읽고 나면 약 30,000-50,000 토큰(창의 15-25%)이 소비됩니다.

스킬 활성화(필요한 경우). 에이전트에게 FastAPI 전용 패턴이 필요하면 3계층(skills/fastapi/SKILL.md, 약 2,500 토큰)을 로드합니다. 스킬은 세션이 시작되었기 때문이 아니라 작업이 요구하기 때문에 로드됩니다. CSS만 다루는 작업이었다면 FastAPI 스킬은 결코 로드되지 않았을 것입니다.

구현과 검증(30초-5분). 에이전트는 코드를 작성하고, 테스트를 실행하고, 결과를 보고합니다. 작업 완료 시점의 컨텍스트 소비량은 보통 60,000-100,000 토큰(창의 30-50%)입니다. 남은 예산으로 후속 질문, 수정, 또는 같은 세션에서의 두 번째 작업을 처리할 수 있습니다.

핵심 관찰은 이것입니다: 1계층과 2계층은 창의 2%를 소비하며 모든 작업에 적용됩니다. 3-7계층의 내용은 선택적으로 로드되며 관련 있을 때만 5-25%를 소비합니다. 650개 파일을 모두 세션 시작 시 로드한다면 약 150,000-200,000 토큰을 소비하여, 실제 작업을 위한 공간은 거의 남지 않을 것입니다.


분산 아키텍처 패턴

7계층 시스템에는 AI 에이전트에만 고유한 것이 없습니다. 이미 확립된 소프트웨어 패턴을 그대로 반영합니다:

소프트웨어 패턴 컨텍스트 대응
환경 변수 코어 CLAUDE.md(항상 로드, 전역)
설정 파일 규칙(시작 시 로드, 도메인별)
라이브러리/모듈 스킬(필요 시 로드, 자기 완결적)
마이크로서비스 에이전트(격리됨, 프로토콜을 통한 통신)
이벤트 핸들러 훅(생명주기 이벤트에 의해 트리거)
데이터베이스 상태 파일(영속적, 조회 가능)
API 계약 설정 스키마(공유 수치 매개변수)

이 대응은 은유가 아닙니다. 같은 힘(결합, 응집, 스코프, 생명주기)이 동일한 아키텍처 결정을 이끕니다.10 컨텍스트 엔지니어링은 “메모리”가 풍부하고 영속적인 자원이 아니라 희소하고 열화되는 자원인 기반을 위한 소프트웨어 엔지니어링입니다.11

이 아키텍처에 대한 독립적인 검증은 obra/superpowers 프로젝트에서 나옵니다. 이 프로젝트는 Claude Code 컨텍스트를 위해 비슷한 다층 구조를 독자적으로 발전시켰습니다: 전역 파일에 담긴 핵심 원칙, 필요 시 로드되는 도메인 스킬, 그리고 행동 지시와 분리된 검증 절차입니다.12 이러한 수렴은 계층형 아키텍처가 특이한 설계 선택이 아니라 기반의 제약에 대한 자연스러운 대응임을 시사합니다.


핵심 교훈

에이전트 시스템을 구축하는 엔지니어를 위해:

  • 컨텍스트를 문서가 아닌 소프트웨어 아키텍처처럼 설계하십시오. 무엇이 언제 로드되고, 무엇이 무엇을 오버라이드하며, 무엇이 서브에이전트에 전파되는지가 개별 지시보다 에이전트 행동을 더 크게 결정합니다. 코드에 사용하는 것과 동일한 관심사 분리 규율을 적용하십시오.

  • 생명주기별로 계층을 분리하십시오. 보편적 규칙은 매 세션 로드됩니다. 도메인별 지식은 필요 시 로드됩니다. 세션별 상태는 일시적으로 유지됩니다. 하나의 파일에 생명주기를 섞으면, 소프트웨어 아키텍처가 해결하기 위해 존재하는 바로 그 결합 문제가 생깁니다.

AI 워크플로를 확장하는 팀을 위해:

  • 컨텍스트 창을 예산으로 취급하십시오. 시스템 프롬프트, 파일 읽기, 도구 출력이 200K 토큰 창을 소비합니다. 모든 영속적 지시는 작업 메모리와 경쟁합니다. 로드하는 것을 측정하고, 토큰 비용만큼의 가치를 내지 못하는 것은 정리하십시오.

  • 전파 규칙이 멀티 에이전트 품질을 결정합니다. 서브에이전트에는 일관성을 위한 공유 원칙과 독립성을 위한 격리된 상태가 필요합니다. 컨텍스트를 너무 많이 전파하면 수렴이 일어납니다. 너무 적게 전파하면 비일관성이 일어납니다.

실습: 컨텍스트 시스템을 감사하십시오. 다음 디렉터리 구조를 만들고 기존 지시들로 채우십시오:

mkdir -p .claude/{rules,skills,agents,hooks,config,state}
# Move domain-specific sections from CLAUDE.md into rules/
# Move reusable procedures into skills/
# Move agent specs into agents/

그런 다음 답해 보십시오: 매 세션 로드되는 파일 중 필요 시 로드로 바꿔야 할 것은 무엇입니까? 빠져 있는 필요 시 로드 파일은 무엇입니까? 답은 간단한 로그로 추적하십시오. 각 세션에 “첫 시도 정답” 또는 “수정 필요”를 태그하고, 20개 세션 후에 그 비율을 검토하십시오.


자주 묻는 질문

AI 코딩 에이전트를 위한 컨텍스트 파일은 어떻게 구성해야 합니까?

도메인별 내용이 20-30줄을 넘고 적어도 일부 세션에서 관련이 없다면 별도 파일로 추출하십시오. iOS 전용 규칙과 웹 전용 규칙을 같은 CLAUDE.md에 쓰면, 에이전트는 현재 프로젝트와 관계없이 둘 다 읽습니다. 보편적 제약(보안 규칙, 코딩 표준, 철학적 원칙)은 코어 파일에 두십시오. 도메인별 패턴(FastAPI 엔드포인트, SwiftUI 규약, 데이터베이스 쿼리)은 작업이 필요로 할 때만 로드되는 필요 시 로드 파일로 옮기십시오.

스킬이 낡았는지는 어떻게 알 수 있습니까?

두 가지 신호가 있습니다: 에이전트가 작동은 하지만 현재 코드베이스 패턴과 맞지 않는 코드를 만들거나, 프레임워크의 이전 버전에 있던 API나 패턴을 참조하는 경우입니다. 각 스킬에 “마지막 검증일”을 추가하고 분기마다 확인하십시오. 더 중요한 것은 품질 루프(생성된 코드가 기존 패턴과 일치하는가?)로, 스킬의 내용과 관계없이 낡은 스킬로 인한 드리프트를 잡아냅니다.

컨텍스트 예산의 적정 규모는 얼마입니까?

200K 토큰 창이라면 시스템 프롬프트와 규칙(항상 로드)에 4-6%를 확보하고, 대화 이력과 파일 읽기(실제 작업)에 40-60%를 남기며, 필요 시 로드되는 스킬과 에이전트 컨텍스트에 10-15%를 배정하십시오. 작업이 절반도 끝나기 전에 컨텍스트 압력이 70%를 넘는다면 관련 없는 자료를 너무 많이 로드하고 있는 것입니다. 구체적인 비율은 작업의 복잡도에 따라 달라집니다. 여러 파일에 걸친 리팩터링은 단일 함수의 버그 수정보다 더 많은 컨텍스트를 소비합니다.

계층 간에 충돌하는 지시는 어떻게 처리합니까?

스코프 기반 우선순위를 적용하십시오: 더 구체적인 계층이 우선합니다. 스킬(로컬 스코프)은 규칙(모듈 스코프)을 오버라이드하고, 규칙은 CLAUDE.md(전역 스코프)를 오버라이드합니다. 충돌을 발견하면 모델이 확률적으로 해결하도록 맡기지 말고 해결 방식을 명시하십시오. 더 구체적인 계층에 다음과 같은 메모를 추가합니다: “이 특정 컨텍스트에서는 Y 때문에 X라는 일반 원칙을 오버라이드한다.”


이 게시물은 컨텍스트 창 관리(토큰 경제학)와 Ralph 시스템(파일 시스템 메모리)을 기반으로 합니다. Claude Code 훅 시스템이 자동화 계층을 구현합니다. 에이전트 조정 패턴에 대해서는 멀티 에이전트 심의와 보이드에서 에이전트로를 참조하십시오.



  1. Birgitta Böckeler, “Context Engineering for Coding Agents,” martinfowler.com, February 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. Böckeler의 동료 Bharani Subramaniam은 컨텍스트 엔지니어링을 “더 나은 결과를 얻기 위해 모델이 보는 것을 큐레이션하는 것”으로 정의합니다. 이 정의는 정확합니다. 본 게시물은 그 정보가 조직되고 전달되는 구조가 문서화 작업이 아닌 아키텍처 규율이라고 주장합니다. ↩

  2. Daniel Miessler, “How to Talk to AI,” danielmiessler.com, June 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler는 프롬프트 엔지니어링과 컨텍스트 엔지니어링의 기저에 있는 진짜 기술이 명확한 사고, 즉 달성하고자 하는 바를 정확히 표현하는 능력이라고 주장합니다. 이 프레이밍은 컨텍스트에 대해 명확하게 생각하는 것보다 컨텍스트를 조직하는 구조적 규율에 초점을 맞춘 본 게시물을 보완합니다. ↩

  3. 소프트웨어 아키텍처와의 대응은 의도적입니다. Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017, Part III (Design Principles) and Part V (Architecture). Martin은 동일한 힘을 식별합니다: 결합, 응집, 관심사의 분리. AI 컨텍스트 시스템에서의 차이점은 “메모리”가 일시적이고 제한적이라는 점으로, 전통적 아키텍처가 직면하지 않는 제약이 추가됩니다. ↩

  4. 650개 파일 수는 2026년 2월 기준 저자의 측정입니다. 전역 컨텍스트: 약 400개 파일(규칙, 스킬, 에이전트, 훅, 설정, 상태, 문서, 핸드오프). 프로젝트별 컨텍스트(blakecrosley.com): 약 250개 파일(PRD, 문서, 계획, 워크플로, i18n 설정). 세션당 그중 일부만 로드됩니다. ↩

  5. 프로그래밍 언어에서의 변수 스코프 해결(로컬, 감싸는 함수, 전역, 내장)이 직접적인 비유입니다. Python의 LEGB 규칙은 동일한 계층 구조를 정의합니다: 로컬 스코프, 감싸는 함수 스코프, 전역 스코프, 내장 스코프. Python Software Foundation, “Execution Model,” section 4.2.2, “Resolution of names” 참조. docs.python.org/3/reference/executionmodel.html. 스킬(로컬 스코프)은 규칙(모듈 스코프)을 오버라이드하고, 규칙은 CLAUDE.md(전역 스코프)를 오버라이드합니다. LLM의 지시 따르기가 결정적이 아닌 확률적이라는 점에서 비유가 약간 어긋나지만, 아키텍처적 원칙은 유효합니다. ↩

  6. Anthropic, “Models overview,” platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. 현재 모든 Claude 모델(Opus 4.6, Sonnet 4.6, Haiku 4.5)은 200K 토큰 컨텍스트 창을 명시하며, Opus 4.6과 Sonnet 4.6은 베타로 1M 토큰을 지원합니다. ↩

  7. 토큰 소비 측정치는 제가 2025년 8월부터 2026년 2월 사이에 추적한 50개의 Claude Code 세션에서 나온 것입니다. 전체 방법론은 컨텍스트 창 관리를 참조하십시오. ↩

  8. 토큰 예산과 메모리 계층 간의 비유는 Hennessy, J.L. and Patterson, D.A., Computer Architecture: A Quantitative Approach, 6th edition, Morgan Kaufmann, 2017, Chapter 2 (Memory Hierarchy Design)의 프레임워크를 따릅니다. Hennessy와 Patterson의 캐시 계층, 참조 지역성, 각 수준에서의 메모리 접근 비용에 대한 논의는 컨텍스트 엔지니어링에 직접 대응됩니다: 자주 필요한 컨텍스트(L1 캐시 / 코어 규칙)는 가장 빠르게 로드되고, 드물게 필요한 컨텍스트(디스크 / 필요 시 로드되는 스킬)는 참조될 때만 로드됩니다. ↩

  9. 첫 시도 성공률은 첫 응답에 수정이 필요했는지에 대한 저자의 주관적 평가에 기반한 대략적 지표입니다. 통제된 실험이 아닙니다. 방향적 개선(60%에서 80%)은 세션 유형 전반에서 일관되지만, 정밀한 측정치로 인용되어서는 안 됩니다. ↩

  10. James Lewis and Martin Fowler, “Microservices,” martinfowler.com, March 2014. martinfowler.com/articles/microservices.html. Lewis와 Fowler는 마이크로서비스를 “각각 자체 프로세스에서 실행되며 경량 메커니즘으로 통신하는 작은 서비스들의 모음”으로 정의합니다. 그들이 식별한 힘(독립 배포, 분산 거버넌스, 경계 컨텍스트)은 여기서 설명한 컨텍스트 아키텍처의 에이전트 격리 및 프로토콜 기반 통신에 직접 대응됩니다. ↩

  11. “아키텍처로서의 컨텍스트”라는 프레이밍은 Xu et al., “Everything is Context: Agentic File System Abstraction for Context Engineering,” arXiv, December 2025. arxiv.org/abs/2512.05470에서 가져왔습니다. 이 논문은 생성형 AI 시스템에서 컨텍스트를 관리하기 위한 파일 시스템 추상화를 제안하며, 다양한 지식 산출물, 메모리, 도구를 토큰 제약 안의 컨텍스트로 다룹니다. 이 이론적 프레임워크는 여기서 설명한 실용적 아키텍처를 뒷받침합니다. ↩

  12. obra/superpowers, github.com/obra/superpowers. superpowers 프로젝트는 에이전트 컨텍스트를 핵심 지시, 필요 시 로드되는 스킬, 검증 절차로 구성합니다. 독립적으로 개발되었음에도 이 구조는 여기서 설명한 7계층 아키텍처와 수렴했습니다. 이러한 수렴은 계층형 컨텍스트가 제한된 컨텍스트 창에 대한 자연스러운 아키텍처적 대응이라는 주장을 뒷받침합니다. ↩

관련 게시물

Ralph 루프: 자율 AI 에이전트를 밤새 운영하는 방법

중지 훅, 스폰 예산, 파일 시스템 메모리를 활용한 자율 에이전트 시스템을 구축했습니다. 실패 사례와 실제로 코드를 출시하게 된 과정을 공유합니다.

10 분 소요

멀티 에이전트 숙의: 합의가 버그일 때

멀티 에이전트 숙의는 단일 에이전트 시스템이 놓치는 실패를 포착합니다. 아키텍처, 실패한 접근법, 그리고 실제로 구축할 가치가 있는 것을 소개합니다.

17 분 소요

프로테제 패턴

희소 전문가 접근 권한을 가진 7B 모델이 50배 크기의 에이전트와 대등합니다. 일상 작업은 소형 모델에, 판단은 프론티어 모델에 라우팅.

10 분 소요