AI 코딩 에이전트가 실패하는 가장 흔한 이유는 코드를 작성할 수 없어서가 아니라, 시작할 때 당신의 코드베이스(codebase)를 알지 못하기 때문입니다. 에이전트는 이미 존재하는 유틸리티를 재발명하거나, 6개월 전에 폐기한 에러 패턴을 선택하고, 팀에서 금지한 라우트 핸들러(route handler)에서 데이터베이스를 쿼리합니다. 모델은 능력이 있습니다. 컨텍스트(context)가 부족한 것입니다. **컨텍스트 엔지니어링 (Context engineering)**은 모델이 코드를 한 줄 쓰기 전에 무엇을 알게 할지 결정함으로써 이 문제를 해결하는 규율입니다.

제가 제 SaaS에 에이전트에게 실제 업무를 처음 맡겼을 때, 저는 전체 리포지토리(repo)를 창에 붙여넣었고 더 많은 컨텍스트가 도움이 될 것이라고 생각했습니다. 하지만 에이전트는 이미 있던 날짜 헬퍼(date helper)를 재발명했고, 몇 달 전에 삭제한 검증 패턴을 선택했으며, 라우트 핸들러에 데이터베이스 호출을 직접 넣었습니다. 그래서 저는 거의 모든 것을 삭제하고 대신 30줄짜리 AGENTS.md 파일을 작성했습니다. 여기에는 스택(stack), 세 가지 아키텍처 규칙, 그리고 짧은 금지 사항 목록이 포함되었습니다. 다음 작업은 단 한 번의 시도 만에 제 컨벤션(conventions)에 맞춰 수행되었습니다. 해결책은 더 많은 컨텍스트가 아니라, 올바른 컨텍스트였습니다.

이것은 프롬프트 엔지니어링 (prompt engineering)과는 다른 작업이며, 더 지속 가능한 작업입니다. 훌륭한 프롬프트는 단 하나의 메시지에 도움이 됩니다. 잘 설계된 컨텍스트는 모든 메시지, 모든 세션, 그리고 리포지토리에 접근하는 모든 에이전트에게 도움이 됩니다. 만약 당신의 AI 도구가 일관되지 않은 결과를 생성한다면, 그 해결의 지점은 문구(phrasing)가 아니라 보통 여기에 있습니다.

만약 당신이 바이브 코딩 (vibe coding)을 해왔고, 코드가 맞게 생긴 것 같지만 당신의 컨벤션을 무시하는 결과를 얻고 있다면, 이 가이드는 당신이 놓치고 있는 레이어와 이를 구축하는 방법을 설명합니다.

컨텍스트 엔지니어링 (Context Engineering)이란 무엇인가?

**컨텍스트 엔지니어링 (Context engineering)**은 AI 모델이 출력을 생성하기 전에 보는 모든 것, 즉 시스템 지침 (system instructions), 프로젝트 규칙, 관련 파일, 검색된 데이터 (retrieved data), 대화 기록 (conversation history), 그리고 모델이 호출한 모든 도구의 결과물을 조립하는 실무를 의미합니다. 모델의 답변 품질은 조립된 컨텍스트의 품질에 달려 있습니다. 컨텍스트를 잘 설계하면 중간 수준의 모델도 당신의 코드베이스에 대한 전문가처럼 행동하지만, 설계를 잘못하면 시장에서 가장 뛰어난 모델이라 할지라도 추측에 의존하게 됩니다.

이 용어에는 명확한 기원이 있습니다. 2025년 6월 25일, Andrej Karpathy는 이를 _"다음 단계를 위해 컨텍스트 창 (context window)을 딱 적절한 정보로 채우는 섬세한 예술이자 과학"_이라고 설명했습니다. 이틀 전인 6월 23일, Shopify의 CEO Tobi Lütke는 이를 _"LLM이 해당 작업을 타당하게 해결할 수 있도록 모든 컨텍스트를 제공하는 기술"_이라고 정의했습니다 (@tobi on X, 2025년 6월 23일). Simon Willison은 이 두 정의를 수집하며, 이 문구가 "프롬프트 엔지니어링 (prompt engineering)"이 수행했던 것보다 실제 프로덕션 환경에서의 LLM 작업을 더 잘 포착한다고 주장했습니다 (Willison, 2025년 6월 27일).

