AI 코딩을 위한 컨텍스트 엔지니어링 (Context Engineering): AGENTS.md, Cursor Rules 및 RAG

2025년, AI 안전 및 역량 연구 기관인 METR는 엄격한 무작위 대조 시험 (randomized controlled trial)을 실시했습니다. 16명의 숙련된 오픈 소스 개발자들이 246개의 실제 작업에 참여했으며, 각 작업은 AI 코딩 도구를 자유롭게 사용하거나 전혀 사용하지 않는 방식 중 하나로 무작위 배정되었습니다.

결과는 직관에 반했습니다. AI 도구를 사용하는 개발자들은 복잡한 작업에서 19% 더 느렸습니다.

연구 전, 동일한 개발자들은 AI가 자신들을 24% 더 빠르게 만들어 줄 것이라고 예측했습니다. 실험을 마친 후에도 — 여전히 자신이 더 빨라졌다고 믿으며 — 그들의 주관적인 확신은 전혀 흔들리지 않았습니다.

이 발견은 사람들이 예상했던 이유로 헤드라인을 장식하지 않았습니다. 헤드라인은 "AI는 쓸모없다"가 아니었습니다. 헤드라인은 바로 이것이었습니다: 병목 현상은 모델의 품질이 아닙니다. 그것은 컨텍스트 (context)의 품질입니다.

속도가 느려진 개발자들은 연구자들이 "검증 오버헤드 (verification overhead)" 및 "워크플로 마찰 (workflow friction)"이라고 부르는 작업에 상당한 시간을 소비하고 있었습니다. 이는 AI가 자신이 작업 중인 코드베이스의 아키텍처 제약 조건, 명명 규칙 (naming conventions), 기존 유틸리티 함수, 그리고 확립된 패턴을 이해하지 못해 발생하는 AI 출력물을 수정하는 데 필요한 노력을 의미합니다. AI는 코드를 생성하고 있었습니다. 그것은 상상 속의 시스템을 위한 코드를 생성하고 있었던 것입니다.

이 시리즈의 이번 부분은 바로 그 문제를 해결하는 것에 관한 것입니다.

시리즈 안내: 이 글은 AI Code Review & Vibe Coding 시리즈의 제2부로, AI 생성 결과물을 코드베이스 컨벤션(codebase conventions)에 맞추기 위해 필요한 컨텍스트 엔지니어링 (Context Engineering) 실무를 상세히 다룹니다. 초기 도구 및 비기술적 바이브 코딩 (non-technical vibe coding)에 관한 이전 가이드는 Part 1 — Vibe Coding & The Production Wall을 참조하세요.

범위 참고 사항: 이 글은 특히 _코드 리뷰 수준 (code-review-level)_의 컨텍스트 엔지니어링에 초점을 맞춥니다. 즉, 개별 엔지니어와 팀이 기존 코드베이스 위에서 AI 에이전트(AI agents)가 리뷰 가능하고 아키텍처적으로 올바른 코드를 생성하도록 만드는 실무를 다룹니다. 만약 _플랫폼 수준 (platform-level)_의 컨텍스트 인프라 — 조직 차원의 AI 플랫폼 레이어 구축, 대규모 내부 RAG 시스템, 또는 엔터프라이즈 지식 관리 — 에 관심이 있다면, AI-Driven Playbook 시리즈의 Context Engineering: Domain-Driven Design for AI를 참조하세요.

근본적인 문제: AI는 백지 상태에서 작동한다

AI 코딩 도구와 새로운 세션을 시작할 때마다, 당신은 제로(zero) 상태에서 시작하게 됩니다. 모델은 다음 사항에 대해 전혀 알지 못합니다:

당신의 아키텍처 결정 사항과 그 결정을 내린 이유
어떤 패턴을 표준화하여 사용 중인지, 그리고 어떤 패턴에서 벗어나 전환 중인지
당신의 팀이 "서비스 (service)", "핸들러 (handler)", "컨트롤러 (controller)"를 각각 무엇이라 부르는지
공유 라이브러리에 이미 어떤 유틸리티 함수 (utility functions)가 존재하는지
당신의 코드베이스에서 "성공적인" PR (Pull Request)이란 어떤 모습인지 — 무엇이 리뷰를 통과하고 무엇이 거절되는지

이러한 정보가 없다면, AI는 당신의 코드베이스를 한 번도 본 적 없는, 매우 빠르고 매우 자신만만한 주니어 개발자처럼 작동합니다. 그리고 AI는 당신의 시스템에 올바른 패턴이 아니라, 자신의 학습 데이터에서 가장 흔했던 패턴을 그대로 재현할 것입니다.

