컨텍스트 엔지니어링 – AI가 읽는 양을 설계하는 방법

컨텍스트 엔지니어링은 AI 모델이 추론할 때 함께 들어가는 토큰 묶음을 고르고 관리하는 방법을 가리킵니다. 프롬프트 문장을 다듬는 일에서 범위가 넓어져서, 도구 설명이나 불러온 파일, 쌓인 대화 기록처럼 프롬프트 밖에서 들어오는 정보까지 대상으로 삼아요.

글의 앞쪽은 Anthropic 공식 글과 Claude Code 문서에 적힌 내용을 정리한 것이고, 뒤쪽은 앱인토스 미니앱을 만드는 제 프로젝트의 규칙 파일이 실제로 어떻게 생겼는지입니다.

컨텍스트 엔지니어링이란 무엇인가

Anthropic은 Effective context engineering for AI agents라는 글에서 컨텍스트를 LLM에서 결과를 뽑을 때 함께 들어가는 토큰의 집합으로 정의합니다. 컨텍스트 엔지니어링은 추론하는 동안 그 토큰 묶음을 알맞게 고르고 유지하는 전략들을 말하고, 같은 글은 이것을 프롬프트 엔지니어링이 자연스럽게 발전한 단계로 봅니다.

범위가 넓어진 배경도 글에 적혀 있습니다. 에이전트는 추론을 여러 차례 이어 가며 오래 일하는데, 루프를 돌수록 다음 차례에 쓸 만한 데이터가 계속 생겨서 그것을 매번 추려야 한다는 거예요.

컨텍스트 창을 한정된 자원으로 보는 이유

Claude Code 문서는 컨텍스트 창에 대화 기록, 파일 내용, 명령 출력, CLAUDE.md, 자동 메모리, 불러온 스킬, 시스템 지시문이 담긴다고 설명합니다. 작업을 이어 가면 이 창이 차오릅니다.

Anthropic 글이 드는 근거는 컨텍스트 부패(context rot)라는 현상이에요. 건초 더미에서 바늘을 찾는 방식의 벤치마크 연구에서, 컨텍스트 창의 토큰이 늘어날수록 모델이 그 안의 정보를 정확히 떠올리는 능력이 떨어진다는 점이 드러났다고 합니다. 정도는 모델마다 다르지만 모든 모델에서 나타나는 특성이라고 적혀 있어요.

구조에서 오는 설명도 붙어 있습니다. 트랜스포머는 모든 토큰이 다른 모든 토큰을 참조할 수 있어서 토큰이 n개면 관계가 n²개 생기고, 컨텍스트가 길어질수록 이 관계를 붙잡는 능력이 얇게 퍼진다고 해요. 다만 글은 이것을 어느 지점에서 끊기는 절벽이 아니라 서서히 낮아지는 기울기로 표현합니다. 긴 컨텍스트에서도 모델은 여전히 유능하다고 적혀 있어요.

여기서 나오는 컨텍스트 엔지니어링의 원칙이 있습니다. 원하는 결과가 나올 가능성을 가장 높이는, 신호가 강한 토큰의 가장 작은 묶음을 찾으라고 글은 말합니다. 원문 표현은 “the smallest possible set of high-signal tokens”(Anthropic)예요. 시스템 프롬프트를 다루는 대목에는 최소한이라는 말이 꼭 짧다는 뜻은 아니라는 단서도 달려 있습니다.

공식 글에 나온 기법 네 가지

컨텍스트 엔지니어링 글에 나오는 방법을 제 나름대로 네 가지로 묶었습니다. 첫 번째는 정보를 미리 다 넣어 두지 않고 그때그때 가져오는 방법이고, 나머지 셋은 글이 오래 걸리는 작업에서 컨텍스트가 어지러워지는 문제에 대응하는 방법으로 묶어 소개하는 것들이에요. 오른쪽 칸은 Claude Code가 어떻게 하는지 공식 글과 문서에 적힌 내용이에요.

필요할 때 가져오는 방식에는 대가도 적혀 있습니다. 실행 중에 탐색하는 것은 미리 계산해 둔 데이터를 꺼내는 것보다 느립니다. Claude Code는 둘을 섞어서, CLAUDE.md는 처음부터 컨텍스트에 넣고 파일은 그때그때 찾아 읽는다고 글은 설명합니다.

컨텍스트 창이 차면 Claude Code가 하는 일

Claude Code 문서에 따르면 한도에 가까워졌을 때 오래된 도구 출력을 먼저 비우고, 필요하면 대화를 요약합니다. 사용자의 요청과 핵심 코드 조각은 보존되지만 대화 초반에 준 세부 지시는 사라질 수 있다고 적혀 있어요.

문서는 계속 지켜야 할 규칙을 대화 기록에 기대지 말고 CLAUDE.md에 두라고 권합니다. 프로젝트 루트의 CLAUDE.md는 /compact로 압축한 뒤에 디스크에서 다시 읽혀 세션에 들어갑니다.

지금 무엇이 자리를 차지하고 있는지는 /context 명령으로 볼 수 있다고 문서는 안내합니다.

CLAUDE.md에 넣을 것과 뺄 것