컨텍스트 엔지니어링은 다음 단계를 위해 컨텍스트 창 (context window)을 딱 적절한 정보로 채우는 섬세한 예술이자 과학이다. — Andrej Karpathy, 2025년 6월 25일

Karpathy는 여기서 두 번째 이유로도 유용한 출처입니다. 그는 2025년 2월 2일에도 "바이브 코딩 (vibe coding)"_ (Willison, 2025년 3월 19일)이라는 용어를 만들어냈으며, 이 용어는 이후 Collins Dictionary의 2025년 올해의 단어로 선정되었습니다 (Collins Dictionary, 2025). AI로 자유롭게 구축하는 방식을 우리에게 알려준 바로 그 사람이, 그 구축물을 견고하게 유지하게 만드는 학문적 영역의 이름도 명명한 것입니다. 바이브 코딩이 가속 페달을 의미한다면, 컨텍스트 엔지니어링은 스티어링 (steering, 조향)입니다.

Karpathy의 정의에서 핵심 단어는 _채우기 (filling)_입니다. 컨텍스트 엔지니어링 (Context engineering)은 더 영리한 지시문을 작성하는 것에 관한 것이 아닙니다. 그것은 유한한 윈도우 (finite window) 안에 무엇을 넣을지 결정하는 것에 관한 것입니다. 즉, 어떤 규칙, 어떤 파일, 어떤 검색된 사실 (retrieved facts), 어떤 이전 대화 (prior turns)를 넣을지, 그리고 그만큼 중요하게, 무엇을 제외할지를 결정하는 것입니다.

컨텍스트 엔지니어링 (Context Engineering) vs 프롬프트 엔지니어링 (Prompt Engineering)

프롬프트 엔지니어링 (Prompt engineering)과 컨텍스트 엔지니어링 (Context engineering)은 끊임없이 혼동되곤 하지만, 그 차이를 구분하는 것이 핵심입니다. 프롬프트 엔지니어링은 당신이 던지는 _질문 (question)_을 최적화합니다. 컨텍스트 엔지니어링은 모델이 그 질문을 읽을 때 이미 로드되어 있는 모든 것을 최적화합니다. 하나는 문장이고, 다른 하나는 시스템입니다.

구체적인 예를 들면 다음과 같습니다: 프롬프트 엔지니어링은 "이것을 고쳐줘" 대신 "이 함수를 리팩터링 (refactor)하고 단계별로 당신의 논리를 설명해줘"라고 쓰기로 선택하는 것입니다. 컨텍스트 엔지니어링은 모델이 어떤 프롬프트를 읽기 전에, 당신의 스택이 엄격한 TypeScript를 사용하는 Next.js라는 점, 비즈니스 로직은 서비스 레이어 (service layer)에 속해야 한다는 점, 그리고 모든 데이터베이스 쿼리는 테넌트 (tenant)별로 필터링되어야 한다는 점을 이미 알고 있도록 만드는 것입니다. 어떤 방식이든 프롬프트의 길이는 동일합니다. 하지만 결과물은 다릅니다.

	프롬프트 엔지니어링 (Prompt engineering)	컨텍스트 엔지니어링 (Context engineering)
범위 (Scope)	단일 메시지	전체 컨텍스트 윈도우 (context window)
...

어느 하나가 다른 하나를 대체하지는 않습니다. 빈 컨텍스트에 대한 날카로운 프롬프트는 여전히 당신의 아키텍처 (architecture)를 위반하는 코드를 생성합니다. 게으른 프롬프트와 함께 풍부한 컨텍스트가 있더라도 여전히 명확한 요청이 필요합니다. 하지만 특히 AI 보조 개발 (AI-assisted development)에 있어서는 컨텍스트가 더 높은 레버리지 (leverage, 지렛대)를 가진 레이어입니다. 왜냐하면 컨텍스트가 담고 있는 관습 (conventions), 아키텍처, 그리고 제약 사항 (constraints)은 해당 리포지토리 (repo)를 대상으로 당신이 작성할 모든 프롬프트에 적용되기 때문입니다.

