Update from Sync Service

2026-04-23 07:34:36 +08:00
parent 4eb58661e5
commit 338f6946e6
1 changed files with 351 additions and 0 deletions
--- a/AI工程/claude-code-best-practice详解.md
+++ b/AI工程/claude-code-best-practice详解.md
@@ -0,0 +1,351 @@
+# 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*