Claude Code 扩展机制参考

Claude Code 没有类似 OpenCode definePlugin 的 Plugin（插件） API。它的“扩展“概念通过六个层次实现，从声明式配置到可打包分发的完整组件，复杂度逐层递增。

Claude Code 的扩展体系包含六个层次：CLAUDE.md（项目规则）→ Skills（可复用指令集）→ MCP 服务器（外部工具连接）→ Subagents（子任务代理）→ Hooks（生命周期事件）→ Plugins（打包分发）。所有层次均基于配置文件（Markdown / JSON / Shell 脚本），无需编译构建。

→ Claude Code 内置能力 提供了全貌概览。 → Claude Code 命令参考 列出了所有内置命令和捆绑 Skill（技能）。

扩展体系总览

OpenCode 对比：OpenCode 的扩展体系是 Plugin（代码级 Hook）→ Skill（指令级）→ MCP（工具级）三层架构，核心扩展点是 TypeScript definePlugin API。Claude Code 的扩展全部通过配置文件（JSON / Markdown / Shell 脚本）和外部进程（MCP 服务器）实现，没有 TypeScript 函数回调级别的代码扩展 API（如 OpenCode 的 definePlugin）。

CLAUDE.md — 项目规则与记忆

CLAUDE.md 是 Claude Code 最基础也最重要的扩展方式。它包含项目规范、构建命令、编码约定等信息，写入 Agent 的 System Prompt。

文件层级

写作原则

应当包含（✅）：

• 构建和测试命令（最高 ROI 的配置）
• 与默认不同的代码风格规则
• 项目特定的架构决策
• 环境变量和开发环境要求
• 常见陷阱和非显而易见的行为

不应包含（❌）：

• Claude 读代码就能推断的内容
• 标准语言约定（Claude 已经知道）
• 详细的 API 文档（改为链接引用）
• 逐文件的代码库描述

关键实践

对比 OpenCode：OpenCode 使用 AGENTS.md，单文件 + 项目级，不支持多级继承和子目录自动发现。

Skills — 可复用指令集

Skills 是 Claude Code 中封装可复用 AI 行为的单位。一个 Skill 就是一个包含 SKILL.md 的目录，支持 YAML frontmatter 声明触发条件、工具权限和执行模式。

核心格式

---
name: my-skill
description: 这个 Skill 做什么以及何时使用
allowed-tools: Read Grep Bash
disallowed-tools: Write Edit
context: fork
agent: Explore
---

# 指令内容

这里是 Skill 的核心指令...

三级加载设计

Frontmatter 关键字段

存储位置

动态上下文注入

---
description: 总结未提交的变更
---

## 当前变更
!`git diff HEAD`

## 指令
总结上述变更...

