claude-code-source-study
Deep dive into Claude Code's source code to learn AI agent implementation patterns, system prompt engineering, and production-grade AI coding assistant architecture
How do I install this agent skill?
npx skills add https://github.com/reason-machines/claude-code-skills --skill claude-code-source-studyIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is an educational resource providing documentation and design patterns based on a study of Claude Code's source code. It contains no executable code, tool invocations, or malicious instructions.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Claude Code Source Study
Skill by ara.so — Claude Code Skills collection.
This skill provides expertise in understanding and applying architectural patterns from Claude Code's source code — Anthropic's production-grade AI coding assistant. The project contains ~1,900 files covering system prompt engineering, multi-agent orchestration, tool systems, security, and terminal UI.
What This Project Is
Claude Code Source Study (luyao618/Claude-Code-Source-Study) is a comprehensive 25-article source code analysis of Claude Code, covering:
- Global Architecture: Startup optimization, state management, module structure
- AI Core: System prompt engineering, conversation loops, context management, prompt caching
- Tool & Agent Systems: Tool builder patterns, bash execution safety, multi-agent coordination
- Security & Engineering: Permission systems, settings architecture, feature flags, error recovery
- Terminal UI: Custom Ink framework, design system, memory architecture
Repository Structure
claude-code-source-study/
├── docs/
│ ├── 00-目录与阅读指引.md # Reading guide
│ ├── 01-项目全景.md # Project overview
│ ├── 02-启动优化.md # Startup optimization
│ ├── 03-状态管理.md # State management
│ ├── 04-System-Prompt-工程.md # System prompt engineering
│ ├── 05-对话循环.md # Conversation loop
│ ├── 06-上下文管理.md # Context management
│ ├── 07-Prompt-Cache.md # Prompt caching
│ ├── 08-Thinking-与推理控制.md # Thinking & reasoning control
│ ├── 09-工具系统设计.md # Tool system design
│ ├── 10-BashTool-深度剖析.md # BashTool deep dive
│ ├── 11-命令系统.md # Command system
│ ├── 12-Agent-系统.md # Agent system
│ ├── 13-内置Agent设计模式.md # Built-in agent patterns
│ ├── 14-任务系统.md # Task system
│ ├── 15-MCP-协议实现.md # MCP protocol implementation
│ ├── 16-权限系统.md # Permission system
│ ├── 17-Settings-系统.md # Settings system
│ ├── 18-Hooks系统.md # Hooks system
│ ├── 19-Feature-Flag与编译期优化.md # Feature flags & compile-time optimization
│ ├── 20-API调用与错误恢复.md # API calls & error recovery
│ ├── 21-Ink框架深度定制.md # Ink framework customization
│ ├── 22-设计系统.md # Design system
│ ├── 23-Memory系统.md # Memory system
│ ├── 24-Skill-Plugin开发实战.md # Skill/plugin development
│ └── 25-架构模式总结.md # Architecture patterns summary
└── README.md
Key Learning Paths
Quick Start Path (7 articles)
For rapid global understanding:
- Project Overview (01)
- Startup Optimization (02)
- State Management (03)
- Conversation Loop (05)
- Tool System Design (09)
- Agent System (12)
- Architecture Patterns Summary (25)
AI Engineering Path (9 articles)
For deep AI architecture understanding:
- Project Overview (01)
- State Management (03)
- System Prompt Engineering (04)
- Conversation Loop (05)
- Context Management (06)
- Thinking & Reasoning Control (08)
- Tool System Design (09)
- Agent System (12)
- Built-in Agent Patterns (13)
Complete Path (25 articles)
Read sequentially for comprehensive understanding.
Core Design Patterns
1. System Prompt Engineering
Pattern: Segmented construction with cache boundaries
// System prompt built in segments for optimal caching
const systemPrompt = [
// Static instructions (cacheable)
baseInstructions,
// Tool schemas (cacheable if tools unchanged)
toolSchemas,
// Dynamic context (not cached)
currentProjectContext,
userPreferences
].join('\n\n');
// Cache control headers
const cacheBreakpoints = {
ephemeral: 'static_instructions_end',
persistent: 'tool_schemas_end'
};
Key Learnings:
- Separate static from dynamic content
- Place frequently-changing content last
- Use explicit cache boundary markers
- Balance cache hit rate vs. context freshness
2. Conversation State Machine
Pattern: AsyncGenerator-driven conversation loop
async function* conversationLoop(
messages: Message[],
config: ConversationConfig
): AsyncGenerator<ConversationState> {
let state: ConversationState = { phase: 'thinking' };
while (true) {
yield state;
switch (state.phase) {
case 'thinking':
const thinking = await generateThinking(messages);
state = { phase: 'responding', thinking };
break;
case 'responding':
const response = await generateResponse(messages, state.thinking);
if (response.toolCalls) {
state = { phase: 'tool_execution', toolCalls: response.toolCalls };
} else {
state = { phase: 'complete', response };
}
break;
case 'tool_execution':
const results = await executeTools(state.toolCalls);
messages.push(...results);
state = { phase: 'thinking' };
break;
case 'complete':
return;
}
}
}
Key Learnings:
- AsyncGenerator provides natural state streaming
- Each yield enables UI updates
- Tool execution results feed back into conversation
- Clear state transitions prevent deadlocks
3. Tool Builder Pattern
Pattern: Fluent API for tool registration with conditional activation
interface ToolBuilder {
buildTool(name: string): {
description: (desc: string) => ToolBuilder;
parameters: (schema: JSONSchema) => ToolBuilder;
handler: (fn: ToolHandler) => ToolBuilder;
condition: (predicate: () => boolean) => ToolBuilder;
permission: (level: PermissionLevel) => ToolBuilder;
build: () => Tool;
};
}
// Usage
const readFileTool = buildTool('read_file')
.description('Read contents of a file')
.parameters({
type: 'object',
properties: {
path: { type: 'string', description: 'File path' }
},
required: ['path']
})
.handler(async ({ path }) => {
return await fs.readFile(path, 'utf-8');
})
.condition(() => !isInRestrictedMode())
.permission('read')
.build();
Key Learnings:
- Three-layer registration: builder → registry → runtime
- Conditions evaluated at registration time
- Permissions checked at execution time
- Type-safe parameter schemas
4. Context Budget Management
Pattern: Token-aware context window with auto-compaction
interface ContextManager {
budget: {
total: number; // e.g., 200k tokens
system: number; // ~5k for system prompt
tools: number; // ~10k for tool schemas
history: number; // Remaining for conversation
};
async addMessage(msg: Message): Promise<void> {
const tokens = await this.countTokens(msg);
if (this.currentUsage + tokens > this.budget.history) {
await this.compact();
}
this.messages.push(msg);
this.currentUsage += tokens;
}
async compact(): Promise<void> {
// Strategy 1: Remove old tool results (keep latest)
this.messages = this.messages.filter((m, i) => {
if (m.role === 'tool') {
return i >= this.messages.length - 10;
}
return true;
});
// Strategy 2: Summarize middle conversation
const [start, middle, end] = this.partition(this.messages);
const summary = await this.summarize(middle);
this.messages = [...start, summary, ...end];
this.currentUsage = await this.countTokens(this.messages);
}
}
Key Learnings:
- Pre-allocate token budget by category
- Prioritize recent context over old
- Multi-strategy compaction (remove, summarize, truncate)
- Always preserve system prompt and tool schemas
5. Multi-Agent Orchestration
Pattern: Context-isolated agent delegation
interface Agent {
name: string;
systemPrompt: string;
availableTools: Tool[];
conversationLoop: ConversationLoop;
}
class AgentOrchestrator {
private agents: Map<string, Agent> = new Map();
async delegateTask(
taskType: string,
context: TaskContext,
parentConversation: Message[]
): Promise<AgentResult> {
const agent = this.selectAgent(taskType);
// Create isolated context
const agentContext = {
goal: context.goal,
relevantFiles: context.files,
constraints: context.constraints,
// Do NOT pass full parent conversation
};
const agentMessages = [
{ role: 'user', content: this.formatTaskPrompt(agentContext) }
];
const result = await agent.conversationLoop(agentMessages);
// Merge result back to parent
return this.mergeResult(result, parentConversation);
}
selectAgent(taskType: string): Agent {
const agentMap = {
'explore': this.agents.get('explorer'),
'plan': this.agents.get('planner'),
'verify': this.agents.get('verifier'),
'execute': this.agents.get('executor')
};
return agentMap[taskType] || this.agents.get('default');
}
}
Key Learnings:
- Each agent has isolated conversation context
- Parent conversation not leaked to child agents
- Task-specific agent selection
- Results merged back, not entire conversation
6. Permission System
Pattern: Seven-mode permission model with decision pipeline
type PermissionMode =
| 'auto' // No prompts, auto-approve
| 'confirm' // Prompt for each action
| 'reject' // Auto-reject
| 'readonly' // Only allow read operations
| 'custom' // User-defined rules
| 'trust_verified'// Auto-approve verified operations
| 'sandbox'; // Execute in isolated environment
interface PermissionDecision {
allowed: boolean;
reason?: string;
modified?: ToolCall; // Modified version with restricted params
}
class PermissionManager {
async checkPermission(
toolCall: ToolCall,
context: ExecutionContext
): Promise<PermissionDecision> {
// 7-step decision pipeline
// 1. Global mode check
if (this.mode === 'auto') return { allowed: true };
if (this.mode === 'reject') return { allowed: false };
// 2. Tool-level permission
const toolPerm = this.getToolPermission(toolCall.name);
if (toolPerm === 'blocked') {
return { allowed: false, reason: 'Tool blocked by policy' };
}
// 3. Readonly mode check
if (this.mode === 'readonly' && !toolPerm.isReadOnly) {
return { allowed: false, reason: 'Write operation in readonly mode' };
}
// 4. Path restriction check
if (!this.isPathAllowed(toolCall.arguments.path)) {
return { allowed: false, reason: 'Path outside allowed directories' };
}
// 5. Resource limit check
if (await this.exceedsResourceLimit(toolCall)) {
return { allowed: false, reason: 'Resource limit exceeded' };
}
// 6. Custom rule evaluation
for (const rule of this.customRules) {
const decision = await rule.evaluate(toolCall, context);
if (!decision.allowed) return decision;
}
// 7. User confirmation (if mode === 'confirm')
if (this.mode === 'confirm') {
const approved = await this.promptUser(toolCall);
return { allowed: approved };
}
return { allowed: true };
}
}
Key Learnings:
- Layered decision-making (global → tool → resource → custom)
- Fail-closed by default
- Each layer can short-circuit
- Support for parameter modification (e.g., restrict file paths)
7. Feature Flag with Dead Code Elimination
Pattern: Compile-time feature toggling
// feature.ts
export function feature(flag: string): boolean {
const COMPILE_TIME_FLAGS = {
'mcp_support': process.env.BUILD_TARGET !== 'minimal',
'analytics': process.env.BUILD_TARGET === 'enterprise',
'cloud_sync': process.env.ENABLE_CLOUD === 'true'
};
return COMPILE_TIME_FLAGS[flag] ?? false;
}
// Usage (DCE-optimized)
if (feature('mcp_support')) {
// This entire block removed if BUILD_TARGET=minimal
import('./mcp-client').then(mcp => {
mcp.initialize();
});
}
// Build script
{
"scripts": {
"build:minimal": "BUILD_TARGET=minimal bun build",
"build:full": "BUILD_TARGET=full bun build",
"build:enterprise": "BUILD_TARGET=enterprise ENABLE_CLOUD=true bun build"
}
}
Key Learnings:
- Single codebase, multiple build outputs
- Dead code eliminated at bundle time
- Feature flags as environment variables
- Conditional imports for chunk splitting
Common Patterns & Idioms
AsyncGenerator for Streaming State
// Producer
async function* processWithProgress() {
yield { status: 'starting' };
const result = await heavyComputation();
yield { status: 'processing', progress: 0.5 };
await saveResult(result);
yield { status: 'complete', data: result };
}
// Consumer
for await (const state of processWithProgress()) {
updateUI(state);
}
Store Pattern for React + Non-React
class Store<T> {
private state: T;
private listeners = new Set<(state: T) => void>();
getState(): T {
return this.state;
}
setState(partial: Partial<T>): void {
this.state = { ...this.state, ...partial };
this.listeners.forEach(fn => fn(this.state));
}
subscribe(fn: (state: T) => void): () => void {
this.listeners.add(fn);
return () => this.listeners.delete(fn);
}
}
// React hook
function useStore<T>(store: Store<T>): T {
const [state, setState] = useState(store.getState());
useEffect(() => {
return store.subscribe(setState);
}, [store]);
return state;
}
Retry with Exponential Backoff
async function withRetry<T>(
fn: () => Promise<T>,
options: RetryOptions = {}
): Promise<T> {
const { maxAttempts = 3, backoff = 'exponential', baseDelay = 1000 } = options;
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
return await fn();
} catch (error) {
if (attempt === maxAttempts) throw error;
const delay = backoff === 'exponential'
? baseDelay * Math.pow(2, attempt - 1)
: baseDelay;
await new Promise(resolve => setTimeout(resolve, delay));
}
}
throw new Error('Retry failed');
}
Configuration Examples
System Prompt Configuration
// System prompt with cache boundaries
const systemPromptConfig = {
segments: [
{
name: 'base_instructions',
cacheable: true,
cacheType: 'persistent',
content: `You are Claude Code, an AI coding assistant...`
},
{
name: 'tool_schemas',
cacheable: true,
cacheType: 'ephemeral',
content: JSON.stringify(toolSchemas)
},
{
name: 'project_context',
cacheable: false,
content: () => getCurrentProjectContext()
}
]
};
Agent Configuration
// Multi-agent setup
const agentConfig = {
agents: [
{
name: 'explorer',
systemPrompt: 'You explore codebases and understand structure...',
tools: ['read_file', 'list_directory', 'search_files'],
maxTokens: 50000
},
{
name: 'planner',
systemPrompt: 'You create detailed implementation plans...',
tools: ['read_file', 'analyze_dependencies'],
maxTokens: 30000
},
{
name: 'executor',
systemPrompt: 'You write and modify code...',
tools: ['read_file', 'write_file', 'bash'],
maxTokens: 100000
}
],
orchestration: {
delegation_threshold: 'complex_task',
context_isolation: true,
result_merge_strategy: 'summary'
}
};
Permission Configuration
// Permission rules
const permissionConfig = {
mode: 'confirm',
rules: {
read_file: {
allowed_paths: ['./src/**', './docs/**'],
denied_paths: ['.env', '**/*.key', '**/*.pem'],
auto_approve: true
},
write_file: {
allowed_paths: ['./src/**'],
denied_paths: ['./src/config/**'],
requires_confirmation: true
},
bash: {
allowed_commands: ['npm', 'git', 'ls', 'cat'],
denied_patterns: ['rm -rf', 'sudo', '> /dev/'],
sandbox: true
}
},
resource_limits: {
max_file_size: '10MB',
max_bash_runtime: 30000, // ms
max_concurrent_operations: 5
}
};
Troubleshooting
Context Window Overflow
Problem: "Context window exceeded" errors
Solution: Implement aggressive compaction
// Increase compaction aggressiveness
contextManager.setCompactionStrategy({
trigger_threshold: 0.7, // Compact at 70% capacity
keep_recent_messages: 20,
summarize_threshold: 50, // Summarize if >50 messages
remove_tool_results: 'keep_latest_10'
});
Slow Agent Responses
Problem: Multi-agent delegation causes delays
Solution: Use parallel execution where possible
// Execute independent agents in parallel
const [exploreResult, analyzeResult] = await Promise.all([
orchestrator.delegateTask('explore', context),
orchestrator.delegateTask('analyze', context)
]);
Cache Miss Rate High
Problem: Poor prompt cache hit rate
Solution: Reorder prompt segments
// Place stable content first
const optimizedPrompt = [
staticInstructions, // Rarely changes
toolSchemas, // Changes when tools added
projectContext, // Changes per project
conversationHistory // Always changes
];
Permission Deadlocks
Problem: Agent stuck waiting for user confirmation
Solution: Implement timeout-based defaults
permissionManager.setConfirmationTimeout({
timeout: 30000, // 30 seconds
default_action: 'deny', // Or 'allow' for trusted environments
show_notification: true
});
References
- Main Repository: https://github.com/luyao618/Claude-Code-Source-Study
- Reading Guide: See
docs/00-目录与阅读指引.md - Architecture Summary: See
docs/25-架构模式总结.md - Key Learnings: Each article ends with 2-3 transferable design patterns
Learning Recommendations
- For AI Engineers: Focus on articles 04-08 (AI core) and 12-13 (agents)
- For Tool Builders: Study articles 09-11 (tools & commands)
- For Security-Focused: Read articles 16-18 (permissions, settings, hooks)
- For Full-Stack: Complete all 25 articles sequentially
This is a study resource, not executable code. The patterns and architectures documented here are extracted from Claude Code's source and can be applied to your own AI agent projects.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/claude-code-skills/claude-code-source-study">View claude-code-source-study on skillZs</a>