lucas-flatwhite/claude-code-system-prompts

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)
...

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

기본 프롬프트(Base prompt): 분류기 지침 포함
기본 규칙(Default rules): allow, deny, environment 섹션 포함
사용자 재정의(User overrides): 각 섹션 전체를 대체
2단계 분류(2-stage classification): Stage 1은 빠르게 실행되고, 불확실하면 Stage 2가 확장 추론을 사용

User Message
|
v
...

Memory Loading Order (first loaded = lowest priority):
|
|-- Enterprise managed config
...

| 변수 |
효과 |
CLAUDE_CODE_SIMPLE |
최소 4줄 시스템 프롬프트를 활성화 |
USER_TYPE=ant |
내부 전용 섹션과 모델 재정의를 활성화 |
| Feature flags |
Proactive mode, verification agent, fork subagent 등을 제어 |

claude-code-system-prompts/
README.md
prompts/
...

이 프로젝트는 AI 연구자, 에이전트형 시스템을 구축하는 개발자, 그리고 프로덕션급 (production-grade) AI 코딩 어시스턴트의 설계 패턴을 이해하고자 하는 모든 사람을 위한 교육 자료입니다.

여기서 문서화한 패턴은 더 넓은 AI 엔지니어링 (AI engineering) 커뮤니티와 관련된 다음 주제를 다룹니다.

• 멀티 에이전트 오케스트레이션 (Multi-agent orchestration) 및 조정
• 자율 도구 (Tool) 사용을 위한 보안 분류 체계
• 컨텍스트 윈도 (Context window) 관리와 대화 압축
• 계층적 재정의 의미 체계를 갖춘 메모리 시스템
• 지연 시간 (Latency) 최적화를 위한 프롬프트 캐싱 (Prompt caching) 전략

이 프로젝트는 독립 연구 프로젝트입니다. 내용은 Claude Code의 동작과 아키텍처 (Architecture)에 대한 분석 및 관찰을 바탕으로 합니다. 이 프로젝트는 Anthropic과 어떠한 방식으로도 제휴, 승인, 연관되어 있지 않습니다. 모든 상표는 각 소유자에게 귀속됩니다.