claude-code-handbook

<p align="center"> <img src="docs/assets/readme-banner-1280x640.png" alt="claude-code-handbook" width="100%"> </p> <p align="center"> <a href="./docs/"><img src="https://img.shields.io/badge/docs-Markdown-lightgrey" alt="Docs"></a> <a href="./mewcode/"><img src="https://img.shields.io/badge/python-3.13-blue" alt="Python"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License"></a> </p> --- ## One-Sentence Positioning **A practical knowledge base to take Claude Code from "usable" to "buildable".** Not a recitation of official documentation, nor a piling up of academic papers. Here are three things: 1. **User Manual** — Helps you use Claude Code more steadily, quickly, and with less worry 2. **Practical Recipes** — Directly usable Skill, Agent examples, and configuration templates 3. **Agent Runtime Workshop** — Hands-on from scratch to build a Claude Code-style Coding Agent --- ## Who is it for - 👨‍💻 **Individual Developers**: Want to establish a stable AI-assisted development workflow - 🏗️ **AI Full-Stack Engineers**: Need to integrate Claude Code into complex projects and enterprise processes - 🚀 **Team Leaders**: Want to reference AI Coding engineering practices from organizations like Xiaomi - 🔧 **Agent Builders**: Plan to dive deep into Agent Runtime, from user to builder --- ## Four Major Sections ### 📘 User Manual 8 parts, 24 chapters, from installation and configuration to advanced techniques. - Core Workflow (Matt Pocock / Xu Wenhao) - Xiaomi AI Coding Engineering Practice - Memory, Context, Skills, Hooks, MCP - Permissions, Isolation, Failure Modes → [Enter the Manual](./docs/manual/) --- ### 🧰 Practical Recipes Directly usable code, configurations, and templates. - Agent example code - SKILL.md templates (agent-builder / code-review / mcp-builder / pdf) - Claude Code English and Chinese learning documents - Mainstream Agent Harness comparison and reference → [View Recipes](./docs/recipes/) --- ### 🛠️ Agent Runtime Workshop 10 chapter tutorials + Python reference implementation. - From LLM client to Agent main loop - Tool system, permissions, context, memory - Skill, SubAgent, Agent Teams → [Start the Workshop](./docs/workshop/) --- ### 🏗️ Harness Notes Agent Harness architecture learning and organization. - OpenCode / Codex / DeerFlow comparison - Claude Code Runtime mechanism disassembly - Harness design pattern summary → [View Notes](./harness/) --- ## 📚 Content Map ### User Manual | Part | Content | |------|------| | **part-01-overview** | [What is it](./docs/manual/part-01-overview/ch-01-what-is-it.md), [Three forms of usage](./docs/manual/part-01-overview/ch-02-three-forms.md) | | **part-02-basics** | [Installation and initialization](./docs/manual/part-02-basics/ch-03-install-init.md), [Session management](./docs/manual/part-02-basics/ch-04-session-mgmt.md), [Project-level configuration](./docs/manual/part-02-basics/ch-05-project-config.md) | | **part-03-workflow** | [Demand-driven workflow](./docs/manual/part-03-workflow/ch-06-demand-workflow.md), [Secure development closed loop](./docs/manual/part-03-workflow/ch-07-security-closure.md), [Development rhythm](./docs/manual/part-03-workflow/ch-08-development-rhythm.md), [Xiaomi practice](./docs/manual/part-03-workflow/ch-09-xiaomi-practice.md) | | **part-04-context** | [Memory system](./docs/manual/part-04-context/ch-10-memory-system.md), [Context window](./docs/manual/part-04-context/ch-11-context-window.md), [Context quality](./docs/manual/part-04-context/ch-12-context-quality.md) | | **part-05-extension** | [Skills](./docs/manual/part-05-extension/ch-13-skills.md), [Hooks](./docs/manual/part-05-extension/ch-14-hooks.md), [MCP](./docs/manual/part-05-extension/ch-15-mcp-integration.md), [Plugins](./docs/manual/part-05-extension/ch-16-plugins.md) | | **part-06-parallel** | [Multi-tasking](./docs/manual/part-06-parallel/ch-17-multi-task.md), [Worktree](./docs/manual/part-06-parallel/ch-18-worktree.md), [Pipeline](./docs/manual/part-06-parallel/ch-19-pipeline.md) | | **part-07-security** | [Permissions and approval](./docs/manual/part-07-security/ch-20-permissions.md), [Isolation and protection](./docs/manual/part-07-security/ch-21-isolation.md) | | **part-08-advanced** | [Output styles](./docs/manual/part-08-advanced/ch-22-output-styles.md), [Automation](./docs/manual/part-08-advanced/ch-23-automation.md), [Failure modes](./docs/manual/part-08-advanced/ch-24-failure-modes.md) | ### Practical Recipes | Recipe | Description | |------|------| | **[agents](./docs/recipes/agents/)** | Agent loop, tool use, subagent, skill loading, context compact, task system, background tasks, agent teams example code | | **[skills](./docs/recipes/skills/)** | Directly reusable SKILL.md templates: agent-builder, code-review, mcp-builder, pdf | | **[docs](./docs/recipes/docs/)** | Claude Code English and Chinese learning documents (en / zh) | | **[source-analysis](./docs/recipes/source-analysis/)** | Mainstream Agent Harness (OpenCode / Codex / DeerFlow) design comparison and reference | ### Agent Runtime Workshop | Chapter | Content | Theoretical study | Python implementation | Hands-on practice | |------|------|----------|-------------|----------| | ch-01 | Introduction to Coding Agent | [theory](./docs/workshop/chapters/ch-01-intro-to-coding-agent/theory.md) | [python](./docs/workshop/chapters/ch-01-intro-to-coding-agent/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-01-intro-to-coding-agent/hands-on.md) | | ch-02 | Let AI talk | [theory](./docs/workshop/chapters/ch-02-conversation-module/theory.md) | [python](./docs/workshop/chapters/ch-02-conversation-module/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-02-conversation-module/hands-on.md) | | ch-03 | Tool system | [theory](./docs/workshop/chapters/ch-03-tool-system/theory.md) | [python](./docs/workshop/chapters/ch-03-tool-system/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-03-tool-system/hands-on.md) | | ch-04 | Agent main loop | [theory](./docs/workshop/chapters/ch-04-agent-loop/theory.md) | [python](./docs/workshop/chapters/ch-04-agent-loop/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-04-agent-loop/hands-on.md) | | ch-06 | Permission system | [theory](./docs/workshop/chapters/ch-06-permissions/theory.md) | [python](./docs/workshop/chapters/ch-06-permissions/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-06-permissions/hands-on.md) | | ch-08 | Context management | [theory](./docs/workshop/chapters/ch-08-context-management/theory.md) | [python](./docs/workshop/chapters/ch-08-context-management/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-08-context-management/hands-on.md) | | ch-09 | Memory system | [theory](./docs/workshop/chapters/ch-09-memory-system/theory.md) | [python](./docs/workshop/chapters/ch-09-memory-system/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-09-memory-system/hands-on.md) | | ch-11 | Skill system | [theory](./docs/workshop/chapters/ch-11-skills/theory.md) | [python](./docs/workshop/chapters/ch-11-skills/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-11-skills/hands-on.md) | | ch-13 | SubAgent | [theory](./docs/workshop/chapters/ch-13-subagents/theory.md) | [python](./docs/workshop/chapters/ch-13-subagents/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-13-subagents/hands-on.md) | | ch-15 | Agent Teams | [theory](./docs/workshop/chapters/ch-15-agent-teams/theory.md) | [python](./docs/workshop/chapters/ch-15-agent-teams/python-implementation.md) | [hands-on](./docs/workshop/chapters/ch-15-agent-teams/hands-on.md) | Reference implementation: [mewcode/](./mewcode/) --- ## 🚀 Quick Start **Complete novice**: ``` Manual Chapter 1 (认识它) → Chapter 4 (会话管理) → Chapter 5 (项目级配置) → Chapter 6 (核心工作流) ``` **Want to build an Agent**: ``` Workshop ch-01 → ch-02 → ch-03 → ch-04 ↓ ch-06 → ch-08 → ch-09 ↓ ch-11 → ch-13 → ch-15 ``` **Want to improve stability**: ``` Manual Chapter 7 (五层安全开发闭环) → Chapter 10 (记忆系统) → Chapter 11 (上下文窗口管理) → Chapter 24 (常见失败模式与修复) ``` **Team landing**: ``` Manual Chapter 9 (小米 AI Coding 工程化实践) → Chapter 17-19 (多任务 / Worktree / 流水线) → Chapter 20-21 (权限与隔离) ``` --- ## 📁 Repository Structure ``` . ├── docs/ │ ├── assets/ # Banners, illustrations, Xiaomi practice diagrams │ ├── manual/ # 8-part user manual │ ├── recipes/ # Reusable recipes: agents / skills / docs / source-analysis │ └── workshop/ # Agent Runtime workshop tutorials │ └── chapters/ ├── harness/ # Agent Harness learning notes ├── mewcode/ # Python version Agent Runtime reference implementation ├── AGENTS.md # Repository maintenance specifications ├── LICENSE # MIT └── README.md # This file ``` --- ## 📝 Naming Conventions - **Directories**: `kebab-case` (`part-01-overview`, `query-loop-deep-dive`) - **Markdown files**: `kebab-case` - **Python modules**: `snake_case` - **Avoid**: Chinese file names, spaces --- ## ⚠️ Disclaimer The content of this repository is for learning, practice, and experience precipitation. All cited materials have been marked with their sources. This repository does not contain any commercially protected original source code. --- ## ⭐ Star History [](https://star-history.com/#vitoworleone/claude-code-handbook&Date)