Context Engineering — AI 코딩 에이전트에 맥락을 주입하는 우선순위 체계

같은 질문, 다른 답 — 맥락이 엉키면 생기는 일

AI 코딩 에이전트를 본격적으로 쓰다 보면, 에이전트에게 주입되는 맥락(context)이 하나가 아니라는 걸 깨닫게 됩니다. 프로젝트 설정 파일, 과거 피드백 기록, 스킬 정의서, RAG로 검색한 지식 — 이 모든 것이 동시에 에이전트의 컨텍스트 윈도우에 들어갑니다.

문제는 이것들이 서로 다른 말을 할 때입니다.

예를 들어, 프로젝트 설정 파일에는 "파일 삭제는 항상 사용자 확인을 받아라"라고 써 있는데, 과거 피드백 메모리에는 "묻지 말고 바로 진행해라"라고 기록되어 있다면? 에이전트는 어느 쪽을 따라야 할까요?

실제로 11개 스킬을 운영하면서 이런 충돌을 여러 번 겪었습니다. 그래서 맥락에도 우선순위가 필요하다는 결론에 도달했습니다.

맥락 소스가 5개나 된다고?

Claude Code 기반으로 구축한 개인 개발 환경에서 에이전트에게 주입되는 맥락 소스는 5가지입니다. 각각의 역할이 다릅니다.

소스	무엇인가	비유
CLAUDE.md	프로젝트 루트의 설정 파일. 디렉토리 구조, 도구 경로, 코딩 규칙 등	회사 사규
Auto Memory	세션을 넘어 유지되는 사용자 피드백과 선호도 기록	선임의 OJT 메모
SKILL.md	각 스킬의 절차 정의서. 입력 스키마, 실행 단계, 실패 처리까지	업무 매뉴얼
RAG	벡터 DB에서 실시간 검색한 관련 지식 조각들	필요할 때 찾아보는 사전
memory-store	텔레그램 챗봇 전용 3계층 메모리 (단기/장기/에피소드)	다른 부서의 업무일지

이 중 처음 4개가 Claude Code 세션에서 실제로 사용됩니다. 문제는 이것들이 각각 독립적으로 동작하고 있었다는 점입니다. 언제 어떤 맥락을 로딩해야 하는지, 충돌하면 어떻게 해야 하는지 — 정책이 없었습니다.

Andrej Karpathy의 한마디: "Context Window = RAM"

Karpathy는 LLM의 컨텍스트 윈도우를 컴퓨터의 RAM에 비유했습니다. RAM이 크다고 프로그램이 잘 돌아가는 게 아니듯, 컨텍스트 윈도우가 넓다고 AI가 잘 작동하는 게 아닙니다. 어떤 데이터를 어떤 순서로 올리느냐가 성능을 결정합니다.

운영체제가 메모리를 관리하듯, AI 에이전트에게도 맥락 관리 정책이 필요합니다.

• 어떤 맥락이 항상 상주해야 하는가 (커널 코드처럼)
• 어떤 맥락이 필요할 때만 로딩되면 되는가 (라이브러리처럼)
• 공간이 부족할 때 무엇을 먼저 내려야 하는가 (페이지 교체처럼)

이 비유가 정확히 맞아떨어지는 것이, 실제 컨텍스트 윈도우에는 토큰 한계가 있고, 불필요한 맥락이 많으면 정작 중요한 정보가 묻히기 때문입니다.

5단계 우선순위 체계

Anthropic의 Context Engineering 프레임워크에서 분류한 맥락 역할(Authority, Constraint, Rubric, Exemplar, Metadata)을 참고하여, 실제 환경에 맞는 우선순위 체계를 정의했습니다.

우선순위	소스	역할	로딩 시점	비유
1	CLAUDE.md	Authority — 절대적 규칙	항상 자동	헌법
2	Auto Memory	Constraint — 경험에서 온 제약	세션 시작 자동	판례
3	SKILL.md	Exemplar — 절차와 패턴	스킬 트리거 시	업무 매뉴얼
4	RAG	Metadata — 참고 지식	JIT 동적 로딩	백과사전
5	memory-store	별도 채널 전용	미사용	타부서 문서

각 단계가 왜 이 순서인지 설명하겠습니다.

1순위: CLAUDE.md — "이것만은 반드시"

CLAUDE.md는 프로젝트의 불변 규칙입니다. "GPU 작업은 반드시 스케줄러를 거쳐야 한다", "한국어로 소통한다" 같은 것들이죠. 이것은 어떤 상황에서도 무시되면 안 됩니다.

