Claude Code의 내부 프롬프트 아키텍처와 에이전트 동작 방식을 문서화한 독립 연구 프로젝트입니다. Claude Code는 Anthropic의 AI 기반 소프트웨어 엔지니어링 어시스턴트입니다.
이 문서는 동작 분석, 출력 관찰, 공개 토론 자료 조사를 바탕으로 작성되었습니다. 현대의 에이전트형 AI 코딩 어시스턴트가 어떻게 설계되는지 이해하기 위한 교육 자료로 활용할 수 있습니다.
Claude Code는 정교한 다층 프롬프트 아키텍처를 사용합니다. 메인 시스템 프롬프트는 고정 문자열이 아니라, 모듈식 섹션 빌더(section-builder) 함수들을 통해 런타임에 동적으로 조립됩니다. 경계 마커가 전역 캐시 가능한 접두부(prefix)와 세션별 접미부(suffix)를 구분해 주며, 이를 통해 API 호출 전반에서 프롬프트 캐싱이 가능합니다.
핵심 정체성 프롬프트 외에도, 이 시스템에는 특수 에이전트 프롬프트, 멀티 워커 조정자(coordinator), Tool 호출 자동 승인을 위한 2단계 보안 분류기, 그리고 메모리 선택, 세션 검색, Tool 사용 요약을 위한 각종 유틸리티 프롬프트가 포함됩니다.
| # |
프롬프트 |
설명 |
| 13 |
Tool별 프롬프트 |
Bash, Edit, Agent, fork 동작 의미를 포함한 30개 이상의 Tool 설명 |
| # |
프롬프트 |
설명 |
| 14 |
Tool 사용 요약 |
완료된 Tool 배치에 대해 git commit 스타일 라벨을 생성 |
| 15 |
세션 검색 |
지난 대화 세션 전반에 대한 시맨틱 검색 |
| 16 |
메모리 선택 |
현재 질의 컨텍스트에 맞는 관련 메모리 파일을 선택 |
| 17 |
Auto Mode 비평 |
사용자가 작성한 auto-mode 분류기 규칙을 검토 |
| 20 |
세션 제목 |
Haiku 기반 3~7단어 세션 제목 생성기 |
| 29 |
에이전트 요약 |
조정자(coordinator) 모드에서 서브 에이전트의 진행 상황을 주기적으로 갱신 |
| 30 |
프롬프트 제안 |
클릭 가능한 제안을 위해 사용자의 후속 명령을 예측 |
| # |
프롬프트 |
설명 |
| 18 |
Proactive Mode |
tick 기반 간격 조절과 터미널 포커스 인식을 갖춘 자율 에이전트 |
| 23 |
Chrome 브라우저 자동화 |
브라우저 확장 통합: GIF 녹화, 탭 관리, 대화상자 처리 |
| 24 |
메모리 지침 |
CLAUDE.md 로딩, @include 지시어, 프론트매터(frontmatter) glob 처리 |
메인 시스템 프롬프트는 섹션 빌더(section-builder) 파이프라인을 통해 구성됩니다.
System Prompt Assembly
|
| Static Prefix (globally cached)
|-- Identity and Cyber Risk
|-- Permission modes, hooks, reminders
|-- Code style, security, error handling
|-- Reversibility, blast radius
|-- Tool preferences, parallel calls
|-- Tone and style rules
|-- Output efficiency patterns
|
| CACHE BOUNDARY
|
| Dynamic Suffix (session-specific)
|-- Agent tools, skills, verification
|-- Memory file content
|-- Model overrides
|-- Environment info (CWD, OS, git state)
|-- Language preferences
|-- Custom output styles
|-- MCP server instructions
|-- Context window management
자동 승인 시스템은 아래 요소로 조립되는 별도의 분류기(classifier) 프롬프트를 사용합니다.
- 기본 프롬프트(Base prompt): 분류기 지침 포함
- 기본 규칙(Default rules):
allow, deny, environment 섹션 포함
- 사용자 재정의(User overrides): 각 섹션 전체를 대체
- 2단계 분류(2-stage classification): Stage 1은 빠르게 실행되고, 불확실하면 Stage 2가 확장 추론을 사용
User Message
|
v
[Micro-Compaction] -- Cache-aware tool result deletion
|
v
[Compact Service] -- Full/partial summarization
|
v
[Prompt Suggestion] -- Predict next user command
|
v
[Away Summary] -- Session recap if user was idle
Memory Loading Order (first loaded = lowest priority):
|
|-- Enterprise managed config
|-- User global config
|-- Project config (shared, checked in)
|-- Project rules directory
|-- Local config (private, git-ignored)
|
| @include directives resolve transitively (max depth: 5)
| Frontmatter paths field enables conditional injection
| 변수 |
효과 |
CLAUDE_CODE_SIMPLE |
최소 4줄 시스템 프롬프트를 활성화 |
USER_TYPE=ant |
내부 전용 섹션과 모델 재정의를 활성화 |
| Feature flags |
Proactive mode, verification agent, fork subagent 등을 제어 |
claude-code-system-prompts/
README.md
prompts/
01_main_system_prompt.md 19_simplify_skill.md
02_simple_mode.md 20_session_title.md
03_default_agent_prompt.md 21_compact_service.md
04_cyber_risk_instruction.md 22_away_summary.md
05_coordinator_system_prompt.md 23_chrome_browser_automation.md
06_teammate_prompt_addendum.md 24_memory_instruction.md
07_verification_agent.md 25_skillify.md
08_explore_agent.md 26_stuck_skill.md
09_agent_creation_architect.md 27_remember_skill.md
10_statusline_setup_agent.md 28_update_config_skill.md
11_permission_explainer.md 29_agent_summary.md
12_yolo_auto_mode_classifier.md 30_prompt_suggestion.md
13_tool_prompts.md
14_tool_use_summary.md
15_session_search.md
16_memory_selection.md
17_auto_mode_critique.md
18_proactive_mode.md
이 프로젝트는 AI 연구자, 에이전트형 시스템을 구축하는 개발자, 그리고 프로덕션급 AI 코딩 어시스턴트의 설계 패턴을 이해하고자 하는 모든 사람을 위한 교육 자료입니다.
여기서 문서화한 패턴은 더 넓은 AI 엔지니어링 커뮤니티와 관련된 다음 주제를 다룹니다.
- 멀티 에이전트 오케스트레이션과 조정
- 자율 Tool 사용을 위한 보안 분류 체계
- 컨텍스트 윈도 관리와 대화 압축
- 계층적 재정의 의미 체계를 갖춘 메모리 시스템
- 지연 시간 최적화를 위한 프롬프트 캐싱 전략
이 프로젝트는 독립 연구 프로젝트입니다. 내용은 Claude Code의 동작과 아키텍처에 대한 분석 및 관찰을 바탕으로 합니다. 이 프로젝트는 Anthropic과 어떠한 방식으로도 제휴, 승인, 연관되어 있지 않습니다. 모든 상표는 각 소유자에게 귀속됩니다.