`!`command` 语法在 Claude 看到内容前执行 Shell 命令，输出替换占位符。适合注入实时数据。

与 OpenCode 对比

→ 自定义命令（.claude/commands/*.md）与 Skills 已统一。两者都会创建 /command-name，同名时 Skills 优先。

MCP 服务器 — 外部工具连接

MCP（Model Context（上下文） Protocol）是 Claude Code 连接外部世界的标准化协议。通过 MCP，Agent 可以查询数据库、调用 API、搜索网络，而不需要把能力硬编码到工具链里。

配置位置

传输类型

配置格式

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://..."]
    }
  }
}

CLI 管理

# 添加 MCP 服务器
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 设置环境变量
claude mcp set-env github-mcp GITHUB_TOKEN=ghp_...

# 列出已配置服务器
claude mcp list

# 启动自身作为 MCP 服务器
claude mcp serve

常用 MCP 服务器

→ MCP 服务器 章节有 OpenCode 中 MCP 的完整配置指南。 → Claude Code 生态参考 有更多 MCP 服务器推荐。

Subagents — 专用子 Agent

Subagents（子代理）是拥有独立上下文窗口、自定义 System Prompt 和受限工具访问的 Agent。主 Agent 通过 Task 工具委派任务给子 Agent，子 Agent 完成并以摘要形式返回结果。

工作原理

主会话（编排器）
  │
  ├── Task 调用 ──► Subagent A（独立上下文窗口）
  ├── Task 调用 ──► Subagent B（独立上下文窗口）
  └── Task 调用 ──► Subagent C（独立上下文窗口）
                           │
                      ▼ 摘要（~200 tokens）返回主会话

内置 Subagent 类型

自定义 Subagent 格式

---
name: security-reviewer
description: 安全分析专家，专注于认证和授权代码
model: sonnet
effort: medium
maxTurns: 20
tools: Read Grep Glob Bash
disallowedTools: Write Edit
memory: project
isolation: worktree
color: red
---

# System Prompt

你是一名安全专家，专注于认证漏洞...

## 审查清单
1. SQL 注入风险
2. XSS 漏洞
3. Session 管理缺陷

Frontmatter 关键字段

存储位置优先级

Hooks — 生命周期事件

Hooks 是 Claude Code 中的事件驱动自动化机制。在 Agent 生命周期的关键节点插入自定义逻辑，支持 Shell 脚本、LLM 评估、子 Agent 和 HTTP 请求四种执行类型。

完整事件列表

Hook 类型

配置格式

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE' && exit 2 || exit 0"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

实用 Hook 示例

拦截危险命令：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE' && exit 2 || exit 0"}]
    }]
  }
}

自动格式化文件：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""}]
    }]
  }
}

注入 Git 上下文：

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{"type": "command", "command": "echo '{\"additionalContext\": \"Branch: '$(git branch --show-current)'\"}'"}]
    }]
  }
}

退出码语义

对比 OpenCode：Claude Code Hooks 通过外部 Shell 进程执行，配置方式为 JSON 声明式；OpenCode Hooks 通过 definePlugin TypeScript API，在 Agent 进程内部以函数回调执行。Claude Code 的优势是无需编译，劣势是无法执行复杂运行时逻辑。

Plugins — 打包与分发

Plugin 是 Claude Code 扩展体系的最顶层，将 Skills、Subagents、Hooks、MCP 服务器等组件打包为可分发的单元。

Plugin 组件

Plugin 清单格式

{
  "name": "my-plugin",
  "displayName": "我的插件",
  "version": "1.0.0",
  "description": "插件描述",
  "author": { "name": "作者" },
  "skills": "./skills/",
  "agents": "./agents/",
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json"
}

插件安装

# 从市场安装
claude plugin install code-review@anthropic-agent-skills

# 本地路径安装
claude plugin install ./my-plugin

# 验证插件
claude plugin validate ./my-plugin --strict

# 重新加载
/reload-plugins

Skills-Directory 插件（零安装）

任何包含 .claude-plugin/plugin.json 的 Skills 目录子文件夹会自动加载为插件：

~/.claude/skills/
└── my-tool/
    ├── .claude-plugin/
    │   └── plugin.json    ← 自动识别为插件
    ├── skills/
    │   └── code-review/
    │       └── SKILL.md
    ├── agents/
    │   └── reviewer.md
    └── hooks/
        └── hooks.json

安装作用域

生态规模

完整 .claude/ 目录结构

your-project/
├── CLAUDE.md                       # 团队指令（提交到 Git）
├── CLAUDE.local.md                 # 个人覆盖（Gitignore）
└── .claude/
    ├── settings.json               # 权限 + 配置（提交到 Git）
    ├── settings.local.json         # 个人权限覆盖（Gitignore）
    ├── .mcp.json                   # MCP 服务器配置
    ├── rules/                      # 模块化规则文件
    │   ├── code-style.md
    │   └── testing.md
    ├── commands/                   # 自定义命令（已废弃，用 skills 替代）
    ├── skills/                     # 自动触发的工作流
    │   └── deploy/
    │       ├── SKILL.md
    │       └── deploy-config.md
    ├── agents/                     # 专用子 Agent
    │   ├── code-reviewer.md
    │   └── security-auditor.md
    └── hooks/                      # 事件驱动自动化
        └── validate-bash.sh

~/.claude/
├── CLAUDE.md                       # 全局指令（所有项目）
├── settings.json                   # 全局设置
├── skills/                         # 个人 Skill
├── agents/                         # 个人子 Agent
└── projects/                       # 项目记忆

扩展体系对比：Claude Code vs OpenCode

测试与调试

Subagent 测试工作流

自定义 Subagent 可直接通过 CLI 绕过主 Agent 单独测试：

claude --agent security-reviewer -p "Review this codebase"

使用 /fork 命令将子 Agent 的上下文 fork 到主会话，观察其内部决策。Hooks 配合 --debug 标志查看详细执行日志。

Hooks 调试

Hooks 是外部 Shell 进程，stdout/stderr 默认不可见。关键调试手段是显式写日志文件：

echo "[DEBUG] Hook fired for $CLAUDE_TOOL_NAME" >> /tmp/hook-debug.log

另一个终端运行 tail -f /tmp/hook-debug.log 实时观察。JSON 输出型 Hook 先用 jq 在命令行验证 JSON 合法性，再接入 Hook 系统。LLM Prompt Hook 可以用短 prompt 测试评估逻辑是否符合预期。

常见陷阱

CI 集成

使用社区工具 claude-code-hook-tester 在 CI 中自动测试所有 Hooks：向每个 Hook 发送模拟 JSON 载荷，验证退出码和 JSON 输出合法性。Subagent 和 Plugin 配置可通过 claude plugin validate ./my-plugin --strict 验证结构正确性。

常见反模式

Claude Code 六层扩展体系虽然灵活，但使用不当会引入额外复杂度：

Layer Skip（跳过层次）：越过低复杂度层次直接跳到高层次。例如遇到需要自定义行为时，跳过 CLAUDE.md（声明式规则）直接编写 Plugin（编程式扩展）。结果是一个简单的文件排除规则写了一整段 TypeScript 代码。正确路径是从最简方案开始：CLAUDE.md → Skills → MCP → Subagent → Hook → Plugin，逐层升级，每层满足需求了就不再往上。

配置碎片化：将相关规则分散到多个 CLAUDE.md 文件中，没有层次结构。例如在 root CLAUDE.md 中写 API 规则，在 src/api/CLAUDE.md 中又写了一遍，当两个规则冲突时 Agent 行为不可预测。应遵循“父层通用、子层专精“原则：根目录放全局规则，子目录放该目录独有的增量规则。

MCP 服务器当作万能胶：为每个小任务都启动一个 MCP 服务器。MCP 服务器的启动和维护开销远超直接使用内置工具。应区分：内置工具（Read/Write/Edit/Grep）能解决的不建 MCP；只有需要外部 API 或数据库访问时才引入 MCP 服务器。

适用场景与限制

适用场景：Claude Code 的六层扩展体系最适合渐进式深度定制。小团队从 CLAUDE.md 和 Skills 开始，随项目复杂度增长逐步引入 MCP 服务器和 Subagent，最后再考虑 Hook 和 Plugin。这种渐进式路径的学习曲线平缓，每个层次的引入都有明确的价值信号。

不适用场景：如果项目需要开箱即用的完整扩展方案（例如内置的自动代码审查流水线），Claude Code 的六层体系需要从零搭建，不如 OMO 的 Plugin + Skill 体系来得直接。此外，需要跨团队标准化扩展配置的场景下，Claude Code 缺乏集中分发机制。

限制说明：Claude Code 的扩展体系缺乏统一的调试和可视化工具。当六层扩展同时生效时，排查某条规则来自哪个层次需要逐层检查。此外，Hook 的执行性能不如 OMO 的进程内 Plugin——每次 Shell Hook 调用都会启动子进程，高频事件（如每次工具调用）的场景下性能影响明显。

常见错误与陷阱

CLAUDE.md 位置错误：把单个文件规则放在根 CLAUDE.md 中。Claude Code 支持目录级 CLAUDE.md，用于覆盖特定子目录的行为。常见错误是在根 CLAUDE.md 中用条件语句区分不同模块，这比目录级 CLAUDE.md 更难维护且更容易出错。

Skill 依赖关系未声明：安装了依赖其他 Skill 的 Skill，但没有在 dependencies 字段中声明。例如 “code-review” Skill 依赖 “testing-standards” Skill 中的命名约定，当两个 Skill 独立加载时，code-review 可能引用到不存在的约束条件。

Hook 执行时序依赖：注册了多个 Hook 依赖彼此的执行结果。例如 PreToolUse Hook 修改工具参数，PostToolUse Hook 期望 PreToolUse 已经修改了参数。如果 Hook 执行顺序不符合预期（注册顺序变更或异步问题），结果不可控。Hook 应该是幂等的——即使被多次调用或跳过，状态也应一致。

忽略扩展兼容性：同时使用 OMO Plugin 和 Claude Code Hook 时，没有检查两者的交互。例如 OMO 的 PostAgentResponse Hook 和 Claude Code 的 PostToolUse Shell Hook 可能修改同一个数据，导致覆盖。

关联章节

• → Claude Code 内置能力 — 命令、工具集、配置方式的完整参考
• → Claude Code 命令参考 — 内置命令和捆绑 Skill 的详细用法
• → Claude Code 生态参考 — 社区项目、最佳实践和集成工作流
• → OpenCode Plugin 系统参考 — OpenCode 插件系统对比参考
• → MCP 服务器 — MCP 协议在 OpenCode 中的配置和实践