컨텍스트 엔지니어링의 부상, 파일 선택 전략, 프로젝트 규칙 파일, RAG 기반 코드 검색, 1M 토큰 시대의 전략을 다룹니다.
AI 코딩 어시스턴트의 품질을 결정하는 가장 중요한 요소는 무엇일까요? 더 나은 모델? 더 정교한 프롬프트? 물론 중요하지만, 실무에서 가장 큰 차이를 만드는 것은 컨텍스트입니다.
같은 모델, 같은 프롬프트라도 어떤 코드와 정보를 함께 제공하느냐에 따라 결과가 극적으로 달라집니다. 이러한 인식이 확산되면서, 단순한 프롬프트 엔지니어링을 넘어 컨텍스트 엔지니어링(Context Engineering)이 "개발자 경험의 핵심"으로 부상하고 있습니다.
컨텍스트 엔지니어링은 다음 질문들에 답하는 것입니다.
AI 모델이 한 번에 처리할 수 있는 정보의 양에는 한계가 있습니다. 이를 컨텍스트 윈도우(Context Window)라고 하며, 이 공간을 어떻게 활용하느냐가 핵심입니다.
각 영역이 차지하는 비율을 의식적으로 관리해야 합니다.
| 영역 | 역할 | 최적화 방향 |
|---|---|---|
| 시스템 프롬프트 | 규칙, 컨벤션 전달 | 간결하되 구체적으로 |
| 소스 코드 | 작업 대상과 참고 코드 | 관련성 높은 파일만 선별 |
| 대화 히스토리 | 이전 맥락 유지 | 자기 요약으로 압축 |
| 도구 결과 | 검색, 실행 결과 | 필요한 부분만 발췌 |
| 현재 요청 | 사용자의 지시 | 명확하고 구체적으로 |
어떤 파일을 컨텍스트에 포함시킬 것인가는 결과 품질에 직접적인 영향을 줍니다.
대부분의 도구는 자동으로 관련 파일을 선택합니다. Copilot은 열린 탭과 인접 파일을, Cursor는 벡터 검색으로 관련 파일을 찾습니다. 하지만 자동 선택이 항상 최적은 아닙니다.
수동으로 파일을 지정해야 하는 상황은 다음과 같습니다.
@src/types/user.ts @src/services/auth-service.ts
UserService에 OAuth 소셜 로그인 기능을 추가해줘.
기존 auth-service의 패턴을 따라서 구현해줘.대규모 프로젝트에서는 계층적으로 컨텍스트를 구성하는 것이 효과적입니다.
1단계 (항상 포함): 프로젝트 규칙 파일, 타입 정의
2단계 (작업별 포함): 직접 수정할 파일, 관련 테스트
3단계 (참조용 포함): 유사 구현, API 문서
4단계 (필요시 포함): 설정 파일, 마이그레이션 히스토리"모든 것을 포함시키면 되지 않나?"라고 생각할 수 있지만, 실제로는 관련 없는 정보가 많을수록 AI의 주의가 분산되어 품질이 떨어질 수 있습니다. 이를 "컨텍스트 오염"이라 부르며, "Lost in the Middle" 현상과 관련이 있습니다. 관련 있는 정보를 선별하여 제공하는 것이 핵심입니다.
프로젝트 규칙 파일은 AI에게 프로젝트의 컨벤션과 규칙을 지속적으로 전달하는 메커니즘입니다. 도구별로 다른 이름과 형식을 사용합니다.
You are working on a Next.js project.
Rules:
- Always use TypeScript with strict mode
- Use function declarations, not arrow functions for components
- Use cn() for className composition
- Write all comments in Korean# Project — CLAUDE.md
## 기술 스택
- Next.js 16, TypeScript strict, Tailwind CSS v4
## 개발 명령어
pnpm dev # 개발 서버
pnpm build # 빌드
## 핵심 규칙
1. any 타입 사용 금지
2. 컴포넌트는 function 선언
3. 변경 후 빌드 통과 필수# Agent Instructions
## Code Style
- Use TypeScript strict mode
- Follow existing patterns in the codebase
## Testing
- Write tests for all new functions
- Use vitest for unit tests세 형식은 이름이 다르지만, 효과적인 규칙 파일 작성의 원칙은 동일합니다.
DO — 해야 할 것:
DON'T — 하지 말아야 할 것:
프로젝트 규칙 파일은 "AI를 위한 온보딩 문서"입니다. 새 팀원이 프로젝트에 합류했을 때 가장 먼저 알아야 할 핵심 정보를 담되, AI가 코드 작업을 수행하는 데 직접적으로 필요한 정보에 집중하세요.
도구별로 컨텍스트를 명시적으로 추가하는 방법이 있습니다.
| 멘션 | 용도 | 사용 예시 |
|---|---|---|
@file | 파일 참조 | @src/lib/utils.ts |
@folder | 디렉토리 참조 | @src/components/ui |
@code | 심볼 참조 | @calculateTotal |
@web | 웹 검색 | @web Next.js 16 App Router changes |
@docs | 문서 참조 | @docs React 19 |
Claude Code에서는 대화 중에 파일 경로를 언급하면 자동으로 관련 파일을 읽습니다. 또한 서브에이전트를 통해 대규모 검색을 효율적으로 수행합니다.
"src/services/ 디렉토리의 모든 서비스 파일에서
에러 핸들링 패턴을 분석하고,
가장 일관된 패턴으로 통일해줘."이 경우 Claude Code는 서브에이전트를 사용하여 여러 파일을 병렬로 분석한 뒤, 메인 에이전트가 종합적인 판단을 내립니다.
대규모 코드베이스에서는 모든 코드를 컨텍스트에 포함시킬 수 없습니다. 이때 RAG(Retrieval-Augmented Generation) 기반 코드 검색이 활용됩니다.
RAG의 효과는 검색 품질에 달려 있습니다. 다음 전략이 도움이 됩니다.
RAG는 강력하지만 완벽하지 않습니다. 간접적으로 관련된 파일(예: 설정 파일, 타입 정의)은 의미적 유사도가 낮아 누락될 수 있습니다. 중요한 파일은 수동으로 포함시키는 것이 안전합니다.
Gemini를 필두로 1M 토큰 이상의 컨텍스트 윈도우가 보편화되고 있습니다. 이는 컨텍스트 관리 전략을 근본적으로 변화시킵니다.
소규모 프로젝트 (5K줄 이하):
→ 전체 코드베이스 포함 + 프로젝트 규칙
중규모 프로젝트 (5K-50K줄):
→ 핵심 파일 전체 포함 + 관련 파일 선별 포함
대규모 프로젝트 (50K줄 이상):
→ RAG 기반 선별 + 수동 핵심 파일 포함
→ 모노레포: 관련 패키지만 선택적 포함컨텍스트 윈도우가 아무리 커져도, "어떤 정보를 어떤 순서로 제공하느냐"는 여전히 중요합니다. 가장 관련 있는 정보를 앞쪽에 배치하고, 프로젝트 규칙은 항상 최상단에 위치시키는 것이 좋습니다.
컨텍스트 엔지니어링을 실무에 적용하기 위한 체크리스트입니다.
프로젝트 설정 단계:
일상적 사용 단계:
팀 수준:
이번 장에서는 AI 코딩 어시스턴트의 효과를 결정하는 핵심 요소인 컨텍스트 관리를 다루었습니다.
다음 장에서는 컨텍스트 위에서 AI와 소통하는 방법, 즉 프롬프트 최적화와 효과적 사용법을 다루겠습니다.
이 글이 도움이 되셨나요?
관련 주제 더 보기
코딩 프롬프트 패턴, 작업 분해 전략, 반복 개선 워크플로우, 코드 리뷰/디버깅/리팩터링 프롬프팅, 도구별 최적 사용법을 다룹니다.
Windsurf Cascade, OpenAI Codex CLI, Google Antigravity, Amazon Q, Gemini Code Assist, JetBrains AI, Aider 등 주요 AI 코딩 도구들의 특성과 포지셔닝을 비교합니다.
HumanEval, SWE-bench, CursorBench 등 주요 벤치마크, pass@k 메트릭, AI 코드 품질 문제, 품질 게이트 설계, 자동화된 검증 파이프라인을 다룹니다.