이것이 중요한 이유: 컨텍스트 부패 (Context Rot)와 패턴 드리프트 (Pattern Drift)

Anthropic의 2025년 9월 가이드인 "AI 에이전트를 위한 효과적인 컨텍스트 엔지니어링 (Effective context engineering for AI agents)"은 핵심적인 실패 모드로 **컨텍스트 부패 (context rot)**를 지목합니다. 컨텍스트 윈도우 (context window)가 채워질수록 모델의 회상 (recall) 능력이 저하됩니다. 즉, 이전에 언급되었거나 무관한 토큰 (tokens) 아래에 묻혀버린 사실들을 놓치기 시작하는 것입니다 (Anthropic, 2025년 9월). 더 많은 컨텍스트가 더 좋은 컨텍스트를 의미하지는 않습니다. 전체 리포지토리 (repo)를 쑤셔 넣은 윈도우는 작업에 필요한 내용만 담은 간결한 윈도우보다 더 나쁜 성능을 보입니다. 이것이 이 분야의 직관에 반하는 핵심이며, "그냥 전부 다 붙여넣으면 된다"는 생각이 잘못된 본능인 이유입니다.

핵심적인 직관에 반하는 사실

컨텍스트 윈도우에 더 많은 것을 추가하는 것이 모델을 더 똑똑하게 만드는 것이 아니라 더 멍청하게 만들 수 있습니다. 컨텍스트 부패 (context rot)란 작업에 필요하지 않은 토큰들로 윈도우가 채워짐에 따라 회상 (recall) 능력이 저하됨을 의미합니다. 목표는 '가장 많은' 정보가 아니라 '올바른' 정보입니다.

이 문제를 잘못 해결했을 때 발생하는 비용은 코드 품질에서 나타납니다. Veracode의 2025년 GenAI 코드 보안 보고서 (GenAI Code Security Report)에 따르면, AI가 생성한 코드의 45%가 보안 테스트를 통과하지 못했으며, 모델 전반에 걸쳐 알려진 취약점 클래스 (vulnerability classes)를 일정한 속도로 유발하고 있는 것으로 나타났습니다 (Veracode, 2025). 그중 상당 부분은 컨텍스트 문제입니다. 귀하의 검증 헬퍼 (validation helpers), 인증 경계 (auth boundaries), 또는 에러 컨벤션 (error conventions)을 알지 못하면 모델은 이를 재발명하게 되며, 그 재발명된 결과물은 종종 이미 배포된 것보다 취약합니다. 이를 코드베이스 전체로 확장하면 패턴 드리프트 (pattern drift)가 발생합니다. 즉, 모델이 앞선 네 가지 방식을 보지 못했기 때문에 동일한 작업이 다섯 가지의 일관성 없는 방식으로 수행되는 현상입니다.

martinfowler.com에 게시된 Birgitta Böckeler의 "coding agent를 위한 컨텍스트 엔지니어링 (context engineering for coding agents)"은 이 문제를 진지하게 다루기 위한 실무자용 참조 가이드입니다. 그녀는 컨텍스트를 우연히 쌓이는 것이 아니라, 의도적으로 큐레이션(curate)하여 제공하는 것으로 정의합니다 (Böckeler, martinfowler.com). 신뢰할 수 있는 AI 생성 코드를 배포하는 팀은 에이전트가 무엇을 알게 할지를 의도적으로 결정하는 팀들입니다.

컨텍스트의 네 가지 소스

작동하는 컨텍스트 레이어(context layer)는 네 가지의 서로 다른 소스에서 정보를 가져옵니다. 각 소스는 서로 다른 질문에 답하며, 훌륭한 설정은 이 네 가지를 모두 함께 사용합니다.

1. 상시 활성화된 시스템 프롬프트 (system prompt) / AGENTS.md

이것은 모든 작업 시 로드되는 레이어로, 프로젝트의 기본 규칙입니다. 코딩 도구에서는 보통 에이전트가 작업을 수행하기 전에 읽는 AGENTS.md 파일(또는 CLAUDE.md, .cursorrules)에 존재합니다. 스택(stack), 아키텍처(architecture), 컨벤션(conventions), 그리고 에이전트가 절대 하지 말아야 할 사항들이 여기에 포함됩니다. 이는 여러분이 소유한 컨텍스트 중 가장 작으면서도 가장 많이 읽히는 부분이며, 그렇기 때문에 2,000줄짜리 데이터 덤프(data dump)가 아닌 간결하고 사람이 직접 작성한 형태여야 합니다.