**컨텍스트 엔지니어링 (Context engineering)**은 조직의 지식을 AI 에이전트가 신뢰할 수 있는 방식으로 사용할 수 있도록 구조화하고 전달하는 규율입니다. 현재 업계의 합의에 따르면, 이는 AI를 위한 "DevOps 모멘트 (DevOps moment)"라고 할 수 있습니다. 즉, 실험적인 AI 보조를 신뢰할 수 있는 프로덕션급 (production-grade) AI 협업으로 분리하는 운영 계층입니다.

컨텍스트 계층 구조: 파일에서 RAG 파이프라인까지

현대의 AI 코딩 환경은 여러 계층에서 컨텍스트를 지원합니다. 이 계층 구조를 이해하는 것이 모든 효과적인 컨텍스트 전략의 기초입니다.

계층 1: 규칙 파일 (항상 활성화, 오버헤드 없음)

규칙 파일은 모든 AI 상호작용에 자동으로 주입되는 일반 텍스트 구성 파일입니다. 이는 가장 중요하면서도 가장 활용도가 낮은 형태의 컨텍스트입니다.

AGENTS.md (또는 CLAUDE.md / GEMINI.md)

저장소(repository)의 루트에 저장되는 이 파일들은 AI 에이전트가 작업을 시작하기 전에 읽습니다. 이 파일들은 에이전트의 상시 명령(standing orders) 역할을 합니다. 즉, 에이전트가 수행하는 모든 작업에 적용되는 아키텍처 제약 사항, 행동 표준, 그리고 명시적인 금지 사항을 정의합니다.

잘 구조화된 AGENTS.md는 다음 내용을 포함합니다:

# Project Architecture
This is a Kratos v2 microservice using Clean Architecture.
Layer rules:
...

핵심은 구체성입니다. "클린 아키텍처 (clean architecture)를 따르세요"와 같은 일반적인 지침은 일관되지 않은 결과를 낳습니다. 반면 "비즈니스 계층 (biz layer)은 절대로 gorm.DB를 직접 임포트(import)해서는 안 됩니다"와 같은 구체적인 지침은 결정론적인 (deterministic) 결과를 만들어냅니다.

Cursor Rules (.cursorrules)

Cursor의 규칙 파일은 AGENTS.md와 유사하게 작동하지만, Cursor IDE에 네이티브하게 통합되어 있습니다. 이들은 범위가 지정된 규칙 (scoped rules)을 지원합니다. 즉, 서로 다른 파일 패턴에 대해 각기 다른 동작을 정의할 수 있고, 언어별 표준을 강제할 수 있으며, AI가 절대 수정해서는 안 되는 파일을 지정할 수 있습니다.

