컨텍스트 팩

컨텍스트 팩(Context Pack)은 에이전트에게 반복해서 주입하는 작은 운영 문서입니다. Agentic MVP에서 컨텍스트 팩은 "코드 맥락"뿐 아니라 제품 약속, 타겟, 시장 신호, 금지 행동을 고정합니다.

컨텍스트 팩이 필요한 이유

• 같은 설명을 반복하는 시간을 줄인다
• 티켓/PR 품질이 일정해진다
• 팀 규칙(PII, 코드 스타일, DoD)이 자동으로 지켜진다
• 인터뷰/카피/이벤트/판정 기준이 한 방향으로 정렬된다

CLAUDE.md와 AGENTS.md: 도구별 컨텍스트 거처

Claude Code 중심 프로젝트는 CLAUDE.md, Codex 중심 프로젝트는 AGENTS.md를 기본 컨텍스트 파일로 둡니다. 여러 도구를 같이 쓰는 팀은 두 파일의 핵심 규칙을 맞추고, 도구별 세부 지시만 분리하세요.

추천 계층 구조

~/.claude/CLAUDE.md           ← 전역 개인 규칙
~/.codex/AGENTS.md            ← Codex 전역 개인 규칙
프로젝트 루트/CLAUDE.md        ← 프로젝트 공통 규칙
프로젝트 루트/AGENTS.md         ← Codex/범용 에이전트 공통 규칙
  └── src/CLAUDE.md            ← 이 경로의 파일을 다룰 때 추가 적용
  └── tests/CLAUDE.md          ← 테스트 파일을 다룰 때 추가 적용
프로젝트 루트/CLAUDE.local.md  ← 개인용 로컬 메모(보통 커밋하지 않음)

• 현재 작업 디렉터리와 그 상위 경로의 CLAUDE.md는 시작 시 함께 로드됩니다
• 하위 디렉터리의 CLAUDE.md는 그 경로의 파일을 읽거나 수정할 때 추가로 적용됩니다
• 팀 공통 규칙은 CLAUDE.md, 개인 선호나 임시 메모는 CLAUDE.local.md로 나누면 관리가 쉽습니다

추천 구조(템플릿)

아래를 프로젝트 루트 CLAUDE.md에 두고, 디렉터리별 규칙은 필요한 폴더에만 추가합니다.

컨텍스트 팩 업데이트 규칙

• 가설이 바뀌면 즉시 업데이트
• 범위가 커지면 "제외"를 더 구체화
• 새로 배운 사용자 표현(언어)을 카피에 반영
• 실패 모드/예외 케이스가 생기면 QA 항목에 추가

Skills와 커맨드: 반복 작업을 자동화

컨텍스트 팩과 함께, 커스텀 커맨드와 스킬을 조합하면 반복 워크플로우를 자동화할 수 있습니다.

프로젝트 루트/
├── CLAUDE.md                   ← 팀 공통 컨텍스트
├── CLAUDE.local.md             ← 개인 로컬 메모(보통 gitignore)
└── .claude/
    ├── commands/
    │   └── deploy.md           ← /deploy 커맨드
    ├── skills/
    │   └── create-experiment/
    │       └── SKILL.md        ← 재사용 가능한 작업 스킬
    └── settings.json           ← Hooks 설정

MVP에서 유용한 커스텀 커맨드/스킬 예시:

• /create-experiment: 실험 브리프 템플릿 생성 + 이벤트 스펙 초안
• /learning-report: 학습 리포트 초안 작성
• /qa-scenarios: 정상/실패 플로우 테스트 시나리오 생성
• /gtm-variants: ICP별 랜딩 카피, DM, 반론 처리 문구 생성
• /risk-gates: 에이전트 권한, PII, 롤백, 승인 지점 점검

세션 간 컨텍스트 관리

장기 MVP 개발에서는 여러 세션에 걸쳐 작업이 이어집니다. 세션 간 컨텍스트를 유지하는 전략:

1. 진행 파일(Progress File) 패턴: 매 세션 종료 시 agentic-progress.md에 현재 상태/다음 할 일을 기록
2. 커밋 단위 관리: 기능 하나가 완성될 때마다 커밋 → 새 세션에서 git log로 맥락 복원
3. /compact 활용: 컨텍스트가 80% 차면 자동 압축이 되지만, 수동으로 /compact를 실행해 핵심만 남길 수도 있음
4. /context 활용 (v2.1.74+): 컨텍스트 사용량이 큰 도구, 메모리 비대, 용량 경고를 구체적인 최적화 팁과 함께 진단합니다

Claude Code와 함께 쓰는 운영 팁

• 루트 CLAUDE.md에 핵심 컨텍스트를 두면 "읽어줘"라고 할 필요가 없습니다
• 큰 디렉터리만 별도 CLAUDE.md를 두고, 그 경로를 실제로 다룰 때 추가 규칙이 적용되게 만드세요
• 개인 실험 메모나 로컬 습관은 CLAUDE.local.md로 분리하면 팀 공통 규칙이 덜 흔들립니다
• 작업이 길어질수록 /compact로 컨텍스트 비용을 줄이는 전략이 필요합니다
• Codex와 병행한다면 AGENTS.md에도 같은 제품 약속, 금지 행동, 검증 명령을 남기세요
• 자세한 운영은 Claude Code 고급 활용: 컨텍스트 관리를 참고하세요

참고 자료

• Anthropic, Effective Harnesses for Long-Running Agents — 세션 간 컨텍스트를 유지하는 진행 파일 패턴과 초기화 에이전트 설계.
• Anthropic, Manage Claude's memory — CLAUDE.md, CLAUDE.local.md, 디렉터리별 메모 적용 범위를 설명하는 공식 문서.
• Anthropic, Claude Code Best Practices — 메모를 짧게 유지하고 반복 규칙만 남기는 운영 원칙.
• OpenAI, Codex customization — AGENTS.md, skills, MCP, 권한 설정을 계층화하는 운영 방식.