Jeremy

Prompt Engineering에서 Context Engineering으로 — 에이전트 시스템을 다시 설계한 이유

21 min readEnglish
Claude CodeAIContext Engineering오픈소스

들어가며

이전 글에서 3개 프로젝트를 거치며 에이전트 시스템을 구축한 과정을, 그 다음 글에서는 이를 npm 패키지로 만든 이야기를 다뤘다. 8개 에이전트, 8개 스킬, 3개 프리셋. 잘 동작했고, 나름 만족스러웠다.

그러다 Agent Skills for Context Engineering이라는 리포지토리를 발견했다. 읽으면서 깨달은 것은, 내 시스템이 작동하는 이유를 나 자신도 정확히 설명하지 못하고 있었다는 것이다.

교집합 필터로 불필요한 스킬을 제거한 것은 경험에서 나온 직관이었다. 게이트 시스템은 "에이전트가 폭주해서" 만든 것이었다. 하지만 왜 교집합이 합집합보다 나은지, 왜 게이트 없으면 품질이 떨어지는지를 개념적으로 설명할 프레임워크가 없었다.

Context Engineering이 그 프레임워크를 제공했다. 그리고 그 프레임워크로 에이전트 시스템을 다시 보자, 개선해야 할 지점이 선명하게 보였다. 이 글은 그 과정의 기록이다.

Prompt Engineering ≠ Context Engineering

Agent Skills for Context Engineering의 첫 번째 스킬인 context-fundamentals에서 가장 인상 깊었던 문장은 이것이다:

Context is the complete state available to a language model at inference time — system instructions, tool definitions, retrieved documents, message history, and tool outputs.

Prompt Engineering은 "어떻게 좋은 프롬프트를 쓸까"에 집중한다. 하나의 메시지를 정교하게 다듬는 것이다. Context Engineering은 다르다. 모델의 추론 시점에 존재하는 모든 상태를 설계하는 것이다.

이전에 내가 했던 것은 주로 Prompt Engineering이었다. 에이전트 정의 파일의 문구를 다듬고, 스킬의 지시사항을 정교하게 쓰고, 게이트의 조건을 세밀하게 조정했다. 물론 그것도 중요하다. 하지만 모델에 전달되는 전체 맥락 — 시스템 프롬프트, 도구 정의, 메시지 히스토리, 도구 출력 — 을 하나의 설계 대상으로 본 적은 없었다.

그리고 이 관점의 전환이 핵심이었다.

Prompt Engineering          Context Engineering
─────────────────           ─────────────────────
프롬프트 텍스트              모델에 전달되는 모든 상태
한 번 잘 쓰면 끝            지속적인 큐레이션
메시지 단위                  세션 전체 단위
"무엇을 말할까"             "무엇을 보여줄까, 무엇을 숨길까"

첫 번째 깨달음: 컨텍스트는 유한 자원이다

context-fundamentals가 강조하는 핵심 개념은 **어텐션 예산(Attention Budget)**이다.

Context must be treated as a finite resource with diminishing marginal returns.

컨텍스트 윈도우가 128K, 200K로 커졌다고 해서 다 채워도 되는 게 아니다. 토큰 수가 늘어나면 n² 개의 쌍 관계가 생기고, 모델의 주의력이 분산된다. 더 많이 넣을수록 더 잘하는 게 아니라, **수확 체감(diminishing returns)**이 발생한다.

이것은 v0.1.0에서 경험으로 깨달은 것의 이론적 근거였다. 에이전트에 합집합으로 스킬을 넣었을 때 Backend 에이전트가 visual-qa 체크리스트를 출력한 이유가 바로 이것이다. 불필요한 스킬이 어텐션 예산을 낭비하고, 에이전트가 관련 없는 규칙에 반응한 것이다.

교집합 필터가 효과적이었던 이유도 설명된다:

합집합 (v0.1.0 초기)
Backend 에이전트의 컨텍스트:
  시스템 프롬프트 + scoring + visual-qa + tdd-workflow + ...
  → 어텐션이 visual-qa의 "스크린샷 검증" 지시에 반응
  → 백엔드 코드 리뷰에서 스크린샷 요구 🤦
 
교집합 (v0.1.0 수정)
Backend 에이전트의 컨텍스트:
  시스템 프롬프트 + scoring
  → 어텐션이 코드 품질 평가에 집중
  → 정확한 리뷰 출력 ✓