[rules]
name = Go Microservice Standards
glob = **/*.go
...

실질적인 효과는 다음과 같습니다: 이제 당신의 AI 어시스턴트는 매 프롬프트마다 사후에 패치하는 방식이 아니라, 당신의 표준이 내장된 상태로 작동하게 됩니다.

규칙 파일이 아키텍처 누수(Architectural Leakage)를 방지하는 방법 (Go / Kratos 예시)

다음과 같은 요청을 가정해 봅시다: "서비스 레이어에서 이메일로 사용자 프로필을 조회하세요."

규칙 파일(AGENTS.md)이 없는 경우: AI는 클린 아키텍처 (Clean Architecture) 설계를 무시하고 어댑터 서비스 레이어 (adapter service layer) 내부에 직접 GORM 쿼리를 작성할 것입니다:
```
// File: internal/service/user.go
func (s *UserService) GetProfileByEmail(ctx context.Context, req *pb.GetProfileReq) (*pb.GetProfileReply, error) {
    var user biz.User
```

...
```

규칙 파일(AGENTS.md)이 있는 경우: AI는 레이어 격리 (layer isolation)를 강제하여, GORM 접근을 오직 영속성 도메인 (persistence domain, repository) 및 비즈니스 유스케이스 (business use case)를 통해서만 수행하도록 유도합니다:
```
// File: internal/service/user.go
func (s *UserService) GetProfileByEmail(ctx context.Context, req *pb.GetProfileReq) (*pb.GetProfileReply, error) {
    // 올바른 방법: 서비스가 biz 레이어 오케스트레이터 (UseCase)를 호출함
```

...
```

레이어 2: 세션 관리 (능동적 컨텍스트 제어)

규칙 파일이 갖춰져 있더라도, 긴 세션은 성능을 저하시킵니다. 이것이 바로 "컨텍스트 부패 (context rot)" 현상입니다. 세션에 실패한 시도, 수정된 오류, 폐기된 계획 노트 등이 쌓이면서 컨텍스트 윈도우 (context window) 내의 신호 대 잡음비 (signal-to-noise ratio)가 떨어지게 됩니다. 모델은 근본적인 제약 조건보다 최근의 잡음(noise)을 우선시할 수 있습니다.

새 세션 전략 (The Fresh Session Strategy)

성과가 높은 엔지니어링 팀은 AI 세션을 상태가 없는 함수 (stateless functions)처럼 취급합니다. 즉, 세션당 하나의 명확한 작업만 수행합니다. 버그 수정을 완료하면 세션을 종료하세요. 새로운 기능을 시작할 때는 새로운 세션을 여세요. 운영 규칙은 다음과 같습니다: 작업의 경계가 곧 세션의 경계입니다.

구조화된 핸드오버 (Structured Handovers)

작업이 완료되기 전에 세션이 너무 길어지면, 다음과 같이 구조화된 핸드오버를 수행하십시오:

AI에게 다음과 같이 요약을 요청하십시오: "우리가 내린 결정은 무엇인가요? 현재 상태는 어떠한가요? 남은 작업은 무엇인가요?"
해당 출력 내용을 프로젝트 디렉토리 내의 PLAN.md 또는 HANDOVER.md 파일에 저장하십시오.
새로운 세션을 열고, 핵심 규칙 파일(core rule files)과 함께 해당 요약본을 로드하십시오.

이렇게 하면 모든 의미 있는 진행 상황을 보존하면서도 컨텍스트 부패 (context rot)를 방지할 수 있습니다.

압축 명령 (Compaction Commands)

최신 코딩 에이전트 (Claude Code, Cursor)에는 /compact 또는 /summarize 명령어가 포함되어 있습니다. 세션이 길어질 때, 즉 모델이 컨텍스트 제한 (context limit)에 도달하여 성능이 저하되기 전에 이를 선제적으로 사용하십시오. 압축된 요약본은 계속 쌓여가는 가공되지 않은 대화 스트림보다 훨씬 더 높은 품질의 입력값이 됩니다.

레이어 3: 리포지토리 인덱싱 (Repository Indexing, 선택적 컨텍스트 주입)

규칙 파일 (Rule files)은 표준을 설정합니다. 세션 관리 (Session management)는 노이즈를 제어합니다. 리포지토리 인덱싱 (Repository indexing)은 다른 문제, 즉 AI에게 코드베이스에 이미 존재하는 것에 대한 정확한 지식을 제공하는 문제를 해결합니다.

N+1 발견 문제 (The N+1 Discovery Problem)

리포지토리 컨텍스트가 없으면, AI 에이전트는 이미 존재하는 함수를 반복해서 구현하는 일이 빈번하게 발생합니다. 기존 테이블과 중복되는 새로운 데이터베이스 테이블을 생성하거나, 이미 확립된 패턴과 충돌하는 에러 타입 (error types)을 정의하기도 합니다. 또한 의존성 그래프 (dependency graph)를 위반하는 패키지를 임포트하기도 합니다. 이는 AI가 더 잘할 능력이 없어서가 아니라, 무엇이 이미 존재하는지 모르기 때문입니다.

수동 선택 vs 전체 리포지토리 스캔 (Manual Selection vs. Full-Repo Scanning)

대부분의 AI 코딩 도구는 전체 리포지토리를 자동으로 스캔하는 기능을 제공합니다. 이는 가치 있어 보이지만 종종 역효과를 낳습니다. 대규모 코드베이스를 컨텍스트에 통째로 주입하면 무관한 파일, 오래된 패턴, 폐기된 모듈 등 상당한 노이즈가 추가됩니다. 원칙은 다음과 같습니다: 작업과 직접적으로 관련된 파일만 수동으로 선택하십시오.

사용자 인증 (user authentication)을 수정하는 작업의 경우, 관련 컨텍스트는 다음과 같습니다:

인증 서비스 인터페이스 (authentication service interface)
기존 사용자 리포지토리 구현체 (user repository implementation)
세션 관리 미들웨어 (session management middleware)
관련 에러 타입 정의 (error type definitions)

전체 코드베이스가 아닙니다.

시맨틱 메모리 뱅크 (Semantic Memory Banks)

더욱 정교한 팀들은 큐레이션된 "메모리 뱅크 (memory bank)" 파일들을 유지 관리합니다. 이는 AI가 소비하기에 최적화된 형태로 코드베이스의 아키텍처 (architecture), 주요 패턴 (key patterns), 그리고 중요한 결정 사항들을 기술한 구조화된 마크다운 (markdown) 문서입니다:

# Memory Bank: Authentication Domain

## Architecture
...

이러한 메모리 뱅크는 중요한 아키텍처 결정이 내려질 때마다 업데이트되며, 코드와 함께 저장소 (repository)에 커밋됩니다.

레이어 4: RAG 파이프라인 (RAG Pipelines) (엔터프라이즈 규모의 컨텍스트)

수백 개의 서비스, 성숙한 문서화, 그리고 복잡한 아키텍처 표준을 가진 대규모 엔지니어링 조직의 경우, 정적인 규칙 파일만으로는 불충분합니다. 특정 작업에 필요한 관련 컨텍스트 (context)는 너무 빠르게 변하며, 수동으로 관리하기에는 너무 많은 곳에 존재합니다.

코드 컨텍스트를 위한 **검색 증강 생성 (Retrieval-Augmented Generation, RAG)**은 다음과 같은 방식으로 작동합니다:

코드베이스, 아키텍처 결정 기록 (Architecture Decision Records, ADRs), 런북 (runbooks), 그리고 내부 문서를 벡터 데이터베이스 (vector database)에 인덱싱 (indexing)합니다.
AI 에이전트가 작업을 시작할 때, 해당 인덱스에서 의미론적으로 가장 관련성이 높은 컨텍스트를 자동으로 쿼리 (querying)합니다.
검색된 컨텍스트를 작업 설명과 함께 세션에 주입 (injecting)합니다.

운영 결과: 결제 기능(payments feature)을 작업하는 AI 에이전트는 엔지니어가 수동으로 컨텍스트를 큐레이션하지 않아도, 관련 결제 서비스 인터페이스 (payment service interfaces), 현재 트랜잭션 모델을 선택한 이유를 설명하는 ADR, 그리고 결제 제공업체 연동을 위한 런북을 자동으로 검색하여 가져옵니다.

기계 판독 가능한 판단 도구로서의 ADR (ADRs as Machine-Readable Judgment)

아키텍처 결정 기록 (ADRs)은 특별한 주의를 기울일 가치가 있습니다. 구조화된 형식으로 커밋되어 RAG 파이프라인에 인덱싱되면, ADR은 정적인 문서에서 능동적인 제약 사항 (constraints)으로 변모합니다:

# ADR-047: Event-Sourcing for Order State Transitions

## Status: Accepted (2025-03)
...

이 ADR에 접근할 수 있는 AI 에이전트는 주문 상태 변경을 위해 UPDATE orders SET status = ?와 같은 직접적인 쿼리를 생성하지 않을 것입니다. 이 정보가 없다면, 에이전트는 거의 확실히 그렇게 할 것입니다.

컨텍스트 인프라로서의 MCP 서버 (MCP Servers as Context Infrastructure)

Anthropic이 출시하고 현재 업계 전반에서 채택하고 있는 Model Context Protocol (MCP)은 AI 에이전트에게 컨텍스트를 제공하기 위한 표준화된 인터페이스를 제공합니다. 조직은 각 AI 도구마다 맞춤형 통합(bespoke integrations)을 구축하는 대신, 표준 프로토콜을 통해 특정 조직 지식(문서, 코드 패턴, 티켓 컨텍스트)을 노출하는 경량 서비스인 MCP 서버를 구축합니다.

이를 통해 가능한 변화: 컨텍스트 인프라가 엔지니어 개별의 설정 문제(per-engineer configuration problem)가 아닌, 조직의 공유 자산이 됩니다.

ContextOps 방법론 (The ContextOps Discipline)

이제 업계에서는 조직 규모의 컨텍스트 인프라를 운영하는 것에 대해 ContextOps라는 이름을 붙였습니다.

운영 루프는 다음과 같습니다: 수집 (Ingest) → 검증 (Validate) → 구조화 (Structure) → 제공 (Serve) → 감사 (Audit) → 개선 (Refine).

수집 (Ingest): Confluence, Notion, ADR 파일, 런북(runbooks), Slack 아키텍처 논의 내용 등에서 데이터를 가져옵니다.
검증 (Validate): 콘텐츠가 정확하고 최신 상태이며 모순되지 않는지 확인합니다.
구조화 (Structure): AI가 소비하기 좋은 형태로 포맷팅합니다 — 명확한 헤더, 명시적인 "do/do not" 섹션, 구조화된 코드 예시 등.
제공 (Serve): MCP 서버, 규칙 파일(rule files), 또는 RAG 검색을 통해 제공합니다.
감사 (Audit): AI 출력이 컨텍스트를 준수하고 있는지 모니터링합니다 (만약 에이전트가 컨텍스트에서 금지한 실수를 계속 반복한다면, 컨텍스트가 틀렸거나 불분명한 것입니다).
개선 (Refine): 감사를 통해 드러난 내용을 바탕으로 컨텍스트를 업데이트합니다.

컨텍스트를 일회성 설정(throwaway configuration) — 즉, 임시로 업데이트되고, 일관성 없는 형식으로 작성되며, 인덱싱되지 않은 마크다운(markdown) 파일에 저장되는 방식 — 으로 취급하는 조직은 METR 결과, 즉 팀의 속도를 늦추는 AI를 경험하게 됩니다. 반면 컨텍스트를 인프라 — 버전 관리되고, 검증되며, 모니터링되는 대상 — 로 취급하는 조직은 의미 있게 다른 결과를 경험합니다.