2. 범위가 지정된 규칙(Scoped rules) 및 적시 검색 (just-in-time retrieval)

모든 규칙이 상시 활성화된 레이어에 속할 필요는 없습니다. 에이전트가 코드베이스의 특정 부분(데이터베이스 레이어, 결제 흐름, 이메일 템플릿 등)을 다룰 때만 중요한 세부 사항은 해당 영역이 작동할 때만 로드되어야 합니다. 이것이 바로 적시 검색(just-in-time retrieval)입니다. 즉, 모든 규칙을 항상 들고 다니는 대신 적절한 순간에 적절한 규칙을 가져오는 것입니다. 이는 컨텍스트 윈도우(context window)를 가볍게 유지하고 컨텍스트 부패(context rot)에 직접적으로 대응합니다.

3. 살아있는 문서 (Living documentation)

코드와 동떨어진 문서는 문서가 없는 것보다 더 나쁩니다. 왜냐하면 에이전트는 그 문서를 신뢰하기 때문입니다. 세 번째 소스는 코드베이스와 동기화되어 유지되는 문서입니다. 커밋 시점에 재생성되거나 확인되어, 에이전트가 문서를 읽을 때 3번의 스프린트(sprint) 전의 상태가 아니라 시스템이 실제로 수행하는 동작을 설명하도록 해야 합니다. 오래된(stale) 컨텍스트는 확신에 찬 오답(confidently wrong)을 만듭니다.

4. 도구 결과 및 메모리 (Tool results and memory)

마지막 소스는 에이전트가 런타임(runtime)에 가져오는 것입니다: 데이터베이스 쿼리(database query)의 출력값, 읽어온 파일의 내용, 검색 결과, 또는 이전 턴(turn)에서 메모리에 작성한 노트 등이 이에 해당합니다. 이것이 바로 동적 컨텍스트(dynamic context)입니다. 사용자가 프롬프트(prompt)에 현재 스키마(schema)를 직접 붙여넣는 대신, 에이전트가 도구(tool)를 호출하여 최신 상태로 읽어옵니다. 즉, 필요할 때마다 가져오기(fetch) 때문에 컨텍스트가 절대 오래되지(stale) 않습니다.

SaaS 코드베이스를 위한 컨텍스트 레이어 (A Context Layer for a SaaS Codebase)

추상적인 원칙은 고개를 끄덕이기는 쉽지만 적용하기는 어렵습니다. 그래서 구체적인 사례를 하나 소개하겠습니다. 아래는 TaskFlow라는 가상의 멀티 테넌트(multi-tenant) SaaS를 위한, 그대로 복사해서 붙여넣을 수 있는 완전한 AGENTS.md 파일입니다. 이것은 항상 켜져 있는(always-on) 레이어입니다. 모든 작업에 로드될 만큼 충분히 짧으면서도, 출력을 바꿀 수 있을 만큼 충분히 구체적입니다.

# AGENTS.md — TaskFlow

코드를 작성하기 전에 이 파일을 읽으세요. 이것은 이 시스템이 어떻게 작동하는지에 대한 진실의 원천(source of truth)입니다.
...

해당 파일은 모든 프롬프트에서 로드됩니다. 하지만 데이터베이스 레이어가 어떻게 작동하는지에 대한 깊은 세부 사항은 그곳에 있어서는 안 됩니다. Prisma를 전혀 건드리지 않는 90%의 작업에서는 그것이 노이즈(noise)가 되기 때문입니다. 따라서 에이전트가 prisma/ 또는 src/lib/repositories/에서 작업할 때만 로드되는 범위 지정 규칙(scoped rule)에 포함시킵니다:

# database.md — 에이전트가 prisma/ 또는 src/lib/repositories/를 건드릴 때 로드됨

- 모든 모델은 `organizationId String`과 `@@index([organizationId])`를 가집니다.
...