경험적으로 "교집합이 더 낫다"고 알았지만, 왜 그런지는 Context Engineering을 읽고 나서야 정확히 이해했다. 핵심 원칙은 간단하다:

Informativity over exhaustiveness — 필요한 것만 포함하고, 나머지는 제외하라.

두 번째 깨달음: Progressive Disclosure

두 번째로 눈이 갈 수밖에 없었던 개념은 **Progressive Disclosure(점진적 공개)**다.

Load information only when needed. Apply at multiple levels: skill selection, document loading, tool result retrieval.

기존 시스템에서는 모든 스킬 내용이 에이전트 프롬프트에 통째로 주입되었다. scoring 스킬의 전체 기준표, visual-qa의 체크리스트, tdd-workflow의 단계별 가이드 — 에이전트가 시작하는 순간 모든 것이 컨텍스트에 들어갔다.

문제는 에이전트가 항상 모든 스킬을 동시에 필요로 하지 않는다는 것이다. QA Reviewer가 코드 리뷰를 시작할 때 visual-qa 체크리스트는 아직 필요 없다. scoring 기준표부터 본 다음, 시각적 검증 단계에서 visual-qa를 꺼내면 된다.

이것을 3단계 컨텍스트 로딩 모델로 바꿨다:

L1 — Metadata (항상 로드)
  스킬 이름, 한 줄 설명, 활성화 조건
  예: "scoring — 정량적 코드 품질 평가. 코드 리뷰 또는 QA 시 활성화."
 
L2 — Module (조건부 로드)
  핵심 가이드라인, 주요 규칙
  예: scoring의 1000점 기준표 개요
 
L3 — Data (필요 시 로드)
  전체 체크리스트, 상세 기준, 예시
  예: scoring의 항목별 상세 점수 배분

이전에는 모든 스킬이 항상 L3 수준으로 로드되었다. 이제는 에이전트가 시작할 때 L1만 로드하고, 해당 스킬이 필요한 맥락에서 L2, L3을 순차적으로 불러온다.

이것은 실제로 큰 차이를 만들었다. 8개 스킬이 전부 L3로 로드되면 수천 토큰이 컨텍스트를 차지했다. L1만 로드하면 스킬당 2~3줄. 에이전트의 초기 컨텍스트가 가벼워지니, 실제 작업에 더 많은 어텐션 예산을 쓸 수 있게 되었다.

세 번째 깨달음: Tool Consolidation

tool-design 스킬에서 소개하는 Tool Consolidation Principle:

If a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better.

이 원칙을 CLAUDE.md 템플릿에 적용했다. v0.1.0에서는 CLAUDE.md 안에 Context Engineering 관련 지침이 12줄에 걸쳐 상세히 기술되어 있었다. 압축 전략, 컨텍스트 예산, 어텐션 배치 규칙까지 전부.

문제는 CLAUDE.md가 모든 에이전트에 항상 로드된다는 것이다. Frontend 개발자에게 "컨텍스트 압축 시 Anchored Summarization을 사용하라"는 지침은 필요 없다. 그 지침은 오케스트레이터나 장기 세션을 관리하는 에이전트에게만 의미가 있다.

Tool Consolidation 원칙을 적용한 결과:

Before (v0.1.0 CLAUDE.md) — 12줄
─────────────────────────────────
## Context Engineering
- 컨텍스트 예산: 70-80%에서 압축 트리거
- 어텐션 배치: 중요 정보는 시작/끝에
- 압축 전략: Anchored Summarization 사용
- 도구 출력: 관찰 마스킹으로 토큰 절약
- ... (8줄 더)
 
After (v0.2.0 CLAUDE.md) — 3줄
─────────────────────────────────
## Context Engineering
- 자세한 내용은 context-engineering 스킬 참조
- 핵심 원칙: 가장 작은 고신호 토큰 집합으로 최대 효과

상세 내용은 context-engineering 스킬로 위임했다. CLAUDE.md에는 한 줄 원칙만 남기고, 나머지는 필요한 에이전트가 스킬을 통해 접근하게 했다. 이것이 Tool Consolidation이다 — 정보가 어디에 있어야 가장 효과적인지를 설계하는 것.

v0.2.0: 개념을 코드에 적용하다

이 세 가지 깨달음을 종합해서 create-agent-system v0.2.0을 만들었다. 핵심 변경 사항을 정리하면:

1. context-engineering 스킬 신규 추가

.claude/skills/
├── scoring/SKILL.md
├── visual-qa/SKILL.md
├── tdd-workflow/SKILL.md
├── ... (기존 8개 스킬)
└── context-engineering/SKILL.md    ← 신규

이 스킬은 Progressive Disclosure의 L1→L2→L3 모델, 컨텍스트 예산 관리, 압축 전략, 에이전트 간 통신 패턴을 담고 있다. 그리고 이 스킬 자체도 Progressive Disclosure를 따른다 — 에이전트가 처음 참조할 때는 핵심 원칙만, 필요에 따라 상세 기법을 점진적으로 로드한다.

2. CLAUDE.md 템플릿에 6개 공통 규칙 추가

Agent Skills for Context Engineering에서 반복적으로 강조하는 원칙들을 CLAUDE.md 템플릿의 공통 규칙으로 추가했다:

## 공통 규칙
 
1. 단순함 우선 — 요청하지 않은 기능/추상화 추가 금지
2. 정밀한 수정 — 요청된 부분만 변경
3. 탐색 → 계획 → 코딩 → 커밋 워크플로우
4. 보안 — 하드코딩된 시크릿 금지
5. 병렬 처리 — 독립적인 작업은 동시 실행
6. SSOT — 공식 문서가 항상 우선

이 중 SSOT(Single Source of Truth) 원칙은 이전부터 있었지만, context-fundamentals의 "컨텍스트 큐레이션은 일회성이 아니라 지속적 관리"라는 관점을 만나면서 더 강화했다.

3. 훅 강화

Context Engineering 관점에서 보면, 훅은 컨텍스트 오염을 물리적으로 방지하는 도구다:

훅방지하는 컨텍스트 문제
Stop → 코드 단순화복잡한 코드가 다음 세션의 컨텍스트를 오염
Write|Edit → 시크릿 감지비밀키가 컨텍스트에 노출
Task → Telephone Game 방지서브에이전트 체인에서 정보 왜곡

특히 Telephone Game 방지 훅은 multi-agent-patterns 스킬에서 영감을 받았다:

In orchestrator patterns, the main risk is the "telephone game" problem — responses getting distorted as they pass through the orchestrator.

오케스트레이터가 서브에이전트에 작업을 위임할 때, 원래 요구사항이 왜곡되는 문제. 이전에는 프롬프트에 "원문을 그대로 전달하라"고 썼지만, 훅으로 실제 전달 내용을 검증하게 바꿨다.

4. 전 스킬 Agent Skills spec 형식 적용

기존 스킬은 형식이 제각각이었다. 어떤 스킬은 지침만, 어떤 스킬은 체크리스트만, 어떤 스킬은 둘 다 있었다. Agent Skills for Context Engineering의 스킬 형식을 참고해서 모든 스킬에 통일된 구조를 적용했다:

# 스킬 이름
 
## When to Activate
 
- 이 스킬을 활성화해야 하는 구체적 상황
 
## Guidelines
 
- 핵심 규칙과 원칙
 
## Integration
 
- 다른 스킬/에이전트와의 연결점

"When to Activate" 섹션이 핵심이다. 에이전트가 언제 이 스킬을 참조해야 하는지 명확히 함으로써, Progressive Disclosure의 L1 역할을 한다. 에이전트는 모든 스킬의 "When to Activate"만 보고, 현재 맥락에 필요한 스킬만 깊이 읽는다.

5. 압축 기법 구체화

context-compression 스킬에서 배운 기법들을 에이전트 시스템에 적용했다:

Anchored Summarization
─────────────────────
단순 요약: "인증 시스템 구현 중"
앵커드 요약: "인증 시스템 구현 중.
  결정사항: JWT + refresh rotation 채택 (ADR-003).
  완료: 로그인 API, 토큰 저장.
  미결: 갱신 인터셉터에서 race condition 처리 방법."
 
→ 핵심 결정, 완료/미완료 상태, 미결 이슈를 앵커로 보존
→ 컨텍스트 압축 시에도 중요 정보 유실 방지

그리고 Tokens-per-task 개념을 도입했다. "작업당 소비 토큰"을 추적하면, 어떤 에이전트가 컨텍스트를 비효율적으로 사용하는지 파악할 수 있다. 같은 작업을 더 적은 토큰으로 수행하도록 프롬프트를 개선하는 지표가 된다.

