...
- 프롬프트 시스템 개요
- 시스템 프롬프트 아키텍처
- 핵심 시스템 프롬프트 구성
- 도구(Tool)별 프롬프트
- 메모리/컨텍스트 프롬프트
- Compact(요약) 프롬프트
- 코디네이터 모드 프롬프트
- 팀/스웜 프롬프트
- 컴패니언(Buddy) 프롬프트
- CLAUDE.md 메모리 파일 시스템
- 프롬프트 캐싱 전략
- 기타 보조 프롬프트
...
폴더 구조
1. 프롬프트 시스템 개요
Claude Code의 프롬프트 시스템은 단일 프롬프트가 아닌, 다층 합성(multi-layered composition) 구조이다. 최종 시스템 프롬프트는 여러 소스에서 동적으로 조합되어 API에 전달된다.
┌────────────────────────────────────────────────────────────────┐┌───────────────────────────────────────────────────────────────┐
│ 최종 시스템 프롬프트 │
├──────────────────────┬─────────────────────────────────────────┤├──────────────────────┬────────────────────────────────────────┤
│ Static 영역 │ Dynamic 영역 │
│ (전역 캐시 가능) │ (세션/턴별 재계산) │
├──────────────────────┼─────────────────────────────────────────┤├──────────────────────┼────────────────────────────────────────┤
│ Attribution Header │ 세션별 가이던스 │
│ CLI 접두사 │ MEMORY.md 콘텐츠 │
│ 역할 소개 │ 환경 정보 (CWD, OS, 모델) │
│ 보안 지침 │ 언어 설정 │
│ 시스템 규칙 │ 출력 스타일 │
│ 작업 수행 지침 │ MCP 서버 지시사항 │
│ 행동 주의사항 │ CLAUDE.md 사용자/프로젝트 컨텍스트 │
│ 도구 사용법 │ Git 상태 │
│ 톤/스타일 │ │ │
│ 출력 효율성 │ │ │
└──────────────────────┴─────────────────────────────────────────┘└──────────────────────┴────────────────────────────────────────┘
주요 소스 파일:
| 파일 | 역할 |
|---|---|
constants/prompts.ts | 메인 시스템 프롬프트 빌더. 모든 섹션의 조합 및 최종 프롬프트 생성 |
constants/systemPromptSections.ts | 프롬프트 섹션 캐싱/관리 프레임워크 |
constants/system.ts | CLI 접두사 상수 및 Attribution 헤더 |
constants/cyberRiskInstruction.ts | 보안/사이버 위험 지침 |
context.ts | 시스템/사용자 컨텍스트 (Git 상태, CLAUDE.md) |
utils/queryContext.ts | 시스템 프롬프트 파츠 조합 헬퍼 |
utils/systemPromptType.ts | SystemPrompt 브랜드 타입 |
utils/claudemd.ts | CLAUDE.md 파일 로딩/파싱 |
memdir/memdir.ts | 메모리 디렉토리 프롬프트 빌더 |
memdir/memoryTypes.ts | 메모리 타입 분류 (user/feedback/project/reference) |
services/compact/prompt.ts | Compact 요약 프롬프트 |
coordinator/coordinatorMode.ts | 코디네이터 모드 시스템 프롬프트 |
tools/*/prompt.ts | 개별 도구 설명 프롬프트 (36개 파일) |
...
2. 시스템 프롬프트 아키텍처
2.1 프롬프트 조합 흐름
...
3.1 CLI 접두사 (constants/system.ts)
세 가지 접두사가 상황에 따라 선택된다:
| 접두사 | 사용 시점 |
|---|---|
"You are Claude Code, Anthropic's official CLI for Claude." | 대화형(REPL) 모드 기본값 |
"You are Claude Code, ... running within the Claude Agent SDK." | 비대화형 + appendSystemPrompt |
"You are a Claude agent, built on Anthropic's Claude Agent SDK." | 비대화형 단독 실행 |
3.2 역할 소개 (getSimpleIntroSection)
...
메모리 4가지 유형 (memdir/memoryTypes.ts)
| 유형 | 설명 | 저장 시점 |
|---|---|---|
| user | 사용자의 역할, 목표, 선호도, 지식 수준 | 사용자 프로필 정보 학습 시 |
| feedback | "하지 마"/"이렇게 해" 행동 가이드 | 교정/확인 받을 때 |
| project | 진행 중 작업, 목표, 마감일 등 프로젝트 맥락 | git/코드에서 도출 불가한 정보 학습 시 |
| reference | 외부 시스템 위치 참조 (Linear, Slack 등) | 외부 리소스 위치를 배울 때 |
핵심 프롬프트 (memdir/memdir.ts):
...
5.2 CLAUDE.md 파일 시스템 (utils/claudemd.ts)
| 우선순위 | 유형 | 경로 |
|---|---|---|
| 1 (낮음) | Managed | /etc/claude-code/CLAUDE.md |
| 2 | User | ~/.claude/CLAUDE.md |
| 3 | Project | CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md |
| 4 (높음) | Local | CLAUDE.local.md |
주입 프롬프트:
Codebase and user instructions are shown below. Be sure to adhere
to these instructions. IMPORTANT: These instructions OVERRIDE any
default behavior and you MUST follow them exactly as written.
...
You are Claude Code, an AI assistant that orchestrates software
engineering tasks across multiple workers.
4단계 워크플로우:
| 단계 | 수행자 | 목적 |
|---|---|---|
| Research | 작업자 (병렬) | 코드베이스 조사 |
| Synthesis | 코디네이터 | 발견 종합, 구현 명세 |
| Implementation | 작업자 | 코드 변경 |
| Verification | 작업자 | 변경 검증 |
작업자 프롬프트 5원칙:
- 자기 완결적 (작업자는 코디네이터 대화를 못 봄)
- 종합(Synthesize) 필수 — "your findings에 따라" 금지
- 목적 서술 포함
- Continue vs. Spawn을 컨텍스트 겹침으로 판단
- "Done" 정의 명시
...
/init 명령어 (commands/init.ts)
인터뷰 기반 5단계:
| 단계 | 내용 |
|---|---|
| Phase 1 | 설정 범위 확인 (Project/Personal/Both, Skills+Hooks 여부) |
| Phase 2 | 코드베이스 탐색 (매니페스트, README, CI, 기존 규칙) |
| Phase 3 | 빈 정보 인터뷰 |
| Phase 4 | CLAUDE.md 작성 ("이 줄 제거 시 Claude가 실수할까?" 테스트) |
| Phase 5 | 스킬/훅 생성 |
로드 순서
1. /etc/claude-code/CLAUDE.md (Managed — 낮은 우선순위)
2. ~/.claude/CLAUDE.md (User)
3. 프로젝트 루트 → CWD까지 각 디렉토리:
├─ CLAUDE.md (Project)
├─ .claude/CLAUDE.md (Project)
├─ .claude/rules/*.md (Project)
└─ CLAUDE.local.md (Local — 높은 우선순위)
...