컨텍스트 관리: 새로운 핵심 역량

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

컨텍스트 윈도우: AI의 작업 기억

AI에게는 컨텍스트 윈도우라는 제한된 작업 기억이 있다. 사람의 단기 기억에 비유할 수 있지만, 작동 방식은 근본적으로 다르다.

항목	사람의 단기 기억	AI의 컨텍스트 윈도우
용량	7 +/- 2개 항목	수천에서 백만 토큰
특성	주의력이 분산되면 잊음	윈도우 밖의 정보는 존재하지 않음
갱신	새 정보가 들어오면 오래된 것이 밀려남	대화가 길어지면 초반 내용 영향력 감소
품질 저하	피로, 멀티태스킹	노이즈 증가, 핵심 정보 매몰
보완 수단	메모, 문서화	CLAUDE.md, 프로젝트 파일

컨텍스트 윈도우의 핵심 제약

컨텍스트 예산이라는 관점

관찰 기반 모델

위 비중은 토큰 계산 공식이 아니라, 어떤 정보에 예산을 우선 배분해야 하는지 보여주는 설명용 모델입니다.

토큰 소비 감각 익히기

실제 작업에서 컨텍스트를 얼마나 사용하는지 추정하는 방법이다.

항목	토큰 추정	비고
CLAUDE.md	500-2000	프로젝트 규모에 비례
소스 파일 1개 (200줄)	약 800	언어와 주석에 따라 변동
타입 정의 파일 1개	약 400	인터페이스, enum 위주
대화 메시지 1턴	100-500	요청 복잡도에 따라
AI 응답 1턴	200-2000	코드 포함 시 급증
누적 대화 (20턴)	5000-20000	세션 길이에 비례

컨텍스트 과부하의 신호들

다음 증상이 보이면 컨텍스트가 과부하 상태일 가능성이 높다.

AI가 이전에 합의한 규칙을 갑자기 무시
응답이 산만해지고 핵심을 놓침
같은 질문을 했는데 이전과 다른 스타일의 답변
프롬프트의 특정 지시를 빠뜨림

이런 신호가 보이면 /compact로 대화를 정리하거나, 새 세션을 시작하는 것이 효과적이다.

64k 출력 시대: "작게 나눠라"는 습관의 재고

과거 습관	현재 최적 전략	이유
함수 하나씩 생성 요청	모듈 전체를 한 번에 요청	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 (추상적 원칙만 나열한 예)

## 원칙
- 클린 코드를 작성하라
- 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가 자주 틀리는 것	반복 실수 방지	같은 실수 매번 반복

컨텍스트 오염이라는 현상

오염의 유형과 대응

오염 유형	구체적 증상	대응 방법
관련 없는 파일 포함	엉뚱한 파일의 패턴을 모방	작업 범위 파일만 선별
대화 이력 과다	초반 지시사항이 묻힘	`/compact`로 정리, 핵심 지시 재강조
모순된 규칙	일관성 없는 코드 생성	CLAUDE.md 내 규칙 충돌 점검
오래된 코드 참조	deprecated 패턴 재사용	최신 코드만 컨텍스트에 포함
과도한 주석	주석 내용이 실제 코드보다 영향력 행사	핵심 주석만 유지

## /compact 또는 새 세션용 요약 템플릿

- 현재 작업: ___
- 이미 결정한 규칙: ___
- 반드시 유지할 제약: ___
- 아직 미해결인 질문: ___
- 다음 턴에서 바로 볼 파일: ___

파일 구조와 네이밍이 전달하는 암묵적 컨텍스트

파일 경로	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/`에 모든 파일이 혼재

리팩토링의 숨은 효과

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를 작성하거나 점검할 때, 몇 가지 관점에서 바라보면 도움이 된다.

관점	좋은 상태	개선이 필요한 상태
길이	200줄 이하	일반론이 많아 비대해진 상태
규칙 충돌	모순 0건	충돌하는 규칙 존재
최신성	최근 1개월 내 수정	오래된 규칙이 남아 있음
구체성	모든 규칙에 예시 포함	추상적 원칙만 나열

작업 유형별 컨텍스트 전략

작업별 컨텍스트 구성

작업 유형	필수 컨텍스트	선택 컨텍스트	제외할 것
새 파일 생성	패턴 파일 1개, 타입 정의	관련 테스트, API 스펙	전체 디렉토리 구조
버그 수정	에러 파일, 에러 로그	관련 모듈, git blame	관련 없는 모듈
리팩토링	대상 파일, 테스트	의존 파일, 아키텍처 문서	변경 범위 밖 파일
API 개발	스키마/타입, 기존 API	인증 모듈, 미들웨어	프론트엔드 코드
코드 리뷰	diff, 테스트	요구사항, CLAUDE.md	변경 안 된 파일

다음 장 미리보기

참고 자료

참고 자료 안내

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

컨텍스트 관리: 새로운 핵심 역량

목차

컨텍스트 관리: 새로운 핵심 역량

목차