왜 이것이 중요한가

v0.1.0에서 v0.2.0으로의 변화를 한 문장으로 요약하면:

경험적 최적화에서 원칙 기반 설계로.

v0.1.0은 "해보니까 이게 낫더라"의 산물이었다. 교집합 필터, 게이트 시스템, 파일 소유권 — 모두 문제를 겪고 나서 해결책을 찾은 것이다. 작동하지만, 왜 작동하는지 설명하기 어려웠다.

v0.2.0은 원칙이 설계를 이끈다. 교집합 필터는 "어텐션 예산 최적화"의 구현이다. Progressive Disclosure는 "수확 체감 관리"의 구현이다. Tool Consolidation은 "정보 배치 최적화"의 구현이다. 원칙이 있으니 새로운 결정을 내릴 때도 일관된 기준이 있다.

v0.1.0 의사결정 과정
─────────────────────
문제 발생 → 해결책 시도 → 효과 확인 → 채택
(경험적, 개별적, 이유를 설명하기 어려움)
 
v0.2.0 의사결정 과정
─────────────────────
원칙 확인 → 현재 상태 진단 → 원칙 기반 설계 → 구현
(체계적, 일관적, 이유를 명확히 설명 가능)

배운 것들

1. "왜 작동하는가"를 설명할 수 있어야 진짜 이해한 것이다

3개 프로젝트를 거치며 꽤 정교한 에이전트 시스템을 만들었다고 생각했다. 하지만 Context Engineering을 읽고 나서야, 내가 만든 것의 원리를 이해했다. 원리를 이해하면 새로운 상황에서도 올바른 결정을 내릴 수 있다. 경험만으로는 겪어보지 않은 상황에서 막힌다.

2. 컨텍스트는 "많을수록 좋다"가 아니다

128K, 200K 토큰이 가용하다고 해서 다 채우는 것은 나쁜 전략이다. 가장 적은 고신호 토큰으로 최대 효과를 내는 것이 목표다. 에이전트에 스킬을 추가할 때마다 "이것이 어텐션 예산 대비 가치가 있는가?"를 물어야 한다.

3. 정보의 위치가 정보의 내용만큼 중요하다

같은 지침이라도 CLAUDE.md에 있으면 모든 에이전트에 항상 로드되고, 스킬에 있으면 필요한 에이전트만 필요한 시점에 로드한다. 어디에 정보를 두느냐가 컨텍스트 효율성을 결정한다. Tool Consolidation은 이 원칙의 구체적 적용이다.

4. 좋은 프레임워크는 경험을 구조화한다

Agent Skills for Context Engineering이 새로운 기법을 알려준 것이 아니다. 내가 이미 경험적으로 하고 있던 것에 이름과 구조를 부여해줬다. "교집합 필터"는 "컨텍스트 예산 최적화"가 되었고, "게이트 시스템"은 "점진적 공개의 인간 체크포인트"가 되었다. 이름이 붙으면 소통할 수 있고, 소통할 수 있으면 개선할 수 있다.

5. 오픈소스는 쌍방향이다

나는 Agent Skills for Context Engineering에서 개념 프레임워크를 가져와 create-agent-system에 적용했다. 반대로, 내가 3개 프로젝트에서 검증한 구체적 패턴(교집합 필터, 프리셋 시스템, 게이트)은 그 프레임워크의 실전 사례가 된다. 이론이 실전을 이끌고, 실전이 이론을 검증하는 순환. 이것이 오픈소스의 진짜 가치다.

마치며

create-agent-system 글의 마지막 문장에서 "커뮤니티의 경험이 더해져야 진짜 완성된다"고 썼다. 이번 v0.2.0이 정확히 그 사례다. 다른 개발자의 개념 프레임워크가 내 실전 경험과 만나서, 더 나은 도구가 탄생했다.

npx create-agent-system@latest

v0.2.0에는 context-engineering 스킬, Progressive Disclosure 기반 컨텍스트 로딩, 강화된 훅 시스템이 포함되어 있다.

GitHub: github.com/jeremy-kr/create-agent-system

참고한 리포지토리: Agent Skills for Context Engineering — Context Engineering의 개념과 실전 패턴을 담은 오픈 스킬 컬렉션. 에이전트 시스템을 만드는 사람이라면 반드시 읽어볼 가치가 있다.