← 모든 글

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

8분 소요

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

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

요약

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

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

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

제 첫 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

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

실패 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는 “단순한 솔루션을 선호하라”고 했습니다. 한 스킬은 “재시도 로직과 서킷 브레이커를 포함한 철저한 오류 처리를 추가하라”고 했습니다. 각각 따로 놓으면 합리적이었습니다. 하지만 함께 사용하면 에이전트가 특정 턴에서 어떤 지시에 더 큰 가중치를 두느냐에 따라 일관성 없는 결과가 생성되었습니다 (때로는 최소한으로, 때로는 과도하게 엔지니어링됨).

비용: 예측 불가능한 출력 품질. 동일한 유형의 작업이 세션마다 다른 품질 수준을 만들어내어 시스템의 신뢰성을 떨어뜨렸습니다.

해결책: 명확한 우선순위 계층을 확립했습니다. CLAUDE.md는 원칙을 설정합니다 (“단순함을 선호하라”). 규칙은 제약을 설정합니다 (“모든 사용자 입력을 검증하라”). 스킬은 절차를 설정합니다 (“FastAPI 엔드포인트를 이렇게 만들어라”). 충돌 시, 더 구체적인 계층이 우선합니다: 스킬의 절차가 해당 스킬이 다루는 특정 작업에 대해 원칙의 가이드라인을 오버라이드합니다. 이 해결 방식은 프로그래밍 언어가 스코프를 처리하는 방식을 그대로 반영합니다: 로컬이 글로벌을 오버라이드합니다.5

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

컨텍스트 창은 무한하지 않습니다. Claude의 200K 토큰 컨텍스트 창6은 무엇이 이를 소비하는지 측정하기 전까지는 넉넉해 보입니다:

소비 항목 일반적인 토큰 수 창 대비 비율
시스템 프롬프트 + 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분간의 집중적인 세션은 일반적인 파일 읽기와 도구 상호작용만으로도 컨텍스트 창을 고갈시킬 수 있습니다. 컨텍스트 예산은 아키텍처적 트레이드오프를 강제합니다:

항상 로드 핵심 철학, 활성 수정 사항, 보안 규칙. 세 가지 모두 저렴하고 (예산의 4-6%) 보편적으로 적용됩니다.

필요 시 로드 스킬, 에이전트 사양, 참조 문서. 각각 스킬당 컨텍스트 창의 5-15%를 소비하며 단일 도메인에만 적용됩니다. 관련이 있을 때만 로드하면 실제 작업을 위한 예산이 보존됩니다.

절대 로드하지 않음 낡은 핸드오프 문서, 더 이상 사용되지 않는 설정, 과거 상태. 낡은 파일은 모두 출력을 개선하지 않으면서 예산만 소비합니다. 복리 엔지니어링 패턴은 더 이상 토큰 비용만큼의 가치를 제공하지 못하는 컨텍스트를 주기적으로 정리할 것을 요구합니다.

컨텍스트 예산 관리는 전통적인 소프트웨어에서 데이터베이스 인덱싱, 캐싱 전략, 메모리 관리를 이끄는 트레이드오프를 그대로 반영합니다.8 제약의 대상이 다를 뿐 (바이트 대신 토큰), 아키텍처적 규율은 동일합니다.

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

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

전파 규칙:

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

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

컨텍스트 품질 측정

토큰 수는 대리 지표입니다. 컨텍스트 품질의 실제 척도는 다음과 같습니다: 에이전트가 첫 시도에서 올바른 결과를 생성하는가?

50개 세션을 추적한 후, 세 가지 품질 신호를 식별했습니다:

첫 시도 성공률. 에이전트의 첫 번째 응답이 수정 없이 통과하는 빈도는 얼마나 되는가? 모놀리식 CLAUDE.md에서는 약 60%였습니다. 7개 계층 아키텍처 도입 후 약 80%로 상승했습니다. 개선은 무관한 컨텍스트 제거 (산만함 감소)와 도메인별 스킬 추가 (관련 지식 증가)에서 비롯되었습니다.9

수정 유형. 에이전트가 수정을 필요로 할 때, 그 오류가 사실적 오류 (잘못된 API, 잘못된 패턴)인가 판단 오류 (잘못된 접근 방식, 잘못된 우선순위)인가? 사실적 오류는 컨텍스트 부족을 나타냅니다. 판단 오류는 충돌하거나 모호한 컨텍스트를 나타냅니다. 수정 유형을 추적하면 어떤 계층에 주의가 필요한지 알 수 있습니다.

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

분산 아키텍처 패턴

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

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

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

핵심 교훈

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

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

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

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

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

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

이 게시물은 컨텍스트 창 관리 (토큰 경제학)와 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. Martin은 동일한 힘을 식별합니다: 결합, 응집, 관심사의 분리. AI 컨텍스트 시스템에서의 차이점은 “메모리”가 임시적이고 제한적이라는 점으로, 전통적 아키텍처가 직면하지 않는 제약이 추가됩니다. ↩

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

  5. 프로그래밍 언어에서의 변수 스코프 해결 (로컬, 감싸는 함수, 전역, 내장)이 직접적인 비유입니다. Python의 LEGB 규칙은 동일한 계층 구조를 정의합니다: 로컬 스코프, 감싸는 함수 스코프, 전역 스코프, 내장 스코프. Python Software Foundation, “Execution Model,” 섹션 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의 프레임워크를 따릅니다. 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 시스템에서 컨텍스트를 관리하기 위한 파일 시스템 추상화를 제안하며, 다양한 지식 아티팩트, 메모리, 도구를 토큰 제약 내의 컨텍스트로 취급합니다. 이 이론적 프레임워크는 여기에 기술된 실용적 아키텍처를 뒷받침합니다. ↩