CLAUDE.md는 세션이 시작될 때마다 읽히는 파일입니다. 문서는 이 파일이 강제되는 설정이 아니라 컨텍스트로 취급된다고 밝히고, 지시가 구체적이고 간결할수록 더 일관되게 따른다고 설명해요.

분량은 파일 하나에 200줄 미만을 목표로 하라고 권합니다. 이보다 길면 컨텍스트를 더 쓰고 지시를 따르는 정도가 낮아진다고 적혀 있어요. @경로로 다른 파일을 불러오는 방식은 정리에는 도움이 되지만, 불러온 파일도 시작할 때 함께 읽히기 때문에 컨텍스트 비용은 줄지 않는다는 설명도 있습니다.

내 프로젝트의 규칙 파일은 입구 역할을 한다

여기부터는 컨텍스트 엔지니어링을 제 프로젝트에 옮긴 이야기입니다. 저장소 루트의 CLAUDE.md는 15줄이에요.

# Agent entry point

Project rules live in `AGENTS.md`; follow them.

@AGENTS.md

## Apps in Toss work

- Skill: `.claude/skills/apps-in-toss-factory/SKILL.md` (mirrors `appintoss/harness/SKILL.md`).
- Always start with `node scripts/ait-harness.mjs context <N>` and read only its `readNext` files.
- Console MCP server name: `apps-in-toss-console` (project scope, `.mcp.json`, OAuth). Check with
  `node scripts/ait-harness.mjs mcp`; if its tools are not callable in this session, finish the local
  work and report the exact console-only action instead of guessing.
- Do not load archived/local SDK guide snapshots under `md/`. Use
  `appintoss/harness/OFFICIAL_SOURCES.md` only when live policy or API verification is needed.

다섯째 줄의 @AGENTS.md가 규칙 파일을 불러옵니다. 앞에서 본 문서대로라면 불러온 파일도 시작할 때 같이 읽히니까, 세션이 시작될 때는 이 15줄에 76줄짜리 AGENTS.md가 더해져서 들어옵니다. 문서가 CLAUDE.md 파일 하나에 권하는 분량이 200줄 아래인데, 두 파일은 합쳐도 그보다 짧습니다.

AGENTS.md는 규칙 몇 줄 뒤에 문서 위치를 적은 표가 이어지는데, 표 바로 위에 이 두 줄이 있습니다.

This file is a table of contents, not the knowledge itself. Open a document only when the task
needs it; none of these are session-start reading.

표의 왼쪽 칸은 “무엇이 필요한가”, 오른쪽 칸은 “어느 문서로 가는가”입니다. 제작 절차, 공식 정책 주소, 화면 설계 기준, 현재 작업 상태가 각각 다른 문서에 있어요. 지난 작업 기록 문서 옆에는 통째로 읽지 말라는 말이, 외부 매뉴얼을 모아 둔 폴더 옆에는 검색만 하라는 말이 붙어 있습니다.

읽지 않을 것을 규칙으로 적어 둔다

AGENTS.md의 규칙 가운데에는 읽지 말 것을 정한 줄이 있습니다. 다른 앱 폴더, node_modules, dist, 생성된 번들, .ait 파일은 작업이 명시적으로 요구하지 않으면 훑지 않는다는 내용이에요. 토큰 규칙도 한 줄 있는데, 앱 하나에 세션 하나를 쓰고, 메인 세션에서 PNG를 읽지 않고, 긴 문서는 grep -n으로 위치를 찾은 뒤 sed -n으로 구간만 읽는다고 적혀 있습니다.

Codex 터미널용으로 따로 둔 정책 문서에는 작업 범위를 정하는 대목이 있어요.

- 한 작업은 하나의 프로젝트 번호와 하나의 사용자 결과를 기준으로 시작한다.
- `context`가 알려 준 `readNext` 파일을 먼저 읽고, 부족한 사실이 생길 때만 좁은 파일 검색을 한다.
- 전체 포트폴리오 상태는 사용자가 포트폴리오 전체 점검을 요청했을 때만 확인한다.
- 콘솔 결과·광고 ID·빌드 결과는 한 번 확인한 뒤 작업 기록으로 재사용한다. 새 릴리스나 사용자 지시가 없는 한 반복 확인하지 않는다.
- 단순 메타데이터 수정에는 앱 전체 소스, `dist`, 과거 로드맵을 읽지 않는다.

여기 나오는 context 명령은 앱 번호를 받아 그 앱의 상태와 읽을 파일 목록을 돌려주는 스크립트이고, 코드는 AI 하네스 글에서 다뤘습니다. 스킬 문서에는 이 명령과 짝을 이루는 규칙이 있어요. 출력에 앱 이름, 카테고리, 광고와 알림 설정 같은 값이 이미 들어 있으니 그 값을 보려고 설정 파일을 다시 열지 말고, 그 파일을 고치려 할 때나 출력에 없는 값이 필요할 때 열라고 적혀 있습니다.

컨텍스트 엔지니어링을 처음 적용한다면

규칙 파일부터 손본다면 저는 이 순서를 권합니다. 앞의 두 단계는 Claude Code 문서의 안내이고 뒤의 두 단계는 제 프로젝트에서 쓰는 방식이에요.

읽을 범위를 정해 주는 context 명령과, 코드 규칙을 스크립트로 검사하는 쪽은 AI 하네스 글에 있습니다.

글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.

이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.