Claude Code 源码学习笔记

学习时间: 2026-04-10 源码路径: C:\work\claude-code-main 项目类型: Claude Code 官方插件仓库

---

一、项目概览

1.1 项目定位

Claude Code 是 Anthropic 官方推出的 AI 编程助手，运行在终端中，通过自然语言命令帮助开发者理解代码库、执行常规任务、处理 Git 工作流、生成和修改代码。

1.2 项目结构

claude-code-main/ ├── plugins/ # 插件目录（核心） │ ├── agent-sdk-dev/ # Agent SDK 开发工具 │ ├── code-review/ # 代码审查插件 │ ├── commit-commands/ # Git 命令插件 │ ├── feature-dev/ # 功能开发插件 │ ├── hookify/ # Hook 创建工具 │ ├── plugin-dev/ # 插件开发工具包 │ ├── pr-review-toolkit/ # PR 审查工具包 │ ├── ralph-wiggum/ # 自迭代循环插件 │ └── security-guidance/ # 安全指导插件 ├── scripts/ # 工具脚本 ├── examples/ # 示例文件 └── README.md # 项目说明

---

二、插件系统架构

2.1 插件目录结构

plugin-name/ ├── .claude-plugin/ │ └── plugin.json # 插件清单（必需） ├── commands/ # 斜杠命令 │ └── *.md # 命令定义文件 ├── agents/ # 子代理定义 │ └── *.md # 代理定义文件 ├── skills/ # 技能模块 │ └── skill-name/ │ ├── SKILL.md # 技能定义（必需） │ ├── references/ # 参考文档 │ ├── examples/ # 示例文件 │ └── scripts/ # 工具脚本 ├── hooks/ # 事件钩子 │ ├── hooks.json # 钩子配置 │ └── scripts/ # 钩子脚本 └── .mcp.json # MCP 服务器定义

2.2 四大组件详解

Commands（命令）

用户可调用的斜杠命令，格式为 Markdown 文件 + YAML frontmatter。

关键字段:

• description: 命令描述

• allowed-tools: 允许使用的工具

• model: 指定模型（haiku/sonnet/opus）

• argument-hint: 参数提示

动态参数:

• $ARGUMENTS: 所有参数

• $1, $2, $3...: 位置参数

• @$1: 文件引用

Agents（代理）

专门的子代理，处理特定任务。

关键字段:

• name: 代理名称

• description: 代理描述（用于自动选择）

• tools: 可用工具列表

• model: 使用的模型

• color: UI 显示颜色

Skills（技能）

专业化知识包，自动激活。支持渐进式加载：

1. Metadata: 始终加载（~100词）

2. SKILL.md body: 触发时加载（<5k词）

3. Bundled resources: 按需加载

Hooks（钩子）

事件驱动的拦截器。

事件类型:

• PreToolUse: 工具使用前

• PostToolUse: 工具使用后

• Stop: 会话结束时

• SessionStart: 会话开始时

• UserPromptSubmit: 用户提交时

---

三、核心概念详解

3.1 Plugin Manifest

位置: .claude-plugin/plugin.json 必需字段: 仅 name 推荐字段: version, description, author, homepage, repository, license, keywords

3.2 Portable Path References

关键变量: ${CLAUDE_PLUGIN_ROOT}

确保插件可移植性，避免硬编码路径。

3.3 Auto-Discovery

Claude Code 自动发现和加载组件：

1. Plugin manifest: 读取 .claude-plugin/plugin.json

2. Commands: 扫描 commands/ 目录的 .md 文件

3. Agents: 扫描 agents/ 目录的 .md 文件

4. Skills: 扫描 skills/ 子目录中的 SKILL.md

5. Hooks: 加载 hooks/hooks.json

---

四、最佳实践

4.1 Command 开发规范

1. 指令给 Claude，不是用户

2. 单一职责：一个命令只做一件事

3. 参数验证：检查必需参数

4. 文档注释：说明用法和要求

4.2 Agent 开发规范

1. 明确的专业领域

2. 工具限制：只授予必要工具

3. 模型选择：根据任务复杂度选择

4. 输出结构化：提供清晰的结果格式

4.3 Skill 开发规范

1. SKILL.md 保持精简（1,500-2,000词）

2. 详细内容移到 references/

3. 示例放在 examples/

4. 使用祈使句/不定式写作

4.4 Hook 开发规范

1. 事件匹配：使用正则匹配工具名称

2. 条件过滤：使用 if 字段

3. 钩子脚本输出：JSON 格式

4. 超时设置：默认 30秒

---

五、实战案例

5.1 Hookify 插件

通过对话分析或用户指令，自动创建 Hook 规则。工作流程：用户调用 → 分析对话 → 确认行为 → 创建文件 → 立即生效。

5.2 Feature-Dev 插件

7 阶段引导式功能开发：

1. Discovery: 理解需求

2. Codebase Exploration: 代码库探索

3. Clarifying Questions: 澄清问题

4. Architecture Design: 架构设计

5. Implementation: 实施

6. Quality Review: 质量审查

7. Summary: 总结

5.3 Code-Review 插件

使用多个专门代理并行审查 PR。关键设计：

• 高信噪比：只报告置信度 ≥80 的问题

• 并行处理：多代理并行提高效率

• 验证机制：二次验证减少误报

5.4 Plugin-Dev 插件

完整的插件开发工具链，包含 7 个 Skills 和 3 个 Agents。

---

六、关键设计模式

6.1 渐进式加载模式

三级加载机制：

• Level 1: Metadata (name + description)

• Level 2: SKILL.md body (<5k words)

• Level 3: references/, examples/, scripts/

6.2 代理协作模式

多代理并行处理：用户请求 → 主 Agent 分解任务 → 并行启动子 Agents → 结果汇总 → 整合输出

6.3 Hook 拦截模式

事件驱动：事件触发 → 匹配器检查 → 条件过滤 → 执行脚本 → 返回结果

6.4 可移植性模式

使用环境变量 ${CLAUDE_PLUGIN_ROOT} 确保插件可移植。

---

七、对 OpenClaw 的启示

7.1 架构借鉴

1. 渐进式加载：三级加载机制

2. 代理协作：多代理并行处理

3. Hook 系统：事件驱动拦截器

4. 可移植路径：环境变量机制

7.2 实现建议

1. Skills 目录结构参考 Claude Code

2. 实现组件自动发现和加载

3. 文档分离到 references/

4. 提供完整可运行的示例

---

八、学习总结

核心收获

1. 完整的插件架构和组件设计

2. Commands、Agents、Skills、Hooks 的开发规范

3. 渐进式加载、代理协作、Hook 拦截等核心模式

4. 参数处理、Bash 执行、条件语法等实现细节

关键要点

1. 可移植性至关重要

2. 渐进式加载减少开销

3. 并行代理提高效率

4. 高质量 Skill 描述要具体明确

---

学习完成时间: 2026-04-10 文档版本: v1.0