Claude Code 시스템 프롬프트

Claude Code의 내부 프롬프트 아키텍처와 에이전트 동작 방식을 문서화한 독립 연구 프로젝트입니다. Claude Code는 Anthropic의 AI 기반 소프트웨어 엔지니어링 어시스턴트입니다.

이 문서는 동작 분석, 출력 관찰, 공개 토론 자료 조사를 바탕으로 작성되었습니다. 현대의 에이전트형 AI 코딩 어시스턴트가 어떻게 설계되는지 이해하기 위한 교육 자료로 활용할 수 있습니다.

개요

Claude Code는 정교한 다층 프롬프트 아키텍처를 사용합니다. 메인 시스템 프롬프트는 고정 문자열이 아니라, 모듈식 섹션 빌더(section-builder) 함수들을 통해 런타임에 동적으로 조립됩니다. 경계 마커가 전역 캐시 가능한 접두부(prefix)와 세션별 접미부(suffix)를 구분해 주며, 이를 통해 API 호출 전반에서 프롬프트 캐싱이 가능합니다.

핵심 정체성 프롬프트 외에도, 이 시스템에는 특수 에이전트 프롬프트, 멀티 워커 조정자(coordinator), Tool 호출 자동 승인을 위한 2단계 보안 분류기, 그리고 메모리 선택, 세션 검색, Tool 사용 요약을 위한 각종 유틸리티 프롬프트가 포함됩니다.

프롬프트 카탈로그

핵심 정체성

오케스트레이션

특수 에이전트

보안 및 권한

Tool 관련 설명

유틸리티 및 헬퍼

컨텍스트 윈도 관리

동적 섹션

번들 스킬

아키텍처

프롬프트 조립

메인 시스템 프롬프트는 섹션 빌더(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

Auto Mode 분류기

자동 승인 시스템은 아래 요소로 조립되는 별도의 분류기(classifier) 프롬프트를 사용합니다.

1. 기본 프롬프트(Base prompt): 분류기 지침 포함
2. 기본 규칙(Default rules): allow, deny, environment 섹션 포함
3. 사용자 재정의(User overrides): 각 섹션 전체를 대체
4. 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-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과 어떠한 방식으로도 제휴, 승인, 연관되어 있지 않습니다. 모든 상표는 각 소유자에게 귀속됩니다.