본문으로 건너뛰기

2부: 컨텍스트 엔지니어링

컨텍스트 엔지니어링은 빠른 AI 출력과 유용한 AI 출력을 구분하는 기술입니다. 1부에서 다룬 규칙 파일은 그 한 요소입니다. 이 파트는 더 큰 규율에 관한 것입니다. 에이전트가 무엇을 보는지, 그리고 언제 보는지를 결정하는 것입니다.

사고의 전환이 필요합니다. "모델이 좋은 코드를 내놓도록 어떻게 표현할까?"에서 "새로운 팀원이 잘 기여하려면 무엇을 알아야 하며, 어떻게 효율적으로 전달할까?"로 관점을 바꾸어야 합니다.

두 가지 버킷: 정적과 동적​

모든 컨텍스트는 두 버킷 중 하나에 속하며, 어떤 버킷을 선택할지는 실질적인 비용이 따르는 실제 엔지니어링 결정입니다.

정적 컨텍스트는 매 요청마다 항상 로드됩니다.

  • 시스템 지침
  • 규칙 파일 (CLAUDE.md 등)
  • 전역 메모리와 페르소나

신뢰할 수 있습니다 — 에이전트가 절대 잊지 않습니다 — 하지만 비용이 높습니다. 현재 작업에 필요하든 필요하지 않든 모든 호출마다 모든 토큰에 대해 비용을 지불하기 때문입니다.

동적 컨텍스트는 필요할 때만 로드됩니다.

  • 현재 작업에 의해 트리거되는 스킬
  • 실행 중 가져오는 도구 결과
  • 검색 인덱스에서 조회된 문서
  • 최근 대화 기록의 일부

효율적입니다 — 정보가 실제로 관련될 때만 비용을 지불합니다.

양 극단의 함정: 정적 컨텍스트가 너무 많으면 돈을 낭비하고 신호를 희석시킵니다 (중요한 규칙이 소음에 묻힙니다). 너무 적으면 에이전트가 필요한 것을 잊어버립니다. 정적/동적 경계선을 다른 아키텍처 결정과 마찬가지로 다루세요 — 우연이 아닌, 검토되고 버전 관리된 결정으로.

간단한 비용 직관​

규칙 파일이 2,000 토큰이고 한 세션에서 50번의 요청을 한다고 가정해 봅시다. 규칙 파일만으로 100,000 토큰이 소비되며, 50번에 걸쳐 지불하게 됩니다. 그 파일의 절반이 특정 작업 하나에만 관련된 참조 자료라면, 나머지 49번의 요청에서 불필요한 비용을 지불하는 것입니다. 그 절반을 온디맨드로 로드되는 스킬로 옮기면 나머지 49번에 대한 비용은 사라집니다.

이것이 "정적 컨텍스트를 밀도 있고 신호가 강하게 유지하라"는 것이 스타일 선호가 아닌 이유입니다 — 이것은 비용 항목입니다.

스킬: 동적 컨텍스트를 위한 패턴​

동적 버킷을 관리하는 가장 효과적인 방법은 스킬입니다. 스킬이란 작업이 일치할 때만 에이전트가 로드하는 자기 완결적인 절차적 지식 패키지입니다.

스킬은 점진적 공개를 통해 작동합니다 — 지연 로드되는 세 개의 레이어:

  1. 시작 시, 에이전트는 경량 메타데이터(이름과 한 줄 설명)만 봅니다.
  2. 작업이 일치하면 전체 지침을 로드합니다.
  3. 깊이가 필요할 때만 무거운 참조 자료를 가져옵니다.

결과적으로: 경량 범용 에이전트가 수십 가지 전문 역량을 보유하면서도 현재 활발히 사용 중인 하나의 토큰 비용만 지불할 수 있습니다.

최소한의 스킬은 다음과 같습니다.

---
name: stripe-refunds
description: How to issue and reconcile refunds through our billing layer. Use when a task involves refunds, chargebacks, or payment reversals.
---

# Issuing a refund

1. Look up the charge via `billing.get_charge(charge_id)`.
2. Refunds over $500 require an `approved_by` field — never auto-approve.
3. Call `billing.refund(charge_id, amount, approved_by)`.
4. Write a `RefundRecord` to the ledger in the same transaction.
5. Emit a `refund.issued` event.

See `reference/refund-edge-cases.md` for partial refunds and currency conversion.

에이전트는 작업이 실제로 환불을 언급할 때만 이것을 읽습니다. 나머지 시간에는 한 줄짜리 설명 외에 아무 비용도 들지 않습니다.

관리해야 할 여섯 가지 컨텍스트 유형​

무엇을 제공할지 결정할 때, 여섯 가지 카테고리를 고려하세요. 대부분의 워크플로는 중간의 네 가지에 충분히 투자하지 않습니다.

  • 지침 — 에이전트의 역할, 목표, 경계 (규칙 파일).
  • 지식 — 문서, 아키텍처 다이어그램, 도메인 데이터.
  • 메모리 — 방금 일어난 일 (세션), 그리고 프로젝트가 무엇인지 (장기).
  • 예시 — 인터넷에서 가져온 일반적인 것이 아닌, 여러분 자신의 코드베이스에서 가져온 참조 패턴.
  • 도구 — 에이전트가 호출할 수 있는 API와 스크립트의 정확한 정의.
  • 가드레일 — 하드 제약과 안전 규칙.

"예시" 항목은 특별히 언급할 가치가 있습니다. 실제 코드에서 가져온 예시 하나가 세 단락짜리 설명보다 에이전트에게 여러분의 스타일을 더 빠르게 가르쳐 줍니다.

전체 저장소를 붙여넣지 마세요​

흔한 실수는 "모든 것을 갖추기 위해" 100,000 토큰짜리 전체 저장소를 프롬프트에 넣는 것입니다. 이것은 비용도 많이 들고 역효과도 납니다 — 관련 신호가 묻혀버립니다. 대신 현재 작업과 관련된 몇 개의 파일만 조회하고, 필요하면 에이전트가 더 요청하게 하세요. 코드베이스 전체 인식은 도구의 역할입니다 (인덱싱, 조회). 매 프롬프트마다 여러분이 수동으로 할 일이 아닙니다.

직접 워크플로 설정하기​

  • 현재 정적 컨텍스트에 있는 모든 것을 나열합니다. 각 항목에 대해 묻습니다: 모든 작업에 이것이 필요한가?
  • 작업별 자료를 규칙 파일에서 꺼내 스킬로 이동합니다.
  • 반복적으로 발생하는 전문 작업(환불 흐름, 마이그레이션 패턴, 리포트 형식 등)을 위한 첫 번째 스킬을 작성합니다.
  • 규칙 파일이나 스킬에 코드베이스에서 가져온 실제 예시를 몇 가지 추가합니다.
  • 전체 파일을 붙여넣는 것을 중단합니다. 관련 내용이 표면에 드러나도록 조회를 활용하세요.