메뉴
Analyze and apply architectural patterns from Claude Code's system design for building AI agent systems
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/Aradotso/claude-code-skills --skill dive-into-claude-code-analysis명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | dive-into-claude-code-analysis |
| description | Analyze and apply architectural patterns from Claude Code's system design for building AI agent systems |
| triggers | ["how does Claude Code architecture work","show me Claude Code design patterns","apply Claude Code safety principles","implement agent loop like Claude Code","use Claude Code permission system design","analyze AI agent architecture patterns","design agent system with Claude Code principles","implement defense in depth for AI agents"] |
Skill by ara.so — Claude Code Skills collection.
This skill provides expertise in understanding and applying the architectural patterns, design principles, and implementation strategies documented in the VILA-Lab "Dive into Claude Code" analysis — a comprehensive study of Claude Code v2.1.88 (~512K lines of TypeScript across 1,884 files).
The Dive into Claude Code project is a systematic analysis that reveals:
# Clone the repository
git clone https://github.com/VILA-Lab/Dive-into-Claude-Code.git
cd Dive-into-Claude-Code
# Read the paper (PDF in repo or arXiv)
open paper/Dive_into_Claude_Code.pdf
# or visit https://arxiv.org/abs/2604.14228
Claude Code demonstrates that production AI agents are primarily infrastructure:
Key insight: The agent loop is a simple while-loop. The engineering complexity lives in the systems around it.
┌─────────────────────────────────────────┐
│ User & Interfaces (CLI, SDK, IDE) │
├─────────────────────────────────────────┤
│ Agent Loop (queryLoop) │
│ • Context Assembly │
│ • Model Invocation │
│ • Tool Dispatch │
├─────────────────────────────────────────┤
│ Permission System (7 modes, deny-first) │
├─────────────────────────────────────────┤
│ Tools & Extensions (54 base + MCP) │
├─────────────────────────────────────────┤
│ State & Execution Environment │
└─────────────────────────────────────────┘
// Values that drive all architectural decisions
enum CoreValue {
HumanDecisionAuthority = "human-control",
SafetySecurityPrivacy = "safe-by-default",
ReliableExecution = "does-what-meant",
CapabilityAmplification = "unix-utility-philosophy",
ContextualAdaptability = "evolves-with-trust"
}
Apply these when designing your AI agent:
async function* agentLoop(
initialPrompt: string,
context: AgentContext,
permissions: PermissionSystem
): AsyncGenerator<AgentEvent> {
let turnCount = 0;
const MAX_TURNS = 25;
const conversationHistory: Message[] = [];
while (turnCount < MAX_TURNS) {
// 1. Context assembly
const assembledContext = await assembleContext(
conversationHistory,
context.workspaceState,
context.availableTools
);
// 2. Five-stage compaction (if needed)
const compactedContext = await compactIfNeeded(
assembledContext,
context.tokenBudget
);
// 3. Model invocation
const modelResponse = await callModel({
messages: compactedContext.messages,
tools: compactedContext.availableTools,
streaming: true
});
// 4. Tool dispatch
const toolCalls = extractToolCalls(modelResponse);
if (toolCalls.length === 0) {
yield { type: 'complete', message: modelResponse.content };
break;
}
// 5. Permission gate
const authorizedCalls = await permissions.authorize(toolCalls);
// 6. Execute with streaming
for await (const toolResult of executeTools(authorizedCalls)) {
yield { type: 'tool_result', data: toolResult };
conversationHistory.push({
role: 'tool',
content: toolResult.output
});
}
turnCount++;
}
}
// Run sequentially, cheapest-first
async function compactIfNeeded(
context: AssembledContext,
tokenBudget: number
): Promise<CompactedContext> {
let current = context;
const currentTokens = estimateTokens(current);
if (currentTokens <= tokenBudget) {
return current;
}
// Stage 1: Budget Reduction (remove low-priority items)
current = await budgetReduction(current, tokenBudget);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 2: Snip (truncate long individual messages)
current = await snipLongMessages(current, tokenBudget);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 3: Microcompact (remove whitespace, comments)
current = await microcompact(current);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 4: Context Collapse (merge related messages)
current = await contextCollapse(current);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 5: Auto-Compact (LLM-based summarization)
current = await autoCompact(current, tokenBudget);
return current;
}
enum PermissionMode {
Plan = "plan", // Show what would happen, no execution
Default = "default", // Ask for every action
AcceptEdits = "acceptEdits", // Auto-approve file edits only
Auto = "auto", // ML classifier decides
DontAsk = "dontAsk", // Auto-approve in current directory
BypassPermissions = "bypassPermissions", // Trust completely
Bubble = "bubble" // Internal: defer to parent
}
interface PermissionRule {
scope: 'global' | 'directory' | 'file';
pattern: string;
decision: 'allow' | 'deny' | 'ask';
priority: number;
}
class DenyFirstPermissionSystem {
async authorize(toolCalls: ToolCall[]): Promise<ToolCall[]> {
const authorized: ToolCall[] = [];
for (const call of toolCalls) {
// 1. Pre-filtering: strip denied tools entirely
if (this.isDeniedTool(call.tool)) {
continue;
}
// 2. Evaluate rules (deny-first: broadest deny wins)
const decision = this.evaluateRules(call);
if (decision === 'deny') {
continue;
}
if (decision === 'ask') {
const userApproved = await this.promptUser(call);
if (!userApproved) continue;
}
// 3. Execute hooks (can still block)
const hookResult = await this.runPreToolUseHooks(call);
if (hookResult.blocked) {
continue;
}
authorized.push(call);
}
return authorized;
}
private evaluateRules(call: ToolCall): 'allow' | 'deny' | 'ask' {
const matchingRules = this.rules
.filter(rule => this.matches(rule, call))
.sort((a, b) => b.priority - a.priority);
// Deny-first: any deny rule wins
const denyRule = matchingRules.find(r => r.decision === 'deny');
if (denyRule) return 'deny';
const allowRule = matchingRules.find(r => r.decision === 'allow');
if (allowRule) return 'allow';
return 'ask'; // Default: escalate to human
}
}
class DefenseInDepth {
async executeTool(call: ToolCall, context: ExecutionContext): Promise<ToolResult> {
// Layer 1: Tool pre-filtering (denied tools removed from tool pool)
// (already applied during context assembly)
// Layer 2: PreToolUse hooks
await this.runHooks('PreToolUse', call);
// Layer 3: Deny-first rule evaluation
const permissionDecision = await this.permissions.authorize([call]);
if (permissionDecision.length === 0) {
throw new Error('Permission denied');
}
// Layer 4: Auto-mode classifier (if in auto mode)
if (context.mode === PermissionMode.Auto) {
const classifierResult = await this.classifier.evaluate(call);
if (!classifierResult.safe) {
const userOverride = await this.promptUser(call);
if (!userOverride) throw new Error('Classifier rejected');
}
}
// Layer 5: Reversibility assessment
const risk = this.assessReversibility(call);
if (risk === 'irreversible' && !call.userApproved) {
throw new Error('Irreversible action requires explicit approval');
}
// Layer 6: Resource limits (timeout, memory, file size)
const result = await this.executeWithLimits(call, {
timeout: 30000,
maxMemory: 512 * 1024 * 1024,
maxFileSize: 10 * 1024 * 1024
});
// Layer 7: PostToolUse hooks (can still intervene)
await this.runHooks('PostToolUse', call, result);
return result;
}
}
// Cost spectrum: Hooks < Skills < Plugins < MCP
// 1. HOOKS (zero context cost)
interface Hook {
event: HookEvent; // 27 available events
handler: string | Function;
blocking?: boolean;
}
// Example: PreToolUse hook
const securityHook: Hook = {
event: 'PreToolUse',
handler: async (call: ToolCall) => {
if (call.tool === 'execute_command' && call.args.command.includes('rm -rf')) {
return { allow: false, reason: 'Dangerous command blocked' };
}
},
blocking: true
};
// 2. SKILLS (low context cost - injected only when triggered)
interface Skill {
name: string;
description: string;
triggers: string[];
content: string; // Markdown with examples
}
// 3. PLUGINS (medium cost - loaded at startup)
interface PluginManifest {
name: string;
components: {
commands?: CommandDefinition[];
agents?: AgentDefinition[];
skills?: Skill[];
hooks?: Hook[];
mcpServers?: MCPServerConfig[];
settings?: Setting[];
};
}
// 4. MCP (high cost - persistent tool pool expansion)
interface MCPServerConfig {
name: string;
command: string;
args?: string[];
env?: Record<string, string>;
}
async function assembleToolPool(context: AgentContext): Promise<Tool[]> {
// Step 1: Base enumeration (up to 54 tools)
let tools = [...BASE_TOOLS];
// Step 2: Mode filtering (e.g., plan mode removes write tools)
tools = filterByMode(tools, context.mode);
// Step 3: Deny pre-filtering (remove denied tools)
tools = tools.filter(tool => !isDenied(tool, context.permissions));
// Step 4: MCP integration (add external tools)
const mcpTools = await loadMCPTools(context.mcpServers);
tools.push(...mcpTools);
// Step 5: Deduplication (by tool name)
tools = deduplicateTools(tools);
return tools;
}
interface SessionState {
id: string;
createdAt: number;
events: SessionEvent[]; // Append-only
metadata: {
workspaceRoot: string;
permissionMode: PermissionMode;
trustLevel: number;
};
}
class SessionPersistence {
// Never mutate history - only append
async appendEvent(sessionId: string, event: SessionEvent): Promise<void> {
const session = await this.loadSession(sessionId);
session.events.push({
...event,
timestamp: Date.now(),
sequenceNumber: session.events.length
});
await this.saveSession(session);
}
// Replay from events for recovery
async replaySession(sessionId: string): Promise<AgentContext> {
const session = await this.loadSession(sessionId);
let context = this.createInitialContext(session.metadata);
for (const event of session.events) {
context = await this.applyEvent(context, event);
}
return context;
}
}
// .claude/config.json
interface ClaudeConfig {
permissionMode: PermissionMode;
customInstructions?: string;
deniedTools?: string[];
allowedDirectories?: string[];
hooks?: Hook[];
mcpServers?: MCPServerConfig[];
}
// CLAUDE.md hierarchy (most specific wins)
// workspace/subdir/CLAUDE.md > workspace/CLAUDE.md > ~/.claude/CLAUDE.md
async function loadConfig(workspacePath: string): Promise<ClaudeConfig> {
const configs: ClaudeConfig[] = [];
// Load from most general to most specific
const homeClaude = await loadIfExists('~/.claude/CLAUDE.md');
if (homeClaude) configs.push(homeClaude);
const workspaceClaude = await loadIfExists(path.join(workspacePath, 'CLAUDE.md'));
if (workspaceClaude) configs.push(workspaceClaude);
const configJson = await loadIfExists(path.join(workspacePath, '.claude/config.json'));
if (configJson) configs.push(configJson);
// Merge (most specific wins)
return mergeConfigs(configs);
}
interface SubagentConfig {
isolatedContext: boolean; // Always true in Claude Code
inheritPermissions: boolean; // Always false
parentVisibility: 'none' | 'summary' | 'full';
}
async function delegateToSubagent(
task: string,
parentContext: AgentContext
): Promise<SubagentResult> {
// Create isolated context (never inherits permissions)
const subagentContext: AgentContext = {
workspaceRoot: parentContext.workspaceRoot,
permissionMode: PermissionMode.Default, // Start at lowest trust
conversationHistory: [], // Empty history
availableTools: assembleToolPool({ /* fresh context */ }),
tokenBudget: parentContext.tokenBudget,
parentSessionId: null // No access to parent
};
// Run isolated agent loop
const result = await runAgentLoop(task, subagentContext);
// Return only summary to parent (not full context)
return {
summary: result.summary,
outcome: result.outcome,
// Full conversation history NOT returned
};
}
class RecoverySystem {
async executeWithRecovery(call: ToolCall): Promise<ToolResult> {
try {
return await this.execute(call);
} catch (error) {
// Strategy 1: Max output token escalation
if (error.code === 'OUTPUT_TOO_LONG') {
return await this.retryWithIncreasedTokens(call, {
attempt: 1,
maxAttempts: 3,
tokenMultiplier: 2
});
}
// Strategy 2: Reactive compaction
if (error.code === 'CONTEXT_TOO_LONG') {
const compacted = await this.compactContext();
return await this.execute(call);
}
// Strategy 3: Streaming fallback
if (error.code === 'STREAMING_FAILED') {
return await this.executeNonStreaming(call);
}
// Strategy 4: Fallback model
if (error.code === 'MODEL_UNAVAILABLE') {
return await this.executeWithFallbackModel(call);
}
// Strategy 5: Graceful degradation
if (error.code === 'TOOL_UNAVAILABLE') {
return {
success: false,
message: `Tool ${call.tool} unavailable, continuing with reduced capabilities`
};
}
throw error; // Unrecoverable
}
}
}
async function assemble(context: AgentContext): Promise<AssembledContext> {
// 1. Run PreContextAssembly hooks
await runHooks('PreContextAssembly', context);
// 2. Gather base context
let assembled = {
messages: [...context.conversationHistory],
tools: await assembleToolPool(context),
systemPrompt: await loadSystemPrompt(context)
};
// 3. Inject custom instructions (CLAUDE.md)
const customInstructions = await loadCustomInstructions(context.workspaceRoot);
if (customInstructions) {
assembled.systemPrompt += '\n\n' + customInstructions;
}
// 4. Inject skills (triggered by user message)
const triggeredSkills = await findTriggeredSkills(
context.lastUserMessage,
context.availableSkills
);
for (const skill of triggeredSkills) {
assembled.messages.push({
role: 'system',
content: skill.content
});
}
// 5. Run PostContextAssembly hooks
assembled = await runHooks('PostContextAssembly', assembled);
return assembled;
}
async function* streamingToolExecutor(
toolCalls: ToolCall[],
executor: ToolExecutor
): AsyncGenerator<ToolResult> {
// Classify as concurrent-safe or exclusive
const { concurrent, exclusive } = classifyTools(toolCalls);
// Execute concurrent tools in parallel
const concurrentPromises = concurrent.map(call => executor.execute(call));
for await (const result of yieldAsCompleted(concurrentPromises)) {
yield result;
}
// Execute exclusive tools sequentially
for (const call of exclusive) {
const result = await executor.execute(call);
yield result;
}
}
function classifyTools(calls: ToolCall[]): { concurrent: ToolCall[], exclusive: ToolCall[] } {
const concurrent: ToolCall[] = [];
const exclusive: ToolCall[] = [];
for (const call of calls) {
// File writes, shell commands → exclusive
if (['write_file', 'execute_command', 'apply_diff'].includes(call.tool)) {
exclusive.push(call);
} else {
concurrent.push(call);
}
}
return { concurrent, exclusive };
}
interface ClassifierResult {
safe: boolean;
reasoning: string;
confidence: number;
}
async function classifyToolCall(call: ToolCall): Promise<ClassifierResult> {
// Fast-filter heuristics (avoid LLM call if obviously safe/unsafe)
if (isTriviallyReversible(call)) {
return { safe: true, reasoning: 'Read-only operation', confidence: 1.0 };
}
if (isObviouslyDangerous(call)) {
return { safe: false, reasoning: 'Irreversible system modification', confidence: 1.0 };
}
// Chain-of-thought classifier
const prompt = `
Analyze this tool call for safety:
Tool: ${call.tool}
Arguments: ${JSON.stringify(call.args, null, 2)}
Context: ${call.context}
Consider:
1. Is this operation reversible?
2. Does it modify system-critical files?
3. Could it leak sensitive data?
4. Is the scope appropriate for the task?
Think step-by-step, then answer: SAFE or UNSAFE
`;
const response = await callClassifierModel(prompt);
return {
safe: response.includes('SAFE') && !response.includes('UNSAFE'),
reasoning: response,
confidence: extractConfidence(response)
};
}
// ANTI-PATTERN: Executing code before trust established
// ❌ Vulnerable: Extension runs during init
async function initializeWorkspace() {
await loadMCPServers(); // Executes server processes
await runHooks('WorkspaceInit'); // Runs arbitrary code
// Trust dialog appears AFTER extensions already ran
await promptForTrust();
}
// ✅ Safe: Defer privileged operations until after trust
async function initializeWorkspace() {
await promptForTrust();
// Only after user approval:
if (trusted) {
await loadMCPServers();
await runHooks('WorkspaceInit');
}
}
// WARNING: Multiple safety layers share performance constraints
async function analyzeCommand(command: string): Promise<SecurityAnalysis> {
const subcommands = parseSubcommands(command);
// If command too complex (>50 subcommands), ALL layers degrade:
if (subcommands.length > 50) {
// Layer 1: Security analysis skipped (event loop starvation)
// Layer 2: Classifier times out
// Layer 3: Hooks don't run
// Result: Command executes with minimal oversight
return {
analyzed: false,
reason: 'Command too complex for analysis',
fallbackToPermissionMode: true
};
}
return await fullSecurityAnalysis(command);
}
// Check compaction effectiveness
async function debugContextOverflow(context: AssembledContext) {
console.log('Token breakdown:');
console.log(' System prompt:', estimateTokens(context.systemPrompt));
console.log(' Conversation:', estimateTokens(context.messages));
console.log(' Tools:', estimateTokens(context.tools));
// Check if a single message is too large
const largeMessages = context.messages.filter(m =>
estimateTokens(m.content) > 10000
);
if (largeMessages.length > 0) {
console.log('Large messages detected - consider manual snipping');
}
// Verify compaction stages ran
if (!context.compactionMetadata) {
console.log('WARNING: Compaction metadata missing - pipeline may not have run');
}
}
// Debug deny-first rule resolution
function debugPermissionDenial(call: ToolCall, rules: PermissionRule[]) {
const matchingRules = rules.filter(r => matches(r, call));
console.log(`Matching rules for ${call.tool}:`);
matchingRules.forEach(rule => {
console.log(` [${rule.decision}] ${rule.scope}:${rule.pattern} (priority: ${rule.priority})`);
});
const denyRule = matchingRules.find(r => r.decision === 'deny');
if (denyRule) {
console.log(`\n❌ DENIED by rule: ${denyRule.pattern}`);
console.log(' Deny-first policy means this overrides all allow rules');
}
}
// Remember: Subagents are ALWAYS isolated
function debugSubagentIsolation() {
console.log('Subagent isolation checklist:');
console.log(' ❌ Does NOT inherit parent permissions');
console.log(' ❌ Does NOT see parent conversation history');
console.log(' ❌ Does NOT share parent context');
console.log(' ✅ DOES start at default permission mode');
console.log(' ✅ DOES get fresh tool pool');
console.log('\nIf you need shared context, use Skills instead of Subagents');
}
docs/architecture.md in repodocs/build-your-own-agent.mdLicense: CC-BY-NC-SA-4.0 (per upstream project)