본문으로 건너뛰기

컨텍스트 엔지니어링 — 에이전트에게 주는 지시의 설계

프롬프트 엔지니어링이 컨텍스트 엔지니어링으로 확장된 과정과 AGENTS.md 표준화, 컨텍스트 예산과 오염 관리까지 정리했습니다. 에이전트에게 주는 파일과 지시를 설계하는 관점을 담은 글입니다.

· 6분 읽기

컨텍스트 엔지니어링 — 에이전트에게 주는 지시의 설계

1년 전만 해도 “프롬프트를 잘 쓰는 법”이 화제였다면, 지금 팀에서 실제로 가르치는 건 “컨텍스트를 잘 예산 쓰는 법”입니다. 코딩 에이전트가 PR을 열고, 이슈를 읽고, 파일을 고치는 단계까지 오면, 문장 하나를 다듬는 일보다 “이 에이전트의 작업 창에 무엇을 언제 넣고 무엇을 비워둘지”가 성패를 갈랐습니다. 이번 글에서는 이 관점의 변화와, 그중에서도 파일과 지시 설계에 집중해 정리해 봤습니다.

프롬프트 엔지니어링에서 컨텍스트 엔지니어링으로

용어의 전환점은 명확합니다. Anthropic은 2025년 9월 Effective context engineering for AI agents라는 엔지니어링 글에서 “컨텍스트는 희소 자원”이라고 규정하고, 시스템 프롬프트 튜닝 수준의 접근을 넘어 “토큰 예산 안에서 정보 가치를 극대화하는 작업”으로 컨텍스트 엔지니어링을 정의했습니다. 이 글 이후 업계 문서와 도구 문서에서 “context engineering”이 사실상 표준 용어로 자리 잡았다고 체감합니다.

프롬프트 엔지니어링과 컨텍스트 엔지니어링의 차이는 이렇게 요약할 수 있습니다.

  • 프롬프트 엔지니어링: 한 번의 호출에서 모델의 출력을 어떻게 이끌어낼지 문장을 다듬는 일
  • 컨텍스트 엔지니어링: 여러 단계로 이어지는 에이전트 루프에서, 각 단계의 컨텍스트 창에 무엇이 들어가는지를 설계하고 관리하는 일

에이전트는 호출이 한 번으로 끝나지 않습니다. 도구 결과가 다시 컨텍스트에 들어오고, 파일 내용이 들어오고, 이전 단계의 실패 기록이 들어옵니다. 그때마다 컨텍스트 창은 쌓이고, 모델은 처음 지시를 점점 흐리게 기억하게 됩니다. 그래서 “무엇을 넣을까”만큼 “무엇을 계속 남겨둘까”가 설계 대상이 됩니다. Anthropic은 같은 글에서 시스템 프롬프트를 “최소한의 수정 가능한 정보”로 유지하라고 권하고, 장기 기억과 단기 작업 맥락을 분리할 것을 권장했습니다.

AGENTS.md — 지시 파일의 표준화

이 관점이 코드 베이스에 착지한 형태가 지시 파일입니다. 그중 AGENTS.md는 “에이전트를 위한 README”라는 슬로건으로 제안된 오픈 포맷으로, 저장소 루트에 두면 코딩 에이전트가 작업 전에 읽는 표준 위치로 자리 잡았습니다. OpenAI Codex도 AGENTS.md로 프로젝트별 지시를 내리는 방식을 공식 문서로 안내하고 있습니다.

핵심은 위치의 표준화입니다. 예전에는 도구마다 지시 파일 이름과 위치가 달라서, 같은 내용을 여러 파일에 복붙하고 어느새 서로 어긋났습니다. AGENTS.md는 “이 파일을 여기 두면 에이전트가 읽는다”는 합의를 만들어, 지시의 단일 진실 공급원을 만들 수 있게 했습니다.

CLAUDE.md와의 관계

그럼 기존의 CLAUDE.md는 어떻게 되냐는 질문이 많습니다. Claude Code는 메모리 문서에서 CLAUDE.md를 “Claude의 행동을 유도하는 용도”의 파일로 안내합니다. 구조적으로는 AGENTS.md와 같은 역할이고, 실무에서는 이렇게 정리합니다.

저장소/
  AGENTS.md      # 도구 공통 지시 (표준 위치)
  CLAUDE.md      # Claude 전용 추가 지시 또는 AGENTS.md 참조

제가 쓰는 방식은 단순합니다. 본체는 AGENTS.md에 두고, CLAUDE.md에는 도구별 차이만 남기거나 “AGENTS.md를 따른다”는 한 줄을 둡니다. 반대 방향(내용을 CLAUDE.md에 두고 복제)은 어느 한쪽만 고치는 사고를 만들어서 지양합니다. 중요한 건 어느 파일이 진실인지가 아니라, 지시가 정확히 한 곳에서 관리되는지입니다.

컨텍스트 예산 — 무엇이 먼저 들어가는가

컨텍스트 창은 무한하지 않고, 들어간 순서와 종류가 품질을 결정합니다. 실무에서 컨텍스트를 층으로 나눠 보면 예산 배분이 명확해집니다.

  1. 시스템 프롬프트 / 지시 파일: 항상 존재. 수정 빈도가 낮고 신뢰도가 높은 규칙을 둡니다. 예산을 아껴야 합니다.
  2. 파일 컨텍스트: 에이전트가 읽은 코드. 가장 크게 불어나는 항목입니다. “전체 폴더 읽기”보다 “이 파일의 이 섹션”이 원칙.
  3. 검색 결과: 문서 검색·웹 검색으로 들어오는 외부 정보. 신뢰도가 낮으므로 출처와 갱신일을 함께 두는 게 안전합니다.
  4. 대화 기록: 가장 오염되기 쉬운 층입니다. 실패한 시도의 스택 트레이스가 그대로 남아 이후 판단을 흔듭니다.