이 분리가 핵심입니다. AGENTS.md는 항상 존재하므로 에이전트는 항상 시스템의 형태를 알고 있습니다. 데이터베이스 규칙은 적시(just-in-time)에 로드됩니다. 즉, 에이전트가 모델이나 리포지토리(repository)를 편집할 때만 로드되므로, 버튼 스타일을 수정하는 작업이 필요하지도 않은 테넌트 격리(tenant-isolation) 규칙에 대한 비용을 지불할 필요가 없습니다. 이것이 축소판 형태의 컨텍스트 엔지니어링(context engineering)입니다: 적절한 정보를, 적절한 순간에, 그 이상 없이 제공하는 것입니다.

직접 구축하는 방법 (단계별 가이드) (How to Build Your Own (Step by Step))

단 한나절 만에 실제 컨텍스트 레이어를 구축할 수 있습니다. 단계들은 서로를 기반으로 쌓여 올라가며, 단 하나의 구성 요소라도 모든 것을 망라하려는 유혹을 뿌리쳐야 합니다.

1. 간결한 AGENTS.md를 작성하세요. 스택 (Stack), 아키텍처 규칙 (architecture rules), 컨벤션 (conventions), 그리고 명시적인 "하지 말아야 할 것 (don't)" 목록을 포함하세요. 사람이 직접 작성한 것처럼 짧게 유지해야 합니다. 이 파일은 에이전트가 가장 많이 읽는 파일이므로, 무관한 한 줄 한 줄이 모든 작업에 세금(tax)처럼 작용하기 때문입니다. 전체 구조에 대해서는 SaaS를 위한 AGENTS.md 작성 방법을 참조하세요.
2. 작업별 세부 사항을 범위가 지정된 규칙 (scoped rules)으로 분리하세요. 코드베이스의 특정 영역(데이터베이스, 결제, 인증 등)에서만 중요한 사항은 경로(path)에 따라 자동으로 로드되는 별도의 규칙으로 만드세요. 이를 통해 항상 켜져 있는 레이어 (always-on layer)를 가볍게 유지하면서도, 중요한 지점에서는 심도 있는 가이드를 제공할 수 있습니다.
3. 문서를 코드 옆에 두고 커밋 시 재생성하세요. 에이전트가 읽을 수 있는 문서가 유용하려면 그 내용이 사실이어야 합니다. 문서 생성(doc generation)을 자동화하거나 커밋 흐름(commit flow)에 동기화 체크를 연결하여, 살아있는 문서가 거짓 정보로 변질되지 않도록 하세요.
4. 에이전트에게 최신 상태를 가져올 수 있는 도구 (tools)를 제공하세요. 현재의 스키마 (schema), 설정 값 (config value), 또는 쿼리 결과 (query result)를 프롬프트 (prompt)에 직접 붙여넣는 대신, 에이전트가 도구를 호출하여 직접 읽을 수 있게 하세요. 동적 컨텍스트 (Dynamic context)는 필요할 때마다 가져오기 때문에 결코 오래된 정보가 되지 않습니다.
5. 가지치기 (Prune) 하세요. 더 많은 컨텍스트가 더 좋은 것은 아닙니다. 컨텍스트 부패 (context rot)는 실제로 존재합니다. 항상 켜져 있는 레이어에서 에이전트에게 필요하지 않은 내용을 주기적으로 제거하세요. 이 규율은 무언가를 더하는 것만큼이나 빼는 것(subtractive)도 중요합니다.

이 모든 것의 중심에 있는 파일에 대한 실질적인 참고 사항: AGENTS.md는 도구 간의 표준 (cross-tool standard)이 되어가고 있습니다. Claude Code, Cursor, Windsurf, 그리고 Gemini CLI 모두 이 파일을 (또는 그와 유사한 파일) 읽습니다. 이는 당신이 한 번 작성한 컨텍스트가 팀원이 어떤 에이전트로 리포지토리 (repo)를 열더라도 함께 이동한다는 것을 의미합니다. 이러한 이식성 (portability)은 이를 제대로 구축하는 데 투자해야 할 실질적인 이유입니다.

컨텍스트 엔지니어링 (Context Engineering) vs RAG