chill_notes/AI工程/claude-code-best-practice详解.md

claude-code-best-practice 详解

From Vibe Coding to Agentic Engineering 的终极指南

归档：2026-04-23

---

📊 项目概览

项目	数据
仓库	https://github.com/shanraisshan/claude-code-best-practice
Stars	⭐ 47,397
Forks	4,662
描述	From vibe coding to agentic engineering - practice makes claude perfect
更新	2026-04-18
版本	Claude Code v2.1.114

---

🎯 核心定位

这是一个 Claude Code 最佳实践百科全书，覆盖：

类别	内容
Agents	子代理、前代理、后代理
Commands	75+ 内置命令
Skills	技能系统与官方技能
Workflows	编排工作流
Hooks	生命周期钩子
MCP	Model Context Protocol
Memory	持久化记忆系统
Settings	配置与权限

---

🤖 Subagents 详解

Frontmatter 字段（16个）

字段	类型	说明
name	string	唯一标识符（小写+连字符）
description	string	何时调用，使用 "PROACTIVELY" 自动触发
tools	list	允许的工具列表
disallowedTools	list	禁止的工具列表
model	string	模型选择（sonnet/opus/haiku/inherit）
permissionMode	string	权限模式
maxTurns	integer	最大交互次数
skills	list	预加载的技能
mcpServers	list	MCP 服务器配置
hooks	object	生命周期钩子
memory	string	持久记忆作用域
background	boolean	后台运行模式
effort	string	努力级别
isolation	string	"worktree" 隔离执行
initialPrompt	string	初始提示词
color	string	显示颜色

官方内置子代理（5个）

代理	模型	工具	用途
general-purpose	inherit	全部	复杂多步任务（默认）
Explore	haiku	只读	快速代码库搜索
Plan	inherit	只读	计划模式预研究
statusline-setup	sonnet	读写	配置状态栏
claude-code-guide	haiku	只读	回答 Claude Code 功能问题

---

⚡ Commands 详解

Frontmatter 字段（14个）

字段	类型	说明
name	string	显示名称
description	string	命令描述
when_to_use	string	触发场景描述
argument-hint	string	参数提示
disable-model-invocation	boolean	禁止自动调用
user-invocable	boolean	是否在菜单显示
paths	list	文件匹配模式
allowed-tools	string	允许的工具
model	string	模型选择
effort	string	努力级别
context	string	"fork" 隔离执行
agent	string	子代理类型
shell	string	脚本类型
hooks	object	钩子

官方内置命令（75个）

分类概览：

类别	数量	示例
Auth	4	/login, /logout, /upgrade
Config	12	/config, /theme, /tui
Context	5	/context, /cost, /insights
Git	7	/git, /diff, /branch
Edit	7	/rewrite, /review, /simplify
Navigate	7	/find, /search, /locate
Agent	8	/agent, /agents, /spawn
Session	8	/resume, /compact, /clear

---

🎓 Skills 详解

Frontmatter 字段（14个）

字段	类型	说明
name	string	显示名称
description	string	技能描述
when_to_use	string	使用场景
argument-hint	string	参数提示
disable-model-invocation	boolean	禁止自动调用
user-invocable	boolean	菜单可见性
allowed-tools	string	允许的工具
model	string	模型选择
effort	string	努力级别
context	string	"fork" 隔离执行
agent	string	子代理类型
hooks	object	钩子
paths	list	文件匹配模式
shell	string	脚本类型

官方内置技能（5个）

技能	用途
/simplify	代码审查与重构，消除重复
/batch	批量跨文件执行命令
/debug	调试失败命令或代码问题
/loop	循环执行提示词或命令（最长3天）
/claude-api	构建 Claude API 应用

---

💾 Memory 系统详解

CLAUDE.md 加载机制

Claude Code 使用两级加载机制：

向上加载（Ancestor Loading）

• 从当前工作目录向上遍历
• 找到的所有 CLAUDE.md 立即加载
• 启动时执行

向下加载（Descendant Loading）

• 子目录的 CLAUDE.md 不在启动时加载
• 只有当 Claude 读写这些目录的文件时才加载
• 懒加载

目录结构示例

