컨텍스트 관리: 새로운 핵심 역량
컨텍스트 윈도우를 작업 기억으로 이해하고, 프로젝트·세션·프롬프트 3계층으로 정보를 나눠 CLAUDE.md와 컨텍스트 예산으로 AI 출력 품질을 끌어올리는 법
핵심 요약
- 컨텍스트 윈도우는 AI의 작업 기억이며, 윈도우 밖 정보는 존재하지 않으므로 "규칙을 무시했다"는 대부분 컨텍스트에 넣지 않은 탓이다.
- 입력(컨텍스트)과 출력(생성 토큰)은 별개의 예산이다. Opus의 64k 출력 시대에는 "작게 나눠라"는 출력 측 습관을 의식적으로 내려놓는다.
- 컨텍스트는 프로젝트(CLAUDE.md)·세션·프롬프트 3계층으로 나누면 각 프롬프트가 간결해진다.
- CLAUDE.md는 일반론이 아닌 프로젝트 고유 규칙과 "AI가 자주 틀리는 것"을 담은, 함께 성장하는 온보딩 문서로 다룬다.
- 컨텍스트는 많을수록 좋은 게 아니다. 관련 없는 파일과 너무 긴 대화 이력은 노이즈가 신호를 덮는 오염을 일으키므로 선별과 /compact가 필요하다.
AI 코딩 도구의 출력 품질은 프롬프트의 품질에 달려 있고, 프롬프트의 품질은 컨텍스트의 품질에 달려 있다. 같은 AI라도 어떤 정보를 주느냐에 따라 결과가 극적으로 달라진다.
컨텍스트 관리가 AI 시대 개발자의 핵심 역량이라는 건, AI 도구를 얼마간 써본 개발자라면 대부분 체감한다. 컨텍스트를 어떻게 설계하고, 얼마나 제공하며, 언제 정리할지를 두고 쌓은 관찰과 경험을 공유한다.
컨텍스트 윈도우: AI의 작업 기억
AI에게는 컨텍스트 윈도우라는 제한된 작업 기억이 있다. 사람의 단기 기억에 비유할 수 있지만, 작동 방식은 근본적으로 다르다.
| 항목 | 사람의 단기 기억 | AI의 컨텍스트 윈도우 |
|---|---|---|
| 용량 | 7 +/- 2개 항목 | 수천에서 백만 토큰 |
| 특성 | 주의력이 분산되면 잊음 | 윈도우 밖의 정보는 존재하지 않음 |
| 갱신 | 새 정보가 들어오면 오래된 것이 밀려남 | 대화가 길어지면 초반 내용 영향력 감소 |
| 품질 저하 | 피로, 멀티태스킹 | 노이즈 증가, 핵심 정보 매몰 |
| 보완 수단 | 메모, 문서화 | CLAUDE.md, 프로젝트 파일 |
컨텍스트 윈도우의 핵심 제약
AI는 컨텍스트 윈도우 안에 있는 정보만으로 판단한다. "프로젝트에 이런 규칙이 있는데 AI가 무시했다"는 불만의 대부분은, 해당 규칙을 컨텍스트 안에 넣지 않았기 때문인 경우가 많다.
컨텍스트 예산이라는 관점
컨텍스트 윈도우가 무한하지 않다는 사실은 자연스럽게 "예산"이라는 사고방식으로 이어진다. 한정된 자원을 어디에 투자하느냐가 결과 품질을 가른다.
관찰 기반 모델
위 비중은 토큰 계산 공식이 아니라, 어떤 정보에 예산을 우선 배분해야 하는지 보여주는 설명용 모델입니다.
토큰 소비 감각 익히기
실제 작업에서 컨텍스트를 얼마나 사용하는지 추정하는 방법이다.
| 항목 | 토큰 추정 | 비고 |
|---|---|---|
| CLAUDE.md | 500-2000 | 프로젝트 규모에 비례 |
| 소스 파일 1개 (200줄) | 약 800 | 언어와 주석에 따라 변동 |
| 타입 정의 파일 1개 | 약 400 | 인터페이스, enum 위주 |
| 대화 메시지 1턴 | 100-500 | 요청 복잡도에 따라 |
| AI 응답 1턴 | 200-2000 | 코드 포함 시 급증 |
| 누적 대화 (20턴) | 5000-20000 | 세션 길이에 비례 |
컨텍스트 과부하의 신호들
다음 증상이 보이면 컨텍스트가 과부하 상태일 가능성이 높다.
- AI가 이전에 합의한 규칙을 갑자기 무시
- 응답이 산만해지고 핵심을 놓침
- 같은 질문을 했는데 이전과 다른 스타일의 답변
- 프롬프트의 특정 지시를 빠뜨림
이런 신호가 보이면 /compact로 대화를 정리하거나, 새 세션을 시작하는 것이 효과적이다.
64k 출력 시대: "작게 나눠라"는 습관의 재고
Claude Opus 4.6의 기본 출력이 64,000 토큰으로 늘면서 컨텍스트 관리 전략도 바뀌어야 한다. 과거에는 AI의 출력 길이 제한 때문에 작업을 작은 청크로 나눠 요청하는 것이 모범 사례였다. 이제는 큰 범위의 의도를 한 번에 전달하고 큰 범위의 결과를 한 번에 받아 검증하는 편이 더 효율적인 경우가 많다.
| 과거 습관 | 현재 최적 전략 | 이유 |
|---|---|---|
| 함수 하나씩 생성 요청 | 모듈 전체를 한 번에 요청 | 64k 출력으로 충분한 용량 |
| 파일별로 나눠서 지시 | 관련 파일 일괄 생성/수정 지시 | 파일 간 일관성 보장 |
| 단계별 점진 요청 | 전체 의도를 CICV로 한 번에 전달 | 컨텍스트 누적 비용 절약 |
| 코드만 생성 요청 | 코드 + 테스트 + 문서를 한 번에 | 출력 예산 여유 |
컨텍스트 예산의 양면
입력(컨텍스트 윈도우)과 출력(생성 토큰)은 별개의 예산이다. 입력은 여전히 신중하게 관리해야 하지만, 출력 측에서는 "작게 나눠라"는 기존 습관을 의식적으로 내려놓아야 할 시점이다.
컨텍스트의 3개 계층
컨텍스트를 잘 관리하는 개발자들을 보면, 대체로 범위에 따라 3개 계층으로 나눠 생각한다.
프로젝트 레벨 (변경 빈도: 낮음)
프로젝트 전체에 걸쳐 유효한 정보다. CLAUDE.md에 기록하고, 세션이 바뀌어도 유지된다.
- 기술 스택과 버전
- 디렉토리 구조
- 코드 컨벤션
- 공통 패턴 (에러 핸들링, 인증 등)
세션 레벨 (변경 빈도: 중간)
하나의 작업 세션 동안 유효한 정보다. 세션 시작 시 AI에게 전달하고, 작업이 끝나면 소멸한다.
- "오늘은 결제 모듈 리팩토링을 합니다"
- "관련 파일:
src/payment/,src/order/" - "Stripe에서 토스페이먼츠로 PG 전환 중입니다"
프롬프트 레벨 (변경 빈도: 높음)
개별 요청마다 달라지는 구체적 정보다.
- "이 함수에 타임아웃 파라미터를 추가해줘"
- 입력:
orderId: 123, 기대 출력:status: "cancelled" - "기존 API 응답 형식을 깨뜨리지 마"
계층 분리의 효과
이렇게 나누면 각 프롬프트가 간결해진다.
- 프로젝트 레벨은 CLAUDE.md가 자동 제공
- 세션 레벨은 세션 시작 시 1회 설정
- 프롬프트 레벨만 매번 작성
매번 "우리 프로젝트는 Next.js 16 + TypeScript이고..."라고 반복할 일이 없어진다.
실전 워크스루: 새 세션을 시작하는 5분 루틴
컨텍스트 관리는 길고 복잡한 문서를 만드는 일이 아니라, 세션 초반 5분을 구조화하는 일에 가깝다.
프로젝트 레벨 확인
먼저 CLAUDE.md와 현재 작업 브랜치의 맥락을 확인한다. 이 단계에서 기술 스택, 금지 규칙, 자주 틀리는 패턴이 비어 있으면 바로 메모해 둔다.
세션 목표를 한 문장으로 고정
"오늘 이 세션에서 무엇을 끝낼 것인가"를 한 줄로 적는다. 목표가 길어지면 작업 범위가 이미 넓다는 신호다.
필수 파일 3개만 선별
대상 파일, 관련 테스트, 규칙 파일 정도면 대부분 시작하기에 충분하다. 처음부터 디렉토리 전체를 넣는 것은 대개 과하다.
첫 프롬프트를 구조화
컨텍스트, 의도, 제약, 검증 기준을 짧게 적는다. 첫 프롬프트가 좀 길어지더라도 정확한 편이 여기서는 낫다.
## 세션 킥오프 템플릿
### 오늘 목표
- 예: 결제 취소 API의 부분 환불 로직을 수정하고 테스트까지 통과시키기
### 현재 컨텍스트
- 관련 파일: `src/payment/cancel.ts`, `src/payment/cancel.test.ts`
- 프로젝트 규칙: 금액은 Decimal 사용, 시간은 KST 기준
### 제약
- 기존 API 응답 형식 유지
- 실패 시 AppError로 래핑
### 검증
- 기존 테스트 통과
- 부분 환불 12-24시간 규칙 확인CLAUDE.md를 온보딩 문서처럼 다루기
CLAUDE.md를 잘 관리하는 팀에는 공통점이 하나 있다. 이 파일을 새 팀원에게 건네는 온보딩 문서처럼 다룬다는 점이다. 새 팀원이 첫날 알아야 할 내용을 적으면, 그게 곧 AI에게도 좋은 컨텍스트가 된다.
추상적인 원칙 vs 구체적인 규칙
효과가 적은 CLAUDE.md의 패턴
# CLAUDE.md (추상적 원칙만 나열한 예)
## 원칙
- 클린 코드를 작성하라
- SOLID 원칙을 준수하라
- 테스트를 작성하라
- 가독성 좋은 코드를 만들어라이런 내용은 AI가 이미 아는 일반론이다. 컨텍스트 예산만 까먹고 프로젝트 고유 정보는 하나도 주지 못한다.
효과적인 CLAUDE.md의 구조
# CLAUDE.md (프로젝트 고유 정보가 담긴 예)
## 프로젝트 개요
B2B SaaS 결제 플랫폼. 월 500만 건 트랜잭션 처리.
## 기술 스택
- Next.js 16 (App Router), React 19, TypeScript 5.7
- DB: PostgreSQL + Prisma ORM
- 인증: NextAuth v5, JWT
- PG: 토스페이먼츠 SDK v2
## 명령어
- 빌드: yarn build
- 테스트: yarn test (vitest)
- 린트: yarn lint (eslint + prettier)
## 코드 규칙
### 에러 핸들링
- 모든 API: try-catch + AppError 래핑
- 사용자 에러 메시지: i18n 키 사용, 하드코딩 금지
- 로깅: structured logging (winston), console.log 금지
### 날짜/시간
- 라이브러리: dayjs (moment.js 사용 금지)
- 타임존: 항상 Asia/Seoul 명시
- DB 저장: UTC, 표시: KST 변환
### DB
- N+1 쿼리 금지: include/join 필수
- 트랜잭션: 2개 이상 write 시 반드시 사용
- soft delete: deletedAt 필드 사용
## AI가 자주 틀리는 것
- API 응답: NextResponse.json 사용 (Response.json 아님)
- 인증 확인: getServerSession 사용 (middleware 아님)
- 금액: number 타입 금지, Decimal 타입 사용각 항목이 AI에게 미치는 영향
| CLAUDE.md 항목 | AI에게 주는 효과 | 없으면 발생하는 문제 |
|---|---|---|
| 프로젝트 개요 1-2줄 | 도메인 맥락 파악 | 범용적인 코드 생성 |
| 기술 스택 + 버전 | 정확한 API 사용 | deprecated API 사용 |
| 명령어 | 빌드/테스트 자동 실행 | 잘못된 명령어 제안 |
| 에러 핸들링 패턴 | 일관된 에러 처리 | 매번 다른 에러 처리 방식 |
| 날짜/시간 규칙 | 올바른 라이브러리 선택 | moment.js 사용, 타임존 누락 |
| AI가 자주 틀리는 것 | 반복 실수 방지 | 같은 실수 매번 반복 |
"AI가 자주 틀리는 것" 섹션이 특히 쓸모 있다. 프로젝트를 진행하다 AI가 반복해서 잘못 만드는 패턴을 발견할 때마다 여기 추가하면, CLAUDE.md가 프로젝트와 함께 자라는 살아있는 문서가 된다.
컨텍스트 오염이라는 현상
컨텍스트는 많을수록 좋은 게 아니다. 컨텍스트 오염은 관련 없는 정보가 AI의 판단을 흐트러뜨리는 현상인데, 직접 겪어보면 그 영향이 생각보다 크다.
오염의 유형과 대응
| 오염 유형 | 구체적 증상 | 대응 방법 |
|---|---|---|
| 관련 없는 파일 포함 | 엉뚱한 파일의 패턴을 모방 | 작업 범위 파일만 선별 |
| 대화 이력 과다 | 초반 지시사항이 묻힘 | /compact로 정리, 핵심 지시 재강조 |
| 모순된 규칙 | 일관성 없는 코드 생성 | CLAUDE.md 내 규칙 충돌 점검 |
| 오래된 코드 참조 | deprecated 패턴 재사용 | 최신 코드만 컨텍스트에 포함 |
| 과도한 주석 | 주석 내용이 실제 코드보다 영향력 행사 | 핵심 주석만 유지 |
컨텍스트 오염을 의심할 만한 상황이 있다. 10개 넘는 파일을 한꺼번에 AI에게 주고 있다거나, 대화가 30턴 넘게 이어지고 있다거나, AI가 앞서 합의한 패턴을 갑자기 무시하기 시작한다면 컨텍스트를 정리할 때다. AI 응답 품질이 대화 초반보다 떨어졌거나, 요청하지 않은 파일의 코드 스타일을 따라 하기 시작하는 것도 비슷한 신호다.
## /compact 또는 새 세션용 요약 템플릿
- 현재 작업: ___
- 이미 결정한 규칙: ___
- 반드시 유지할 제약: ___
- 아직 미해결인 질문: ___
- 다음 턴에서 바로 볼 파일: ___파일 구조와 네이밍이 전달하는 암묵적 컨텍스트
AI는 코드를 읽을 때 파일 이름과 디렉토리 구조에서 많은 것을 추론한다. 잘 정리된 구조는 따로 설명하지 않아도 컨텍스트를 전달하니, 어쩌면 가장 비용 효율적인 컨텍스트 제공 방식이다.
| 파일 경로 | AI가 추론하는 정보 |
|---|---|
src/api/users/route.ts | API 라우트, users 도메인, Next.js App Router |
src/lib/auth/session.ts | 인증 관련 유틸리티, 세션 관리 |
src/components/ui/Button.tsx | 재사용 UI 컴포넌트, 프레젠테이셔널 |
tests/integration/payment.test.ts | 통합 테스트, 결제 도메인 |
src/hooks/useDebounce.ts | 커스텀 훅, 디바운스 로직 |
구조의 품질과 AI 생산성
| 구조 품질 | AI에 미치는 영향 | 구체적 예시 |
|---|---|---|
| 일관된 네이밍 규칙 | 새 파일의 위치와 이름을 정확히 결정 | useXxx 훅, Xxx.test.ts 테스트 |
| 도메인별 디렉토리 분리 | 관련 파일을 정확히 찾아 참조 | src/payment/, src/order/ |
| 테스트 파일 위치 규칙 | 테스트를 올바른 위치에 생성 | co-located vs __tests__/ |
| 설정 파일 분리 | 환경별 설정을 구분 | config/dev.ts, config/prod.ts |
| 플랫한 구조 (안티패턴) | 매번 명시적 지시 필요 | src/에 모든 파일이 혼재 |
리팩토링의 숨은 효과
코드베이스를 깔끔하게 정리하는 리팩토링은 사람뿐 아니라 AI의 생산성도 높인다. 파일 구조가 잘 정리되어 있으면, CLAUDE.md에 적어야 할 규칙이 줄어든다. 구조 자체가 규칙을 말해주기 때문이다.
AGENTS.md: 에이전트 간 협업의 컨텍스트
CLAUDE.md가 사람-AI 협업용이라면, AGENTS.md는 AI 에이전트 간 협업을 위한 컨텍스트다. 서브에이전트나 자동화 파이프라인에서 참조한다.
# AGENTS.md
## 코드 생성 에이전트
- 새 파일 생성 시 반드시 기존 패턴 파일 참조
- 테스트 파일 동시 생성 필수
- 임포트는 절대 경로 사용 (@/ prefix)
## 리뷰 에이전트
- 보안 체크리스트 우선 확인
- 타입 안전성 검증
- 기존 API 계약 변경 감지 시 경고
## 리팩토링 에이전트
- 기능 변경 없이 구조만 개선
- 변경 전후 테스트 결과 동일 확인 필수두 파일의 성격 차이를 알면 각각을 더 잘 관리할 수 있다.
| 항목 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 대상 | 개발자와 AI의 대화 | AI 에이전트 간 자동화 |
| 톤 | 설명적, 맥락 포함 | 명령적, 규칙 위주 |
| 내용 | 기술 스택, 컨벤션, 배경 | 에이전트별 행동 규칙 |
| 갱신 주기 | 프로젝트 진화에 따라 | 워크플로우 변경 시 |
컨텍스트 관리에서 자주 관찰되는 실수들
| 실수 유형 | 증상 | 대응 | 예방 |
|---|---|---|---|
| 과잉 제공 | AI 응답이 산만, 핵심 지시 무시 | 관련 파일만 선별 | 파일 3-5개 이내 유지 |
| 부족 제공 | 범용적이고 맞지 않는 코드 | CLAUDE.md 보강 | 프로젝트 고유 규칙 정리 |
| 오래된 컨텍스트 | AI가 이전 결정을 잘못 적용 | /compact로 정리 | 20턴마다 정리 |
| 모순된 컨텍스트 | AI가 혼란스러운 코드 생성 | 규칙 충돌 점검 | CLAUDE.md 주기적 리뷰 |
| 암묵적 가정 | AI가 다른 가정으로 진행 | 가정을 명시 | "X라고 가정하라" 표현 |
CLAUDE.md의 품질을 가늠하는 관점
CLAUDE.md를 작성하거나 점검할 때, 몇 가지 관점에서 바라보면 도움이 된다.
기본적으로 담겨야 할 것들: 프로젝트가 무엇인지 1-2줄 설명, 빌드/테스트/린트 명령어, 핵심 디렉토리 구조, 기술 스택과 버전. 이것들이 빠져 있으면 AI는 매번 추측에 의존하게 된다.
있으면 품질이 올라가는 것들: 코드 컨벤션(네이밍, 에러 핸들링, 로깅), AI가 자주 틀리는 프로젝트 고유 규칙, 금지 사항(deprecated API, 사용 금지 라이브러리), 커밋/푸시 관련 규칙.
품질의 핵심: 일반론이 아닌 프로젝트 고유 정보만 담고 있는지가 가장 중요하다. "클린 코드를 작성하라"는 컨텍스트 예산만 소모할 뿐 AI의 출력을 개선하지 않는다. 반면 "금액은 number 타입 금지, Decimal 타입 사용"은 즉각적인 효과가 있다.
| 관점 | 좋은 상태 | 개선이 필요한 상태 |
|---|---|---|
| 길이 | 200줄 이하 | 일반론이 많아 비대해진 상태 |
| 규칙 충돌 | 모순 0건 | 충돌하는 규칙 존재 |
| 최신성 | 최근 1개월 내 수정 | 오래된 규칙이 남아 있음 |
| 구체성 | 모든 규칙에 예시 포함 | 추상적 원칙만 나열 |
CLAUDE.md는 한 번에 완성하는 문서가 아니라 프로젝트와 함께 자라는 문서다. AI가 반복해서 틀리는 부분을 발견할 때마다 한 줄씩 더하는 편이, 처음부터 완벽한 문서를 만들려는 것보다 현실적이다.
작업 유형별 컨텍스트 전략
작업 유형에 따라 AI에게 줄 컨텍스트의 종류와 양이 달라진다. 경험이 쌓이면 자연스럽게 감이 오지만, 대략적인 패턴을 미리 알면 초기 시행착오를 줄일 수 있다.
작업별 컨텍스트 구성
| 작업 유형 | 필수 컨텍스트 | 선택 컨텍스트 | 제외할 것 |
|---|---|---|---|
| 새 파일 생성 | 패턴 파일 1개, 타입 정의 | 관련 테스트, API 스펙 | 전체 디렉토리 구조 |
| 버그 수정 | 에러 파일, 에러 로그 | 관련 모듈, git blame | 관련 없는 모듈 |
| 리팩토링 | 대상 파일, 테스트 | 의존 파일, 아키텍처 문서 | 변경 범위 밖 파일 |
| API 개발 | 스키마/타입, 기존 API | 인증 모듈, 미들웨어 | 프론트엔드 코드 |
| 코드 리뷰 | diff, 테스트 | 요구사항, CLAUDE.md | 변경 안 된 파일 |
다음 장 미리보기
컨텍스트 관리가 개인 역량이라면, 다음은 팀 차원의 전환입니다. AI 시대에 기술 부채의 정의 자체가 바뀝니다. 무엇이 더 비싸지고 무엇이 더 싸졌는지, 기술 부채를 재정의하는 새로운 프레임워크를 다룹니다.
참고 자료
참고 자료 안내
이 장의 관점과 프레임워크를 뒷받침하는 참고 자료입니다. 본문의 모든 주장이 아래 자료에서 직접 인용된 것은 아니며, 실무 경험과 커뮤니티 사례를 종합한 해석이 포함되어 있습니다.
- Levy, M. et al. (2024). "Same Task, More Tokens: the Impact of Input Length on the Reasoning Performance of Large Language Models." https://arxiv.org/abs/2402.14848
- Anthropic (2025). "Claude Code Memory and CLAUDE.md." https://docs.anthropic.com/en/docs/claude-code/memory
- Anthropic (2025). "Long Context Window Tips." https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/long-context-tips