# 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：

```json
// .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*