Claude Code가 세션을 시작하면 가장 먼저 CLAUDE.md를 읽습니다. 시스템 프롬프트 직후에 로딩되므로, 다른 모든 맥락보다 우선합니다.

2순위: Auto Memory — "지난번에 이렇게 해달라고 했잖아"

Auto Memory에는 "rm 명령은 allow 목록에 추가하지 마라", "서버 코드 수정 후 재시작 필요하면 묻지 말고 바로 재시작해라" 같은 피드백이 저장됩니다.

이것은 CLAUDE.md에 없는 경험적 제약입니다. 사용자가 여러 세션에 걸쳐 쌓아온 행동 교정 기록이므로, 스킬 정의나 RAG 검색 결과보다 우선해야 합니다. 메모리에 "블로그 드래프트는 반드시 HTML로 작성하라"라고 있으면, RAG에서 찾은 마크다운 예시보다 이 피드백이 우선합니다.

3순위: SKILL.md — "이 작업은 이 순서로"

각 스킬의 SKILL.md는 해당 작업의 구체적 절차를 정의합니다. 블로그 스킬이라면 "노트 확인 → RAG 검색 → 드래프트 생성 → 금칙어 검증 → 발행"이라는 파이프라인이 여기에 있습니다.

스킬은 트리거될 때만 로딩되므로, 불필요한 스킬의 맥락이 컨텍스트 윈도우를 차지하지 않습니다.

4순위: RAG — "관련 지식이 있는데 참고해봐"

RAG 검색 결과는 참고 자료입니다. 유용하지만, 규칙이나 피드백을 덮어쓸 수 있는 권한은 없습니다. "이런 비슷한 사례가 있었으니 참고해서 작업해"라는 수준입니다.

JIT(Just-In-Time)으로 필요한 시점에만 로딩하므로, 세션 시작부터 컨텍스트를 차지하지 않습니다.

스킬별로 다른 맥락이 필요하다

모든 스킬이 같은 맥락을 필요로 하지 않습니다. 11개 스킬을 분석해보면 크게 3가지 유형으로 나뉩니다.

유형 1: 지식 집약형 — RAG + self-learning 모두 필요

블로그 작성, 캘린더 리뷰, 가족 연대기 같은 스킬은 외부 지식이 결과 품질에 직접 영향을 미칩니다. 이전에 쓴 글과 중복되지 않는지, 관련 배경지식이 있는지를 RAG로 확인하고, 과거에 같은 유형의 작업에서 실패한 경험(self-learning repair)도 참조합니다.

유형 2: 실행 집약형 — self-learning만 필요

가족앨범 관리, 젬마 챗봇 개발 같은 스킬은 코드 실행이 핵심입니다. RAG에서 가져올 지식보다는, "지난번에 VLM이 OOM으로 죽었으니 배치 크기를 줄여라" 같은 실패 복구 패치가 더 중요합니다.

유형 3: API 직결형 — 추가 맥락 불필요

GitHub 이슈 리뷰, PR 리뷰 같은 스킬은 외부 API를 직접 호출해서 데이터를 가져오므로, RAG나 self-learning이 필요 없습니다. SKILL.md의 절차 정의만으로 충분합니다.

이 분류를 맥락 로딩 매트릭스로 문서화해서 CLAUDE.md에 넣었습니다. 에이전트가 스킬을 실행할 때 이 매트릭스를 참조해서 필요한 맥락만 로딩합니다.

적재량 관리 — 맥락도 과하면 독이 된다

"많이 주면 많이 알겠지"라는 생각은 위험합니다. Anthropic의 연구에 따르면, 컨텍스트 윈도우에 관련 없는 정보가 많아질수록 정작 중요한 정보를 놓치는 확률이 올라갑니다(이를 "lost in the middle" 문제라고 합니다).

그래서 소스별 적재량 상한을 정했습니다.

맥락 소스	상한	근거
RAG 검색 결과	최대 5건, score ≥ 0.3	낮은 관련도 결과는 노이즈
RAG 원본 파일	최대 3개, 각 500자 발췌	전문 읽기는 토큰 낭비
self-learning repairs	최대 3개	너무 많으면 판단 혼란
전체 추가 맥락	스킬당 ~3,000 토큰	핵심 작업 공간 확보

스킬당 약 3,000 토큰이면 A4 용지 2장 정도입니다. 이 안에서 해당 스킬에 필요한 모든 추가 맥락을 담아야 합니다. 부족해 보이지만, 실제로는 CLAUDE.md(1순위)와 SKILL.md(3순위)가 이미 핵심 정보를 담고 있으므로 추가 맥락은 보충 역할이면 충분합니다.