/mymonorepo/
├── CLAUDE.md          # 根目录 - 所有组件共享
├── frontend/
│   └── CLAUDE.md      # 前端专用
├── backend/
│   └── CLAUDE.md      # 后端专用
└── api/
    └── CLAUDE.md      # API 专用

从根目录运行 vs 子目录运行

运行位置	根 CLAUDE.md	子目录 CLAUDE.md
/mymonorepo/	✅ 启动时加载	❌ 懒加载
/mymonorepo/frontend/	✅ 祖先加载	✅ 启动时加载

关键规则

1. ✅ 祖先始终加载 — 根级说明始终可用
2. ❌ 后代懒加载 — 按需加载，避免上下文膨胀
3. ❌ 兄弟不加载 — 同级目录不会相互加载
4. 🏠 全局 CLAUDE.md — ~/.claude/CLAUDE.md 适用于所有会话

最佳实践

位置	内容
根 CLAUDE.md	编码标准、提交规范、全局规则
组件 CLAUDE.md	框架特定模式、测试规范
CLAUDE.local.md	个人偏好（加入 .gitignore）

---

🪝 Hooks 系统

Hooks 是在代理循环外部运行的脚本：

触发时机	说明
PreToolUse	工具执行前
PostToolUse	工具执行后
Stop	停止时

Hook 类型：

• 脚本 — 可执行脚本
• HTTP — Webhook 调用
• Prompts — 提示词处理
• Agents — 子代理执行

---

🔌 MCP（Model Context Protocol）

MCP 服务器连接外部工具、数据源和 API：

// .mcp.json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@some/mcp-server"]
    }
  }
}

---

⚙️ 配置系统

设置层级

系统级 → 用户级 → 项目级 → 命令级

关键设置

设置	说明
Permissions	allow / ask / deny 规则
Model Config	模型选择
Output Styles	输出样式
Sandboxing	沙箱隔离
Keybindings	快捷键
Fast Mode	快速模式

---

🚀 高级功能

Beta 功能

功能	说明
Routines	云自动化（定时/API触发/GitHub事件）
Ultrareview	云端多代理代码审查
Devcontainers	开发容器
Channels	Telegram/Discord 集成
Ultraplan	云端计划协作
No Flicker Mode	无闪烁全屏渲染
Auto Mode	自动权限判断
Computer Use	屏幕控制
Agent SDK	构建生产级 AI 代理
Chrome	浏览器自动化
Claude Code Web	云端运行

自动化选项

方案	说明
Routines	云端定时/事件触发
Desktop Tasks	桌面端定时任务
Claude Code Web	云端会话

---

📁 项目结构

shanraisshan/claude-code-best-practice/
├── best-practice/           # 最佳实践文档
│   ├── claude-subagents.md
│   ├── claude-commands.md
│   ├── claude-skills.md
│   ├── claude-memory.md
│   ├── claude-mcp.md
│   ├── claude-settings.md
│   ├── claude-hooks.md
│   └── claude-power-ups.md
├── implementation/          # 实现示例
├── orchestration-workflow/  # 编排工作流
├── reports/                 # 研究报告
├── .claude/                # 配置示例
│   ├── agents/
│   ├── commands/
│   ├── skills/
│   └── settings.json
└── .mcp.json              # MCP 配置示例

---

🎯 使用建议

新手路径

1. 熟读 README 了解全貌
2. 从 Commands 开始练习
3. 尝试内置 Skills
4. 编写第一个 CLAUDE.md

进阶路径

1. 学习 Subagents 架构
2. 掌握 Memory 机制
3. 自定义 Hooks
4. MCP 服务器集成

专家路径

1. Agent Teams 协作
2. 自定义 Routines
3. 生产级 Agent SDK
4. 工作流自动化

---

🔗 相关资源

资源	链接
GitHub	https://github.com/shanraisshan/claude-code-best-practice
官方文档	https://code.claude.com/docs
Skills 市场	https://github.com/anthropics/skills
Claude Code	https://github.com/anthropics/claude-code

---

AI工程索引

相关笔记：

• INDEX_AI工程 - AI工程知识索引
• ClaudeCode完全研究 - Claude Code 完整指南
• 软件开发技能收集整理 - 技能资源汇总

---

整理：知识库管理员 | 归档：2026-04-23