mirror of
https://github.com/Piebald-AI/claude-code-system-prompts.git
synced 2026-06-01 14:58:21 +08:00
First attempt
This commit is contained in:
bl-ue
parent
0410732c78
commit
ee0649bccd
77
architecture/1-high-level-system-architecture.md
Normal file
77
architecture/1-high-level-system-architecture.md
Normal file
@ -0,0 +1,77 @@
|
|||||||
|
# High-Level System Architecture
|
||||||
|
|
||||||
|
This diagram shows the overall structure of Claude Code's prompt system.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph Core["Core System"]
|
||||||
|
Main["<b>Main System Prompt</b><br/>Behavior, tone, policies,<br/>task handling"]
|
||||||
|
click Main href "../system-prompts/system-prompt-main-system-prompt.md" "Main System Prompt"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Conditional["Conditional Additions"]
|
||||||
|
Security["Security Policy"]
|
||||||
|
Learning["Learning Mode"]
|
||||||
|
Git["Git Status"]
|
||||||
|
Scratchpad["Scratchpad Directory"]
|
||||||
|
MCP["MCP CLI"]
|
||||||
|
Chrome["Chrome Browser"]
|
||||||
|
click Learning href "../system-prompts/system-prompt-learning-mode.md" "Learning Mode"
|
||||||
|
click Git href "../system-prompts/system-prompt-git-status.md" "Git Status"
|
||||||
|
click Scratchpad href "../system-prompts/system-prompt-scratchpad-directory.md" "Scratchpad Directory"
|
||||||
|
click MCP href "../system-prompts/system-prompt-mcp-cli.md" "MCP CLI"
|
||||||
|
click Chrome href "../system-prompts/system-prompt-claude-in-chrome-browser-automation.md" "Chrome Browser Automation"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Tools["Built-in Tools"]
|
||||||
|
direction LR
|
||||||
|
FileTools["File Operations<br/>Read, Write, Edit,<br/>Glob, Grep"]
|
||||||
|
ExecTools["Execution<br/>Bash"]
|
||||||
|
WebTools["Web<br/>Search, Fetch"]
|
||||||
|
PlanTools["Planning<br/>TodoWrite,<br/>Enter/Exit PlanMode"]
|
||||||
|
InteractTools["Interaction<br/>Task, Skill,<br/>AskUserQuestion"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Agents["Sub-agents"]
|
||||||
|
direction LR
|
||||||
|
Explore["Explore<br/><i>Read-only search</i>"]
|
||||||
|
Plan["Plan<br/><i>Read-only design</i>"]
|
||||||
|
TaskAgent["Task Agent<br/><i>Autonomous work</i>"]
|
||||||
|
click Explore href "../system-prompts/agent-prompt-explore.md" "Explore Agent"
|
||||||
|
click Plan href "../system-prompts/agent-prompt-plan-mode-enhanced.md" "Plan Mode Agent"
|
||||||
|
click TaskAgent href "../system-prompts/agent-prompt-task-tool.md" "Task Tool Agent"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Utilities["Utility Agents"]
|
||||||
|
direction LR
|
||||||
|
Summary["Conversation<br/>Summarization"]
|
||||||
|
Session["Session Title<br/>& Branch Gen"]
|
||||||
|
Hooks["Hooks"]
|
||||||
|
Sentiment["User Sentiment<br/>Analysis"]
|
||||||
|
click Summary href "../system-prompts/agent-prompt-conversation-summarization.md" "Conversation Summarization"
|
||||||
|
click Session href "../system-prompts/agent-prompt-session-title-and-branch-generation.md" "Session Title Generation"
|
||||||
|
click Hooks href "../system-prompts/agent-prompt-agent-hook.md" "Agent Hook"
|
||||||
|
click Sentiment href "../system-prompts/agent-prompt-user-sentiment-analysis.md" "User Sentiment Analysis"
|
||||||
|
end
|
||||||
|
|
||||||
|
Main --> Conditional
|
||||||
|
Main --> Tools
|
||||||
|
Main --> Agents
|
||||||
|
Main --> Utilities
|
||||||
|
|
||||||
|
style Core fill:#e1f5fe
|
||||||
|
style Tools fill:#f3e5f5
|
||||||
|
style Agents fill:#e8f5e9
|
||||||
|
style Utilities fill:#fff3e0
|
||||||
|
style Conditional fill:#fce4ec
|
||||||
|
```
|
||||||
|
|
||||||
|
## Components
|
||||||
|
|
||||||
|
| Component | Description | Key Prompts |
|
||||||
|
|-----------|-------------|-------------|
|
||||||
|
| **Core System** | The main system prompt that defines Claude Code's behavior, tone, and policies | [Main System Prompt](../system-prompts/system-prompt-main-system-prompt.md) |
|
||||||
|
| **Conditional Additions** | Context-dependent prompt sections added based on environment and configuration | [Learning Mode](../system-prompts/system-prompt-learning-mode.md), [Git Status](../system-prompts/system-prompt-git-status.md), [MCP CLI](../system-prompts/system-prompt-mcp-cli.md) |
|
||||||
|
| **Built-in Tools** | Tool descriptions injected when tools are available | See [Tool Ecosystem](./3-tool-ecosystem.md) |
|
||||||
|
| **Sub-agents** | Specialized agents spawned for complex tasks | [Explore](../system-prompts/agent-prompt-explore.md), [Plan](../system-prompts/agent-prompt-plan-mode-enhanced.md), [Task](../system-prompts/agent-prompt-task-tool.md) |
|
||||||
|
| **Utility Agents** | Background agents for session management and analysis | [Summarization](../system-prompts/agent-prompt-conversation-summarization.md), [Session Title](../system-prompts/agent-prompt-session-title-and-branch-generation.md) |
|
||||||
101
architecture/2-agent-delegation-flow.md
Normal file
101
architecture/2-agent-delegation-flow.md
Normal file
@ -0,0 +1,101 @@
|
|||||||
|
# Agent Delegation Flow
|
||||||
|
|
||||||
|
This diagram shows how the main Claude Code agent decides when to handle tasks directly versus delegating to specialized sub-agents.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
User["👤 User Request"]
|
||||||
|
Main["Main Agent<br/><i>Main System Prompt</i>"]
|
||||||
|
click Main href "../system-prompts/system-prompt-main-system-prompt.md" "Main System Prompt"
|
||||||
|
|
||||||
|
Decision{{"Task Complexity?"}}
|
||||||
|
|
||||||
|
subgraph Direct["Direct Tool Use"]
|
||||||
|
direction TB
|
||||||
|
Read["ReadFile"]
|
||||||
|
Write["Write"]
|
||||||
|
Edit["Edit"]
|
||||||
|
Bash["Bash"]
|
||||||
|
Glob["Glob"]
|
||||||
|
Grep["Grep"]
|
||||||
|
Web["WebSearch /<br/>WebFetch"]
|
||||||
|
click Read href "../system-prompts/tool-description-readfile.md" "ReadFile Tool"
|
||||||
|
click Write href "../system-prompts/tool-description-write.md" "Write Tool"
|
||||||
|
click Edit href "../system-prompts/tool-description-edit.md" "Edit Tool"
|
||||||
|
click Bash href "../system-prompts/tool-description-bash.md" "Bash Tool"
|
||||||
|
click Glob href "../system-prompts/tool-description-glob.md" "Glob Tool"
|
||||||
|
click Grep href "../system-prompts/tool-description-grep.md" "Grep Tool"
|
||||||
|
click Web href "../system-prompts/tool-description-websearch.md" "WebSearch Tool"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph TaskTool["Task Tool Delegation"]
|
||||||
|
Task["Task Tool"]
|
||||||
|
click Task href "../system-prompts/tool-description-task.md" "Task Tool"
|
||||||
|
|
||||||
|
subgraph SubAgents["Sub-agent Types"]
|
||||||
|
Explore["<b>Explore Agent</b><br/><i>Read-only codebase search</i><br/>Tools: Glob, Grep, Read, Bash"]
|
||||||
|
Plan["<b>Plan Agent</b><br/><i>Read-only architecture design</i><br/>Tools: Glob, Grep, Read, Bash"]
|
||||||
|
Custom["<b>Custom Agents</b><br/><i>User-defined via config</i>"]
|
||||||
|
click Explore href "../system-prompts/agent-prompt-explore.md" "Explore Agent"
|
||||||
|
click Plan href "../system-prompts/agent-prompt-plan-mode-enhanced.md" "Plan Mode Agent"
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
TaskPrompt["Task Agent Prompt<br/><i>Given to spawned agent</i>"]
|
||||||
|
ExtraNotes["Extra Notes<br/><i>Absolute paths, formatting</i>"]
|
||||||
|
click TaskPrompt href "../system-prompts/agent-prompt-task-tool.md" "Task Agent Prompt"
|
||||||
|
click ExtraNotes href "../system-prompts/agent-prompt-task-tool-extra-notes.md" "Task Tool Extra Notes"
|
||||||
|
|
||||||
|
Result["📋 Result returned to Main Agent"]
|
||||||
|
Response["💬 Response to User"]
|
||||||
|
|
||||||
|
User --> Main
|
||||||
|
Main --> Decision
|
||||||
|
|
||||||
|
Decision -->|"Simple / Specific"| Direct
|
||||||
|
Decision -->|"Complex / Multi-step"| TaskTool
|
||||||
|
|
||||||
|
Task --> SubAgents
|
||||||
|
SubAgents --> TaskPrompt
|
||||||
|
TaskPrompt --> ExtraNotes
|
||||||
|
|
||||||
|
Direct --> Response
|
||||||
|
ExtraNotes --> Result
|
||||||
|
Result --> Main
|
||||||
|
Main --> Response
|
||||||
|
|
||||||
|
style Direct fill:#e8f5e9
|
||||||
|
style TaskTool fill:#e1f5fe
|
||||||
|
style SubAgents fill:#f3e5f5
|
||||||
|
```
|
||||||
|
|
||||||
|
## When to Use Direct Tools vs. Task Delegation
|
||||||
|
|
||||||
|
| Scenario | Approach | Reason |
|
||||||
|
|----------|----------|--------|
|
||||||
|
| Read a specific file | **Direct** (ReadFile) | Known path, simple operation |
|
||||||
|
| Search for "class Foo" | **Direct** (Grep) | Specific needle query |
|
||||||
|
| Find all TypeScript files | **Direct** (Glob) | Simple pattern match |
|
||||||
|
| "Where are errors handled?" | **Task** (Explore) | Requires codebase exploration |
|
||||||
|
| "What's the architecture?" | **Task** (Explore) | Needs broad understanding |
|
||||||
|
| Design a new feature | **Task** (Plan) | Requires analysis and design |
|
||||||
|
| Run tests after code changes | **Task** (Custom) | Multi-step autonomous work |
|
||||||
|
|
||||||
|
## Sub-agent Characteristics
|
||||||
|
|
||||||
|
### Explore Agent
|
||||||
|
- **Purpose**: Fast, read-only codebase search
|
||||||
|
- **Constraints**: Cannot create, modify, or delete files
|
||||||
|
- **Tools**: Glob, Grep, ReadFile, Bash (read-only commands only)
|
||||||
|
- **Prompt**: [agent-prompt-explore.md](../system-prompts/agent-prompt-explore.md)
|
||||||
|
|
||||||
|
### Plan Agent
|
||||||
|
- **Purpose**: Architecture analysis and implementation planning
|
||||||
|
- **Constraints**: Read-only, outputs a plan with critical files
|
||||||
|
- **Tools**: Glob, Grep, ReadFile, Bash (read-only commands only)
|
||||||
|
- **Prompt**: [agent-prompt-plan-mode-enhanced.md](../system-prompts/agent-prompt-plan-mode-enhanced.md)
|
||||||
|
|
||||||
|
### Task Agent (Generic)
|
||||||
|
- **Purpose**: Autonomous execution of delegated tasks
|
||||||
|
- **Prompt**: [agent-prompt-task-tool.md](../system-prompts/agent-prompt-task-tool.md)
|
||||||
|
- **Extra Notes**: [agent-prompt-task-tool-extra-notes.md](../system-prompts/agent-prompt-task-tool-extra-notes.md)
|
||||||
133
architecture/3-tool-ecosystem.md
Normal file
133
architecture/3-tool-ecosystem.md
Normal file
@ -0,0 +1,133 @@
|
|||||||
|
# Tool Ecosystem
|
||||||
|
|
||||||
|
This diagram maps all of Claude Code's built-in tools, organized by category.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph FileOps["📁 File Operations"]
|
||||||
|
direction TB
|
||||||
|
Read["<b>ReadFile</b><br/>Read file contents"]
|
||||||
|
Write["<b>Write</b><br/>Create/overwrite files"]
|
||||||
|
Edit["<b>Edit</b><br/>String replacement in files"]
|
||||||
|
Glob["<b>Glob</b><br/>Pattern-based file search"]
|
||||||
|
Grep["<b>Grep</b><br/>Content search with regex"]
|
||||||
|
Notebook["<b>NotebookEdit</b><br/>Jupyter cell editing"]
|
||||||
|
click Read href "../system-prompts/tool-description-readfile.md" "ReadFile"
|
||||||
|
click Write href "../system-prompts/tool-description-write.md" "Write"
|
||||||
|
click Edit href "../system-prompts/tool-description-edit.md" "Edit"
|
||||||
|
click Glob href "../system-prompts/tool-description-glob.md" "Glob"
|
||||||
|
click Grep href "../system-prompts/tool-description-grep.md" "Grep"
|
||||||
|
click Notebook href "../system-prompts/tool-description-notebookedit.md" "NotebookEdit"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Execution["⚡ Execution"]
|
||||||
|
direction TB
|
||||||
|
Bash["<b>Bash</b><br/>Shell command execution"]
|
||||||
|
BashGit["Git & PR Instructions<br/><i>Commit and PR creation</i>"]
|
||||||
|
BashSandbox["Sandbox Note<br/><i>Security sandboxing</i>"]
|
||||||
|
click Bash href "../system-prompts/tool-description-bash.md" "Bash"
|
||||||
|
click BashGit href "../system-prompts/tool-description-bash-git-commit-and-pr-creation-instructions.md" "Git Instructions"
|
||||||
|
click BashSandbox href "../system-prompts/tool-description-bash-sandbox-note.md" "Sandbox Note"
|
||||||
|
|
||||||
|
Bash --> BashGit
|
||||||
|
Bash --> BashSandbox
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Web["🌐 Web"]
|
||||||
|
direction TB
|
||||||
|
WebSearch["<b>WebSearch</b><br/>Real-time web search"]
|
||||||
|
WebFetch["<b>WebFetch</b><br/>Fetch URL contents"]
|
||||||
|
click WebSearch href "../system-prompts/tool-description-websearch.md" "WebSearch"
|
||||||
|
click WebFetch href "../system-prompts/tool-description-webfetch.md" "WebFetch"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Planning["📋 Planning & Tasks"]
|
||||||
|
direction TB
|
||||||
|
Todo["<b>TodoWrite</b><br/>Task list management"]
|
||||||
|
Enter["<b>EnterPlanMode</b><br/>Start planning mode"]
|
||||||
|
Exit["<b>ExitPlanMode</b><br/>Present plan for approval"]
|
||||||
|
ExitV2["<b>ExitPlanMode v2</b><br/>Enhanced plan dialog"]
|
||||||
|
click Todo href "../system-prompts/tool-description-todowrite.md" "TodoWrite"
|
||||||
|
click Enter href "../system-prompts/tool-description-enterplanmode.md" "EnterPlanMode"
|
||||||
|
click Exit href "../system-prompts/tool-description-exitplanmode.md" "ExitPlanMode"
|
||||||
|
click ExitV2 href "../system-prompts/tool-description-exitplanmode-v2.md" "ExitPlanMode v2"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Interaction["💬 Interaction"]
|
||||||
|
direction TB
|
||||||
|
Task["<b>Task</b><br/>Launch sub-agents"]
|
||||||
|
Skill["<b>Skill</b><br/>Execute skills"]
|
||||||
|
Ask["<b>AskUserQuestion</b><br/>Clarification prompts"]
|
||||||
|
click Task href "../system-prompts/tool-description-task.md" "Task"
|
||||||
|
click Skill href "../system-prompts/tool-description-skill.md" "Skill"
|
||||||
|
click Ask href "../system-prompts/tool-description-askuserquestion.md" "AskUserQuestion"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Specialized["🔧 Specialized"]
|
||||||
|
direction TB
|
||||||
|
Computer["<b>Computer</b><br/>Chrome browser automation"]
|
||||||
|
LSP["<b>LSP</b><br/>Language Server Protocol"]
|
||||||
|
MCP["<b>MCPSearch</b><br/>MCP server discovery"]
|
||||||
|
MCPTools["MCPSearch<br/><i>with available tools</i>"]
|
||||||
|
click Computer href "../system-prompts/tool-description-computer.md" "Computer"
|
||||||
|
click LSP href "../system-prompts/tool-description-lsp.md" "LSP"
|
||||||
|
click MCP href "../system-prompts/tool-description-mcpsearch.md" "MCPSearch"
|
||||||
|
click MCPTools href "../system-prompts/tool-description-mcpsearch-with-available-tools.md" "MCPSearch with tools"
|
||||||
|
|
||||||
|
MCP --> MCPTools
|
||||||
|
end
|
||||||
|
|
||||||
|
style FileOps fill:#e8f5e9
|
||||||
|
style Execution fill:#fff3e0
|
||||||
|
style Web fill:#e1f5fe
|
||||||
|
style Planning fill:#f3e5f5
|
||||||
|
style Interaction fill:#fce4ec
|
||||||
|
style Specialized fill:#f5f5f5
|
||||||
|
```
|
||||||
|
|
||||||
|
## Tool Quick Reference
|
||||||
|
|
||||||
|
### File Operations
|
||||||
|
| Tool | Purpose | Prompt File |
|
||||||
|
|------|---------|-------------|
|
||||||
|
| **ReadFile** | Read file contents with optional offset/limit | [tool-description-readfile.md](../system-prompts/tool-description-readfile.md) |
|
||||||
|
| **Write** | Create or overwrite entire files | [tool-description-write.md](../system-prompts/tool-description-write.md) |
|
||||||
|
| **Edit** | Exact string replacement in existing files | [tool-description-edit.md](../system-prompts/tool-description-edit.md) |
|
||||||
|
| **Glob** | Find files by pattern (e.g., `**/*.ts`) | [tool-description-glob.md](../system-prompts/tool-description-glob.md) |
|
||||||
|
| **Grep** | Search file contents with regex | [tool-description-grep.md](../system-prompts/tool-description-grep.md) |
|
||||||
|
| **NotebookEdit** | Edit Jupyter notebook cells | [tool-description-notebookedit.md](../system-prompts/tool-description-notebookedit.md) |
|
||||||
|
|
||||||
|
### Execution
|
||||||
|
| Tool | Purpose | Prompt File |
|
||||||
|
|------|---------|-------------|
|
||||||
|
| **Bash** | Execute shell commands | [tool-description-bash.md](../system-prompts/tool-description-bash.md) |
|
||||||
|
| ↳ Git Instructions | How to create commits and PRs | [tool-description-bash-git-commit-and-pr-creation-instructions.md](../system-prompts/tool-description-bash-git-commit-and-pr-creation-instructions.md) |
|
||||||
|
| ↳ Sandbox Note | Security sandboxing info | [tool-description-bash-sandbox-note.md](../system-prompts/tool-description-bash-sandbox-note.md) |
|
||||||
|
|
||||||
|
### Web
|
||||||
|
| Tool | Purpose | Prompt File |
|
||||||
|
|------|---------|-------------|
|
||||||
|
| **WebSearch** | Search the web for real-time information | [tool-description-websearch.md](../system-prompts/tool-description-websearch.md) |
|
||||||
|
| **WebFetch** | Fetch content from specific URLs | [tool-description-webfetch.md](../system-prompts/tool-description-webfetch.md) |
|
||||||
|
|
||||||
|
### Planning & Tasks
|
||||||
|
| Tool | Purpose | Prompt File |
|
||||||
|
|------|---------|-------------|
|
||||||
|
| **TodoWrite** | Create and manage task lists | [tool-description-todowrite.md](../system-prompts/tool-description-todowrite.md) |
|
||||||
|
| **EnterPlanMode** | Enter planning mode for complex tasks | [tool-description-enterplanmode.md](../system-prompts/tool-description-enterplanmode.md) |
|
||||||
|
| **ExitPlanMode** | Present plan for user approval | [tool-description-exitplanmode.md](../system-prompts/tool-description-exitplanmode.md) |
|
||||||
|
| **ExitPlanMode v2** | Enhanced plan dialog | [tool-description-exitplanmode-v2.md](../system-prompts/tool-description-exitplanmode-v2.md) |
|
||||||
|
|
||||||
|
### Interaction
|
||||||
|
| Tool | Purpose | Prompt File |
|
||||||
|
|------|---------|-------------|
|
||||||
|
| **Task** | Launch specialized sub-agents | [tool-description-task.md](../system-prompts/tool-description-task.md) |
|
||||||
|
| **Skill** | Execute predefined skills | [tool-description-skill.md](../system-prompts/tool-description-skill.md) |
|
||||||
|
| **AskUserQuestion** | Ask user for clarification | [tool-description-askuserquestion.md](../system-prompts/tool-description-askuserquestion.md) |
|
||||||
|
|
||||||
|
### Specialized
|
||||||
|
| Tool | Purpose | Prompt File |
|
||||||
|
|------|---------|-------------|
|
||||||
|
| **Computer** | Chrome browser automation | [tool-description-computer.md](../system-prompts/tool-description-computer.md) |
|
||||||
|
| **LSP** | Language Server Protocol operations | [tool-description-lsp.md](../system-prompts/tool-description-lsp.md) |
|
||||||
|
| **MCPSearch** | Search for MCP servers | [tool-description-mcpsearch.md](../system-prompts/tool-description-mcpsearch.md) |
|
||||||
137
architecture/4-conversation-lifecycle.md
Normal file
137
architecture/4-conversation-lifecycle.md
Normal file
@ -0,0 +1,137 @@
|
|||||||
|
# Conversation Lifecycle
|
||||||
|
|
||||||
|
This diagram shows how different prompts are used throughout a Claude Code session, from start to finish.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
autonumber
|
||||||
|
participant User
|
||||||
|
participant CC as Claude Code
|
||||||
|
participant Main as Main Agent
|
||||||
|
participant Tools as Tools
|
||||||
|
participant SubAgent as Sub-agents
|
||||||
|
participant Utility as Utility Agents
|
||||||
|
|
||||||
|
Note over CC: Session Start
|
||||||
|
|
||||||
|
rect rgb(225, 245, 254)
|
||||||
|
Note over Main: System Prompt Assembly
|
||||||
|
CC->>Main: Load Main System Prompt
|
||||||
|
CC->>Main: Inject Tool Descriptions
|
||||||
|
CC->>Main: Add Conditional Sections<br/>(Git Status, Learning Mode, etc.)
|
||||||
|
end
|
||||||
|
|
||||||
|
User->>CC: Initial message
|
||||||
|
CC->>Main: Process request
|
||||||
|
|
||||||
|
rect rgb(232, 245, 233)
|
||||||
|
Note over Main,Tools: Work Phase
|
||||||
|
loop Task Execution
|
||||||
|
Main->>Tools: Use tools (Read, Write, Bash, etc.)
|
||||||
|
Tools-->>Main: Results
|
||||||
|
|
||||||
|
alt Complex task
|
||||||
|
Main->>SubAgent: Delegate via Task tool
|
||||||
|
Note over SubAgent: Agent-specific prompt loaded
|
||||||
|
SubAgent-->>Main: Results
|
||||||
|
end
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
rect rgb(255, 243, 224)
|
||||||
|
Note over Utility: Context Management
|
||||||
|
alt Context grows large
|
||||||
|
CC->>Utility: Trigger Summarization
|
||||||
|
Note over Utility: Conversation Summarization prompt
|
||||||
|
Utility-->>CC: Compressed context
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
User->>CC: Follow-up messages
|
||||||
|
Note over Main: Continue with context
|
||||||
|
|
||||||
|
rect rgb(252, 228, 236)
|
||||||
|
Note over Utility: Session End
|
||||||
|
CC->>Utility: Generate session title
|
||||||
|
Note over Utility: Session Title & Branch prompt
|
||||||
|
Utility-->>CC: Title and branch name
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
## Lifecycle Phases
|
||||||
|
|
||||||
|
### 1. Session Initialization
|
||||||
|
|
||||||
|
When a Claude Code session starts, the system prompt is assembled from multiple pieces:
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
subgraph Assembly["System Prompt Assembly"]
|
||||||
|
direction TB
|
||||||
|
Base["Main System Prompt"]
|
||||||
|
Tools["Tool Descriptions"]
|
||||||
|
Cond["Conditional Sections"]
|
||||||
|
|
||||||
|
Base --> Final["Complete System Prompt"]
|
||||||
|
Tools --> Final
|
||||||
|
Cond --> Final
|
||||||
|
end
|
||||||
|
|
||||||
|
click Base href "../system-prompts/system-prompt-main-system-prompt.md" "Main System Prompt"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Prompts:**
|
||||||
|
- [Main System Prompt](../system-prompts/system-prompt-main-system-prompt.md) - Core behavior and policies
|
||||||
|
- [Git Status](../system-prompts/system-prompt-git-status.md) - Repository state (if in git repo)
|
||||||
|
- [Learning Mode](../system-prompts/system-prompt-learning-mode.md) - Educational mode (if enabled)
|
||||||
|
- [Scratchpad Directory](../system-prompts/system-prompt-scratchpad-directory.md) - Temp file location (if configured)
|
||||||
|
|
||||||
|
### 2. Work Phase
|
||||||
|
|
||||||
|
During active work, the main agent uses tools and may delegate to sub-agents:
|
||||||
|
|
||||||
|
| Action | Prompts Used |
|
||||||
|
|--------|-------------|
|
||||||
|
| Direct tool use | Individual [tool descriptions](./3-tool-ecosystem.md) |
|
||||||
|
| Codebase exploration | [Explore Agent](../system-prompts/agent-prompt-explore.md) via Task |
|
||||||
|
| Planning | [Plan Agent](../system-prompts/agent-prompt-plan-mode-enhanced.md) via Task |
|
||||||
|
| Task management | [TodoWrite](../system-prompts/tool-description-todowrite.md) |
|
||||||
|
|
||||||
|
### 3. Context Management
|
||||||
|
|
||||||
|
As conversation grows, summarization preserves important context:
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Long["Long Conversation"] --> Trigger{"Context<br/>too large?"}
|
||||||
|
Trigger -->|Yes| Summary["Summarization Agent"]
|
||||||
|
Summary --> Compact["Compacted Context"]
|
||||||
|
Compact --> Continue["Continue Session"]
|
||||||
|
Trigger -->|No| Continue
|
||||||
|
|
||||||
|
click Summary href "../system-prompts/agent-prompt-conversation-summarization.md" "Summarization"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Prompts:**
|
||||||
|
- [Conversation Summarization](../system-prompts/agent-prompt-conversation-summarization.md) - Standard summarization
|
||||||
|
- [Summarization with Additional Instructions](../system-prompts/agent-prompt-conversation-summarization-with-additional-instructions.md) - Custom summarization rules
|
||||||
|
|
||||||
|
### 4. Session End
|
||||||
|
|
||||||
|
When a session concludes, utility agents generate metadata:
|
||||||
|
|
||||||
|
**Key Prompts:**
|
||||||
|
- [Session Title & Branch Generation](../system-prompts/agent-prompt-session-title-and-branch-generation.md) - Creates descriptive title and git branch name
|
||||||
|
- [Session Notes Template](../system-prompts/agent-prompt-session-notes-template.md) - Structure for session notes
|
||||||
|
- [Session Notes Update](../system-prompts/agent-prompt-session-notes-update-instructions.md) - How to update notes during session
|
||||||
|
|
||||||
|
## Prompt Injection Points
|
||||||
|
|
||||||
|
| Phase | Injection Point | Prompt Type |
|
||||||
|
|-------|----------------|-------------|
|
||||||
|
| Start | System message | Main + conditionals |
|
||||||
|
| Tool call | Tool schema | Tool descriptions |
|
||||||
|
| Sub-agent spawn | New context | Agent prompts |
|
||||||
|
| Context compact | Background | Summarization prompt |
|
||||||
|
| Plan mode | System reminder | Plan mode reminders |
|
||||||
|
| Session end | Background | Title/branch generation |
|
||||||
165
architecture/5-plan-mode-flow.md
Normal file
165
architecture/5-plan-mode-flow.md
Normal file
@ -0,0 +1,165 @@
|
|||||||
|
# Plan Mode Flow
|
||||||
|
|
||||||
|
This diagram shows the planning subsystem—how Claude Code enters, operates in, and exits plan mode.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
stateDiagram-v2
|
||||||
|
[*] --> NormalMode: Session Start
|
||||||
|
|
||||||
|
NormalMode --> PlanMode: Shift+Tab OR<br/>EnterPlanMode tool
|
||||||
|
|
||||||
|
state PlanMode {
|
||||||
|
direction TB
|
||||||
|
[*] --> Exploring
|
||||||
|
Exploring --> Designing: Understanding complete
|
||||||
|
Designing --> ProposingPlan: Design ready
|
||||||
|
|
||||||
|
state Exploring {
|
||||||
|
direction LR
|
||||||
|
ReadFiles: Read relevant files
|
||||||
|
SearchCode: Search codebase
|
||||||
|
AnalyzeArch: Analyze architecture
|
||||||
|
}
|
||||||
|
|
||||||
|
state Designing {
|
||||||
|
direction LR
|
||||||
|
IdentifyPatterns: Identify patterns
|
||||||
|
ConsiderTradeoffs: Consider trade-offs
|
||||||
|
PlanSteps: Plan implementation steps
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
PlanMode --> ExitDecision: ExitPlanMode tool
|
||||||
|
|
||||||
|
state ExitDecision <<choice>>
|
||||||
|
ExitDecision --> Implementation: User approves
|
||||||
|
ExitDecision --> PlanMode: User requests changes
|
||||||
|
|
||||||
|
Implementation --> NormalMode: Work complete
|
||||||
|
NormalMode --> PlanMode: Re-enter (Shift+Tab)
|
||||||
|
|
||||||
|
NormalMode --> [*]: Session End
|
||||||
|
```
|
||||||
|
|
||||||
|
## Plan Mode Entry Points
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
subgraph Triggers["Entry Triggers"]
|
||||||
|
Keyboard["⌨️ Shift+Tab"]
|
||||||
|
Tool["🔧 EnterPlanMode tool"]
|
||||||
|
Complex["🤔 Complex task detected"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Entry["Plan Mode Activation"]
|
||||||
|
Enter["EnterPlanMode"]
|
||||||
|
Reminder["Plan Mode Reminder<br/>injected into context"]
|
||||||
|
end
|
||||||
|
|
||||||
|
Triggers --> Entry
|
||||||
|
|
||||||
|
click Enter href "../system-prompts/tool-description-enterplanmode.md" "EnterPlanMode"
|
||||||
|
click Reminder href "../system-prompts/system-reminder-plan-mode-is-active.md" "Plan Mode Reminder"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Prompts:**
|
||||||
|
- [EnterPlanMode Tool](../system-prompts/tool-description-enterplanmode.md) - Tool description for entering plan mode
|
||||||
|
- [Plan Mode Active Reminder](../system-prompts/system-reminder-plan-mode-is-active.md) - System reminder injected when plan mode is active
|
||||||
|
|
||||||
|
## Plan Mode Operation
|
||||||
|
|
||||||
|
While in plan mode, Claude Code operates in **read-only** mode with specific capabilities:
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph Capabilities["✅ Allowed in Plan Mode"]
|
||||||
|
Read["Read files"]
|
||||||
|
Search["Search codebase"]
|
||||||
|
Analyze["Analyze patterns"]
|
||||||
|
Design["Design solutions"]
|
||||||
|
Parallel["Spawn parallel<br/>exploration agents"]
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Restricted["❌ Restricted in Plan Mode"]
|
||||||
|
Write["Write files"]
|
||||||
|
Edit["Edit files"]
|
||||||
|
Execute["Execute commands<br/>(except read-only)"]
|
||||||
|
Create["Create anything"]
|
||||||
|
end
|
||||||
|
|
||||||
|
PlanAgent["Plan Mode Agent"]
|
||||||
|
PlanAgent --> Capabilities
|
||||||
|
PlanAgent -.->|blocked| Restricted
|
||||||
|
|
||||||
|
click PlanAgent href "../system-prompts/agent-prompt-plan-mode-enhanced.md" "Plan Mode Agent"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Prompts:**
|
||||||
|
- [Plan Mode Agent](../system-prompts/agent-prompt-plan-mode-enhanced.md) - Enhanced planning prompt
|
||||||
|
- [Plan Mode for Subagents](../system-prompts/system-reminder-plan-mode-is-active-for-subagents.md) - Simplified reminder for spawned sub-agents
|
||||||
|
|
||||||
|
## Plan Mode Exit
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
PlanReady["Plan Ready"]
|
||||||
|
Exit["ExitPlanMode Tool"]
|
||||||
|
|
||||||
|
subgraph Dialog["Plan Approval Dialog"]
|
||||||
|
Present["Present plan to user"]
|
||||||
|
UserChoice{{"User Decision"}}
|
||||||
|
Approve["✅ Approve"]
|
||||||
|
Modify["✏️ Request changes"]
|
||||||
|
Reject["❌ Reject"]
|
||||||
|
end
|
||||||
|
|
||||||
|
PlanReady --> Exit
|
||||||
|
Exit --> Present
|
||||||
|
Present --> UserChoice
|
||||||
|
UserChoice --> Approve
|
||||||
|
UserChoice --> Modify
|
||||||
|
UserChoice --> Reject
|
||||||
|
|
||||||
|
Approve --> Implement["Begin Implementation"]
|
||||||
|
Modify --> Continue["Continue Planning"]
|
||||||
|
Reject --> Normal["Return to Normal Mode"]
|
||||||
|
|
||||||
|
click Exit href "../system-prompts/tool-description-exitplanmode.md" "ExitPlanMode"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Prompts:**
|
||||||
|
- [ExitPlanMode Tool](../system-prompts/tool-description-exitplanmode.md) - Standard exit tool
|
||||||
|
- [ExitPlanMode v2](../system-prompts/tool-description-exitplanmode-v2.md) - Enhanced plan dialog
|
||||||
|
|
||||||
|
## Re-entry Flow
|
||||||
|
|
||||||
|
Users can re-enter plan mode after exiting:
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Normal["Normal Mode<br/>(implementing)"]
|
||||||
|
ReEnter["Shift+Tab"]
|
||||||
|
PlanAgain["Plan Mode<br/>(re-entered)"]
|
||||||
|
Reminder["Re-entry Reminder"]
|
||||||
|
|
||||||
|
Normal --> ReEnter
|
||||||
|
ReEnter --> PlanAgain
|
||||||
|
PlanAgain --> Reminder
|
||||||
|
|
||||||
|
click Reminder href "../system-prompts/system-reminder-plan-mode-re-entry.md" "Re-entry Reminder"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Prompt:**
|
||||||
|
- [Plan Mode Re-entry](../system-prompts/system-reminder-plan-mode-re-entry.md) - Reminder when re-entering plan mode after implementation
|
||||||
|
|
||||||
|
## All Plan Mode Prompts
|
||||||
|
|
||||||
|
| Prompt | Purpose | File |
|
||||||
|
|--------|---------|------|
|
||||||
|
| **EnterPlanMode** | Tool to enter plan mode | [tool-description-enterplanmode.md](../system-prompts/tool-description-enterplanmode.md) |
|
||||||
|
| **ExitPlanMode** | Tool to exit with plan | [tool-description-exitplanmode.md](../system-prompts/tool-description-exitplanmode.md) |
|
||||||
|
| **ExitPlanMode v2** | Enhanced exit dialog | [tool-description-exitplanmode-v2.md](../system-prompts/tool-description-exitplanmode-v2.md) |
|
||||||
|
| **Plan Mode Agent** | Agent behavior in plan mode | [agent-prompt-plan-mode-enhanced.md](../system-prompts/agent-prompt-plan-mode-enhanced.md) |
|
||||||
|
| **Active Reminder** | Injected while plan mode active | [system-reminder-plan-mode-is-active.md](../system-prompts/system-reminder-plan-mode-is-active.md) |
|
||||||
|
| **Subagent Reminder** | Simplified reminder for sub-agents | [system-reminder-plan-mode-is-active-for-subagents.md](../system-prompts/system-reminder-plan-mode-is-active-for-subagents.md) |
|
||||||
|
| **Re-entry Reminder** | When re-entering after exit | [system-reminder-plan-mode-re-entry.md](../system-prompts/system-reminder-plan-mode-re-entry.md) |
|
||||||
166
architecture/6-slash-commands-and-skills.md
Normal file
166
architecture/6-slash-commands-and-skills.md
Normal file
@ -0,0 +1,166 @@
|
|||||||
|
# Slash Commands & Skills
|
||||||
|
|
||||||
|
This diagram maps Claude Code's built-in slash commands and the skill system to their prompts.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph SlashCommands["Slash Commands"]
|
||||||
|
direction TB
|
||||||
|
|
||||||
|
subgraph PR["Pull Request Commands"]
|
||||||
|
PRComments["/pr-comments<br/><i>Fetch PR comments</i>"]
|
||||||
|
ReviewPR["/review-pr<br/><i>Review a PR</i>"]
|
||||||
|
click PRComments href "../system-prompts/agent-prompt-pr-comments-slash-command.md" "/pr-comments"
|
||||||
|
click ReviewPR href "../system-prompts/agent-prompt-review-pr-slash-command.md" "/review-pr"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Security["Security Commands"]
|
||||||
|
SecReview["/security-review<br/><i>Security analysis</i>"]
|
||||||
|
click SecReview href "../system-prompts/agent-prompt-security-review-slash.md" "/security-review"
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph Memory["Memory Commands"]
|
||||||
|
Remember["/remember<br/><i>Save learnings</i>"]
|
||||||
|
click Remember href "../system-prompts/agent-prompt-remember-skill.md" "/remember"
|
||||||
|
end
|
||||||
|
end
|
||||||
|
|
||||||
|
subgraph SkillSystem["Skill System"]
|
||||||
|
SkillTool["Skill Tool"]
|
||||||
|
SkillDesc["Skill Description"]
|
||||||
|
CustomSkills["Custom Skills<br/><i>User-defined</i>"]
|
||||||
|
click SkillTool href "../system-prompts/tool-description-skill.md" "Skill Tool"
|
||||||
|
end
|
||||||
|
|
||||||
|
User["👤 User"]
|
||||||
|
User -->|"/command"| SlashCommands
|
||||||
|
User -->|"Skill invocation"| SkillSystem
|
||||||
|
|
||||||
|
style SlashCommands fill:#e1f5fe
|
||||||
|
style SkillSystem fill:#f3e5f5
|
||||||
|
style PR fill:#e8f5e9
|
||||||
|
style Security fill:#fff3e0
|
||||||
|
style Memory fill:#fce4ec
|
||||||
|
```
|
||||||
|
|
||||||
|
## Built-in Slash Commands
|
||||||
|
|
||||||
|
### `/pr-comments` - Fetch PR Comments
|
||||||
|
|
||||||
|
Fetches and displays comments from a GitHub Pull Request.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Cmd["/pr-comments"] --> Agent["PR Comments Agent"]
|
||||||
|
Agent --> Fetch["Fetch from GitHub"]
|
||||||
|
Fetch --> Display["Display comments"]
|
||||||
|
|
||||||
|
click Agent href "../system-prompts/agent-prompt-pr-comments-slash-command.md" "PR Comments Agent"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Prompt:** [agent-prompt-pr-comments-slash-command.md](../system-prompts/agent-prompt-pr-comments-slash-command.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `/review-pr` - Review Pull Request
|
||||||
|
|
||||||
|
Performs a code review on a GitHub Pull Request.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Cmd["/review-pr"] --> Agent["PR Review Agent"]
|
||||||
|
Agent --> Analyze["Analyze changes"]
|
||||||
|
Analyze --> Review["Generate review"]
|
||||||
|
|
||||||
|
click Agent href "../system-prompts/agent-prompt-review-pr-slash-command.md" "PR Review Agent"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Prompt:** [agent-prompt-review-pr-slash-command.md](../system-prompts/agent-prompt-review-pr-slash-command.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `/security-review` - Security Analysis
|
||||||
|
|
||||||
|
Comprehensive security review focusing on exploitable vulnerabilities (OWASP Top 10, etc.).
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Cmd["/security-review"] --> Agent["Security Review Agent"]
|
||||||
|
Agent --> Scan["Scan for vulnerabilities"]
|
||||||
|
Scan --> Report["Generate report<br/>with severity levels"]
|
||||||
|
|
||||||
|
click Agent href "../system-prompts/agent-prompt-security-review-slash.md" "Security Review Agent"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Prompt:** [agent-prompt-security-review-slash.md](../system-prompts/agent-prompt-security-review-slash.md)
|
||||||
|
|
||||||
|
*Note: This is the largest slash command prompt at ~2610 tokens, reflecting the depth of security analysis.*
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `/remember` - Save Learnings
|
||||||
|
|
||||||
|
Reviews session memories and updates `CLAUDE.local.md` with recurring patterns and learnings.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
Cmd["/remember"] --> Agent["Remember Skill Agent"]
|
||||||
|
Agent --> Review["Review session"]
|
||||||
|
Review --> Update["Update CLAUDE.local.md"]
|
||||||
|
|
||||||
|
click Agent href "../system-prompts/agent-prompt-remember-skill.md" "Remember Skill Agent"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Prompt:** [agent-prompt-remember-skill.md](../system-prompts/agent-prompt-remember-skill.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Skill System
|
||||||
|
|
||||||
|
The Skill tool allows execution of both built-in and custom skills.
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TB
|
||||||
|
subgraph Invocation["Skill Invocation"]
|
||||||
|
Direct["Direct call"]
|
||||||
|
SlashCmd["Via slash command"]
|
||||||
|
Auto["Automatic trigger"]
|
||||||
|
end
|
||||||
|
|
||||||
|
SkillTool["Skill Tool"]
|
||||||
|
|
||||||
|
subgraph Execution["Skill Execution"]
|
||||||
|
Load["Load skill definition"]
|
||||||
|
Context["Inject into conversation"]
|
||||||
|
Run["Execute skill logic"]
|
||||||
|
end
|
||||||
|
|
||||||
|
Invocation --> SkillTool
|
||||||
|
SkillTool --> Execution
|
||||||
|
|
||||||
|
click SkillTool href "../system-prompts/tool-description-skill.md" "Skill Tool"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Prompt:** [tool-description-skill.md](../system-prompts/tool-description-skill.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Command | Purpose | Prompt File |
|
||||||
|
|---------|---------|-------------|
|
||||||
|
| `/pr-comments` | Fetch GitHub PR comments | [agent-prompt-pr-comments-slash-command.md](../system-prompts/agent-prompt-pr-comments-slash-command.md) |
|
||||||
|
| `/review-pr` | Review a Pull Request | [agent-prompt-review-pr-slash-command.md](../system-prompts/agent-prompt-review-pr-slash-command.md) |
|
||||||
|
| `/security-review` | Security vulnerability analysis | [agent-prompt-security-review-slash.md](../system-prompts/agent-prompt-security-review-slash.md) |
|
||||||
|
| `/remember` | Save session learnings | [agent-prompt-remember-skill.md](../system-prompts/agent-prompt-remember-skill.md) |
|
||||||
|
| *Skill Tool* | Execute custom skills | [tool-description-skill.md](../system-prompts/tool-description-skill.md) |
|
||||||
|
|
||||||
|
## Related Prompts
|
||||||
|
|
||||||
|
These utility prompts support the slash command system:
|
||||||
|
|
||||||
|
| Prompt | Purpose | File |
|
||||||
|
|--------|---------|------|
|
||||||
|
| **CLAUDE.md Creation** | Generate project documentation | [agent-prompt-claudemd-creation.md](../system-prompts/agent-prompt-claudemd-creation.md) |
|
||||||
|
| **Agent Creation** | Create custom agents | [agent-prompt-agent-creation-architect.md](../system-prompts/agent-prompt-agent-creation-architect.md) |
|
||||||
|
| **Prompt Suggestions** | Generate follow-up prompts | [agent-prompt-prompt-suggestion-generator-v2.md](../system-prompts/agent-prompt-prompt-suggestion-generator-v2.md) |
|
||||||
Loading…
x
Reference in New Issue
Block a user