왜 Hook이 아닌 SKILL.md로 맥락을 주입하는가

맥락 주입을 어디서 하느냐는 설계상 중요한 선택입니다. 처음에는 Hook(PreToolUse, UserPromptSubmit 등)으로 자동 주입하려 했으나, 실용적인 이유로 SKILL.md를 선택했습니다.

방식	장점	단점
Hook	완전 자동, 에이전트 의식 불필요	10초 타임아웃 제한, RAG(GPU 점유 + 임베딩)에 부적합
SKILL.md	타임아웃 없음, 유연한 조건 분기 가능	에이전트가 절차를 따라야 함 (하지만 스킬 자체가 절차 정의서)

Hook은 빠르고 결정적인 검증(네이밍 규칙 체크, 금지 명령어 차단)에 적합합니다. 반면 RAG 검색은 GPU를 acquire하고, 임베딩 모델을 호출하고, 벡터 DB를 쿼리하는 과정이 필요해서 10초 안에 끝나지 않을 수 있습니다. SKILL.md에 "Phase 0: RAG 검색" 같은 단계를 명시하면, 에이전트가 스킬 실행의 자연스러운 일부로 맥락을 로딩합니다.

실제 적용 — CLAUDE.md에 정책을 심다

위의 모든 설계를 CLAUDE.md 한 곳에 정리했습니다. 에이전트가 세션을 시작하면 자동으로 이 정책을 인식합니다.

추가한 섹션은 4개입니다:

1. 맥락 소스 우선순위 — 5단계 테이블로 충돌 해결 규칙 명시
2. 스킬별 맥락 로딩 매트릭스 — 11개 스킬 각각이 어떤 맥락을 필요로 하는지
3. 맥락 적재량 가이드라인 — 소스별 상한선
4. 컨텍스트 관리 — 세션 운영 원칙 (한 번에 하나의 작업, 대파일 직접 붙여넣기 금지 등)

핵심은 이 정책이 CLAUDE.md 안에 있다는 것입니다. CLAUDE.md는 1순위 맥락이므로, 이 정책 자체가 다른 모든 맥락보다 우선적으로 적용됩니다. 맥락 관리 정책이 맥락 우선순위의 최상위에 위치하는 자기 참조적 구조입니다.

Context Engineering은 Harness Engineering의 핵심이다

이전 글에서 Harness Engineering의 구조를 Data Plane(흐름)과 Control Plane(통제)으로 나눠 설명한 적이 있습니다. Context Engineering은 Data Plane의 첫 번째 단계 — 입력 준비에 해당합니다.

AI의 출력 품질을 결정하는 공식이 있습니다:

AI 출력 품질 = Intent 정확도 × Context 정합성

사용자의 의도(Intent)를 정확히 파악하는 것도 중요하지만, 그 의도를 실현할 맥락(Context)이 정합하지 않으면 결과는 엉뚱해집니다. "로그인 기능 만들어줘"라는 의도가 명확해도, React 프로젝트인지 Vue 프로젝트인지, 어떤 인증 라이브러리를 쓰는지, 기존 코드 스타일이 어떤지 — 이런 맥락이 없으면 쓸 수 없는 코드가 나옵니다.

Karpathy의 비유를 확장하면:

• Prompt Engineering은 함수 호출 — "이 함수를 실행해줘"
• Context Engineering은 메모리 관리 — "이 데이터를 RAM에 올려둬"
• Harness Engineering은 운영체제 설계 — "전체 시스템이 안정적으로 돌아가게 해"

프롬프트만 잘 써서는 안 됩니다. 프롬프트가 실행될 환경을 설계해야 합니다. Context Engineering이 바로 그 환경의 기초입니다.

다음 단계 — self-learning 자동 참조와 RAG 확대

우선순위 체계를 정의한 것은 첫걸음입니다. 다음에 해야 할 일은:

1. self-learning 자동 참조 — 각 스킬이 실행 전에 자기 도메인의 실패 복구 패치를 자동으로 읽도록 SKILL.md에 표준 섹션 추가
2. RAG 활용 확대 — 현재 3개 스킬에서만 쓰는 RAG를 6개 스킬로 확대, 공통 래퍼 스크립트 추출
3. Contextual Retrieval 품질 개선 — RAG 검색의 정확도를 높이기 위한 임베딩 파라미터 조정

이 시리즈의 다음 글에서 이어서 다루겠습니다.

---

참고 자료

• Anthropic, Effective Harnesses for Long-Running Agents
• Martin Fowler, Harness Engineering
• Can Bölük, The Harness Problem — Harness 변경만으로 15개 모델 성능 향상 실증

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.