351 lines
9.2 KiB
Markdown
Executable File
351 lines
9.2 KiB
Markdown
Executable File
# 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* |