우선순위는 “변하지 않는 규칙 > 구조적 사실 > 이번 작업의 목적 > 지나간 시도”입니다. 지나간 시도는 대부분 예산 낭비라서, 긴 작업에서는 주기적으로 정리하거나 요약으로 대체합니다. Anthropic의 에이전트 설계 글도 복잡한 프레임워크보다 필요한 최소한의 구조로 시작하라는 방향인데, 컨텍스트 예산도 같은 철학입니다.

컨텍스트 오염과 압축

예산 문제와 함께 오는 것이 오염입니다. 대표적인 패턴 세 가지를 봤습니다.

  • 실패의 잔상: 디버깅 중 오류 메시지가 컨텍스트에 남자, 이미 고쳐진 문제를 계속 의심하며 원점으로 돌아가는 경우
  • 지시의 상쇄: 오래된 대화 초반의 임시 지시(“일단 임시로 하드코딩해 봐”)가 나중 지시와 충돌하는 경우
  • 외부 텍스트의 주입: 도구 결과로 들어온 문서나 웹 페이지에 섞인 문장이 지시처럼 해석되는 경우. 이건 품질 문제가 아니라 보안 문제입니다.

대책의 축은 둘입니다. 첫째, 정리(compaction) — 주기적으로 지금까지의 작업을 “확정된 사실 + 남은 할 일”로 요약하고 원문을 버립니다. Claude Cookbook의 컨텍스트 엔지니어링 예제는 메모리·압축·도구 결과 정리를 어떻게 구성하는지 좋은 참고가 됐습니다. 둘째, 분리 — 오염 가능성이 있는 입력(외부 검색 결과 등)은 지시와 같은 층에 두지 않고, 결과 처리 전용 단계를 두는 겁니다.

압축을 설계할 때 주의할 점은 “무손실”을 가정하지 않는 겁니다. 요약이 빠뜨린 제약은 사라진 제약이나 마찬가지라서, 압축 후에는 규칙(AGENTS.md)이 다시 들어와야 합니다. 그래서 규칙은 요약 대상에서 제외하고 항상 재주입되는 구조가 안전합니다.

잘 되는 AGENTS.md 구조

1년간 사이드 프로젝트와 이 블로그 저장소에 AGENTS.md를 운영하며 잘 통한 구조입니다. 핵심은 “에이전트가 작업 중 다시 찾게 되는 순서”로 쓰는 겁니다.

# 이 저장소 에이전트 지시

## 저장소 개요
- Astro 5 + MDX 한국어 기술 블로그. 콘텐츠는 content/posts/ 아래.

## 불변 규칙 (항상 지켜야 함)
- 새 글은 frontmatter에 title/date/description/tags를 모두 명시한다.
- date는 배정표 날짜와 정확히 일치시킨다.

## 명령어
- 글 확인: pnpm check
- 로컬 미리보기: pnpm dev

## 작업별 지침
### 새 글을 쓸 때
1. 기존 글 2~3개를 먼저 읽고 문체를 맞춘다.
2. 레퍼런스 링크는 실존 확인 후에만 추가한다.

## 하지 말 것
- 빌드/린트를 임의로 비활성화하지 않는다.
- 검증되지 않은 수치를 본문에 넣지 않는다.

이 구조가 잘 통는 이유를 분석해 보면 셋입니다. 첫째, 불변 규칙이 위에 있어 긴 작업 후반에도 희석되지 않습니다. 둘째, 명령어를 알려주는 순간 검색 비용이 사라져 에이전트가 추측으로 파일을 뒤지는 낭비를 줄입니다. 셋째, 하지 말 것이 실제 사고 기반일 때 잘 지켜집니다. “깔끔하게 써라” 같은 추상 지시는 무시되지만 “date는 배정표와 일치”는 검증 가능해서 지켜집니다.

반대로 실패한 패턴도 명확합니다. 수백 줄짜리 치트시트형 AGENTS.md는 처음 몇 분만 효과가 있고, 이후 스크롤 손실 때문에 아래쪽 규칙은 사실상 없는 규칙이 됩니다. 컨텍스트 계약 관점의 더 넓은 실무는 계약과 하네스 글에서 다뤘으니, 이 글은 파일 자체의 설계까지만 다룹니다.

정리

컨텍스트 엔지니어링은 유행어가 아니라, 에이전트가 등장하면서 프롬프트 설계가 자연스럽게 확장된 영역입니다. 기억할 원칙은 세 가지였습니다.

  • 컨텍스트는 예산이다. 무엇을 넣을지보다 무엇을 남기지 않을지를 함께 설계한다.
  • 지시는 표준 위치(AGENTS.md)에 단일 진실 공급원으로 둔다. 도구별 파일은 참조만.
  • 규칙은 검증 가능하게, 외부 입력은 지시와 분리해서 오염을 막는다.

에이전트가 똑똑해질수록 “말을 잘하는 것”의 비중은 줄고 “읽힐 환경을 잘 만드는 것”의 비중은 늘어납니다. 다음 글 작업 전에 AGENTS.md부터 다시 읽어보는 것도 괜찮은 점검이 될 겁니다.

레퍼런스

Related