From 338f6946e6eb49f0b51a770e19fb29908ca4d8f0 Mon Sep 17 00:00:00 2001 From: FNS Service Date: Thu, 23 Apr 2026 07:34:36 +0800 Subject: [PATCH] Update from Sync Service --- AI工程/claude-code-best-practice详解.md | 351 ++++++++++++++++++++++++ 1 file changed, 351 insertions(+) create mode 100755 AI工程/claude-code-best-practice详解.md diff --git a/AI工程/claude-code-best-practice详解.md b/AI工程/claude-code-best-practice详解.md new file mode 100755 index 0000000..9b84200 --- /dev/null +++ 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* \ No newline at end of file