Claude Code 扩展机制指南

作者:Atom

字数统计:5.9k 字

阅读时长:21 分钟

基于 Anthropic 官方文档和工程实践，全面解析 Claude Code 七大扩展机制的定位、使用场景与最佳实践。

为什么需要理解扩展机制？

Claude Code 不只是一个 CLI 工具——它是一个可编程的 AI 工程平台。通过 7 种扩展机制的组合，你可以将 Claude 从一个"聊天式助手"改造为一个符合团队规范、具备领域知识、能自主执行复杂工作流的工程伙伴。

但很多团队在使用时会遇到困惑：

什么时候用 Skill？什么时候用 Rule？
Agent 和 Skill 有什么区别？
如何让配置跨项目复用？

本文将逐一解答。

七大扩展机制一览

机制	加载时机	核心定位	类比
CLAUDE.md	每次会话自动	项目级"宪法"	`.editorconfig`
Rules	匹配路径时自动	模块化条件规则	ESLint 规则文件
Skills	按需/手动调用	可复用知识与工作流	VS Code Snippets + Tasks
Agents	委派时自动	隔离的专家子进程	微服务
Commands	`/command` 手动	快捷指令	Shell Alias
Hooks	事件触发，确定性	强制自动化	Git Hooks
MCP	会话启动时	外部工具集成	API Gateway

一、CLAUDE.md — 项目级"宪法"

官方文档

https://code.claude.com/docs/en/memory

定义与定位

CLAUDE.md 是 Claude Code 在每次会话开始时自动读取的项目指令文件。它包含 Claude 无法从代码本身推断的项目上下文——编码规范、构建命令、架构决策等。

加载层级（优先级从低到高）

~/.claude/CLAUDE.md              ← 个人全局（所有项目）
./CLAUDE.md                      ← 项目级（团队共享，提交到 Git）
./.claude/CLAUDE.md              ← 项目级（等效）
./CLAUDE.local.md                ← 本地个人（gitignore）
./子目录/CLAUDE.md               ← 按需加载（进入该目录时）

应该写什么

黄金法则

只写 Claude 无法从代码猜到的信息。

写	不写
非标准构建命令 `cd backend && ./gradlew bootRun`	标准语言惯例
禁止事项 "必须用 pnpm，禁止 npm"	"写干净的代码"
架构决策 "路由必须用 Hash 模式"	每个文件的详细描述
常见陷阱 "gradle.properties 禁止硬编码路径"	经常变动的信息
文件引用 `@rules/frontend.md`	长篇教程

大小控制

指标	推荐值
理想长度	100-200 行
警告阈值	800 行（Claude 可能忽略部分内容）
硬性上限	1500 行（必须拆分）

常见错误

把所有规范都塞进 CLAUDE.md。正确做法：用 @rules/xxx.md 引用外部文件，CLAUDE.md 只保留索引和核心约束。

文件引用语法

markdown

详细前端规范请参考 @rules/frontend.md
个人偏好配置见 @~/.claude/my-preferences.md

二、Rules — 模块化条件规则

官方文档

https://code.claude.com/docs/en/memory

定义与定位

Rules 是 CLAUDE.md 的模块化拆分。每个 .md 文件对应一个主题领域，支持通过 paths 前置元数据实现条件加载——只在操作匹配路径的文件时生效。

文件结构

.claude/rules/
├── frontend.md          # 前端规范
├── backend.md           # 后端规范
├── testing.md           # 测试规范
├── nodejs.md            # Node.js 规范
└── workflow.md          # 工作流规范

路径条件加载

yaml

---
paths:
  - "frontend/**"
  - "src/**/*.vue"
---

# 前端开发规则
- 路由必须使用 createWebHashHistory()
- 包管理器必须使用 pnpm
- 构建工具配置文件必须是 vite.config.ts

支持的 glob 语法

**/*.ts — 递归匹配所有 TypeScript 文件
src/**/*.{ts,tsx} — 花括号展开
backend/** — 匹配整个目录
!test/** — 排除模式（部分场景支持）

Rules vs CLAUDE.md

维度	CLAUDE.md	Rules
粒度	单一文件	多文件，按主题拆分
条件加载	不支持	支持 `paths` 过滤
适用场景	项目全局共识	特定领域/模块规范
大小	100-200 行	每文件 50-500 行

最佳实践

每个文件聚焦一个主题
单文件不超过 500 行
用 paths 限制作用域，避免全局污染
定期清理过时规则

三、Skills — 可复用知识与工作流

官方文档

https://code.claude.com/docs/en/skills

定义与定位

Skills 是 Claude Code 最灵活的扩展机制。每个 Skill 封装一组指令、模板、参考资料和辅助脚本，Claude 可以自动识别并应用，也可以通过 /skill-name 手动触发。

核心区别

Rules 是"始终遵守的法律"，Skills 是"按需调用的能力"。

文件结构

.claude/skills/skill-name/
├── SKILL.md           # 必需 — 主指令文件（YAML frontmatter + Markdown）
├── template.md        # 可选 — 输出模板
├── examples/          # 可选 — 示例输出
│   └── sample.md
├── references/        # 可选 — 按需加载的参考资料
│   └── api-docs.md
└── scripts/           # 可选 — 辅助脚本
    └── helper.py

YAML Frontmatter 配置

yaml

---
name: deploy-backend                    # 显示名称
description: "部署后端服务到远端"         # 必需 — Claude 据此判断何时使用
argument-hint: "[环境名]"               # 参数提示
disable-model-invocation: true          # 禁止 AI 自动触发（有副作用的操作）
user-invocable: true                    # 是否显示在 / 菜单中
allowed-tools: Read, Bash, Grep         # 限制可用工具
model: sonnet                           # 覆盖模型（sonnet/opus/haiku）
context: fork                           # 在子 Agent 中运行
agent: Explore                          # 子 Agent 类型
---

加载机制（重要）

关键理解

description 始终加载（消耗上下文预算），完整内容按需加载。所以 description 要精准简短，SKILL.md 可以很详细。

变量替换

变量	含义	示例
`$ARGUMENTS`	全部参数	`/deploy staging` → `staging`
`$ARGUMENTS[0]` 或 `$0`	第 N 个参数	—
`${CLAUDE_SESSION_ID}`	当前会话 ID	—

使用场景决策树

需要 Skill 吗？

├─ "这是可复用的领域知识" → ✅ Skill（user-invocable: false）
├─ "这是手动触发的工作流" → ✅ Skill（disable-model-invocation: true）
├─ "这个指令始终生效" → ❌ 用 Rules
├─ "这个操作必须确定性执行" → ❌ 用 Hooks
└─ "这需要隔离的专家上下文" → ✅ Skill + context: fork

最佳实践

SKILL.md 保持 500 行以内，详细参考资料放到 references/ 目录
有副作用的操作（部署、提交、发送消息）必须 disable-model-invocation: true
纯知识型 Skill（编码规范、设计模式）可设 user-invocable: false
复杂工作流用 context: fork 在子 Agent 中执行，保护主上下文
显式路径注入——在指令中明确告知 Claude 要读取的参考文件路径

四、Agents — 隔离的专家子进程

官方文档

https://code.claude.com/docs/en/sub-agents

定义与定位

Agents 是运行在独立上下文窗口中的专业子助手。每个 Agent 有自己的系统提示词、工具权限和 Token 预算，与主对话互不干扰。

核心区别

Skill 是"给主 Claude 的指令"，Agent 是"另一个独立的 Claude 实例"。

Skill vs Agent 对比

特性	Skill	Agent
上下文	共享主对话	独立上下文窗口
Token	消耗主会话 Token	独立 Token 预算
调用方式	`/skill-name` 或 AI 自动	`Task` 工具委派
适用场景	知识注入、短工作流	探索、重计算、并行任务
嵌套	可以引用其他 Skill	不能嵌套其他 Agent
工具限制	继承主会话	可独立配置

文件结构

.claude/agents/
├── code-reviewer.md
├── debugger.md
└── security/
    └── auditor.md

配置示例

yaml

---
name: qa-expert
description: "Playwright 测试与 API 测试专家。代码变更后主动使用。"
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit      # 只读探索，不改代码
model: sonnet                      # 使用更快的模型
permissionMode: default
maxTurns: 10
skills:
  - testing-standards              # 预加载 Skill（完整内容注入）
memory: project                    # 项目级持久记忆
isolation: worktree                # 在隔离的 Git worktree 中运行
---

你是一名资深 QA 工程师，专注于 Playwright UI 测试和 API 集成测试...

关键配置项

字段	说明	可选值
`tools`	允许使用的工具白名单	`Read, Write, Edit, Bash, Glob, Grep`
`disallowedTools`	禁止使用的工具	与 `tools` 二选一
`model`	使用的模型	`opus`, `sonnet`, `haiku`, `inherit`
`permissionMode`	权限模式	`default`, `acceptEdits`, `plan`
`maxTurns`	最大迭代次数	数字
`skills`	预注入的 Skill	Skill 名称数组
`memory`	跨会话记忆	`user`, `project`, `local`
`isolation`	运行隔离	`worktree`（独立 Git 分支）
`background`	是否后台运行	`true` / `false`

持久记忆

memory: user     → ~/.claude/agent-memory/          # 跨所有项目
memory: project  → .claude/agent-memory/             # 项目级，可提交 Git
memory: local    → .claude/agent-memory-local/       # 项目级，不提交

内置 Agent

Agent	模型	定位
Explore	Haiku（快速）	只读代码探索
Plan	—	研究和规划
general-purpose	—	通用多步骤任务

使用场景

需要 Agent 吗？

├─ "探索代码库，不想污染主对话" → ✅ Agent (Explore)
├─ "并行执行多个独立任务" → ✅ Agent (background: true)
├─ "需要限制工具权限" → ✅ Agent (tools/disallowedTools)
├─ "输出量大，怕爆上下文" → ✅ Agent (独立 Token 预算)
├─ "需要来回讨论迭代" → ❌ 主对话更合适
└─ "简单修改几行代码" → ❌ 直接在主对话操作

五、Commands — 快捷指令

官方文档

https://code.claude.com/docs/en/skills（Commands 已并入 Skills 体系）

定义与定位

Commands 是 Skills 的前身/简化版，通过 .claude/commands/ 目录创建 /slash-command 快捷指令。

注意

Commands 已被 Skills 体系合并。官方推荐新项目直接使用 Skills。Commands 仍向后兼容，但 Skills 支持更多功能（子目录、参考文件、脚本等）。

文件结构

.claude/commands/
├── debug.md
├── deploy.md
└── review/          # 支持分组
    ├── pr.md       # 调用方式: /review:pr
    └── code.md     # 调用方式: /review:code

Commands vs Skills

特性	Commands	Skills
位置	`.claude/commands/`	`.claude/skills/`
子目录资源	不支持	支持（references/, scripts/）
自动触发	不支持	支持（除非 disable-model-invocation）
优先级	低	高（同名时 Skill 优先）
状态	向后兼容	推荐

迁移建议

# 之前: .claude/commands/deploy.md
# 之后: .claude/skills/deploy/SKILL.md（可附带 references/ 和 scripts/）

六、Hooks — 确定性自动化

官方文档

https://code.claude.com/docs/en/hooks

定义与定位

Hooks 是事件驱动的 Shell 命令，在 Claude 的生命周期特定节点确定性执行。与 CLAUDE.md 中的指令不同，Hooks 保证 100% 触发，不依赖 AI 的判断。

核心区别

Rules/Skills 是"建议"，Hooks 是"法律"。

配置方式

在 .claude/settings.json 或 ~/.claude/settings.json 中配置：

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

可用事件

事件	触发时机	典型用途
`PreToolUse`	工具执行前	验证、阻止危险操作
`PostToolUse`	工具执行后	格式化、Lint、测试
`UserPromptSubmit`	用户发送提示前	验证、上下文增强
`SessionStart`	会话开始	环境初始化
`SessionEnd`	会话结束	清理、日志
`Stop`	响应结束	通知、报告
`SubagentStart`	子 Agent 启动	Agent 环境准备
`SubagentStop`	子 Agent 完成	Agent 清理

退出码语义

退出码	含义	行为
`0`	成功	继续执行
`1`	警告	非阻塞，继续执行
`2`	错误	阻断操作

Matcher 过滤

json

{
  "matcher": "Edit|Write",          // 仅匹配 Edit 和 Write 工具
  "hooks": [...]
}

实战示例

文件保存后自动 Lint阻止删除 main 分支会话结束通知

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo $CLAUDE_BASH_COMMAND | grep -q 'branch -D main' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude 完成了任务\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

使用场景

需要 Hook 吗？

├─ "每次编辑文件后必须 lint" → ✅ Hook (PostToolUse + Edit|Write)
├─ "阻止某些危险操作" → ✅ Hook (PreToolUse, exit 2)
├─ "编码风格建议" → ❌ 用 Rules（Hooks 太重了）
├─ "复杂的条件判断" → ❌ 用 Skills（Shell 不适合复杂逻辑）
└─ "确保操作零遗漏" → ✅ Hook（确定性执行）

七、MCP — 外部工具集成

官方文档

https://code.claude.com/docs/en/mcp

定义与定位

MCP（Model Context Protocol）是 Anthropic 推出的开放标准协议，让 Claude 可以连接外部工具、数据库和 API。它解决的是 N×M 集成问题——多个 AI 工具 × 多个外部服务。

配置方式

命令行添加项目配置 .mcp.json

bash

# HTTP 远程服务
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Stdio 本地进程
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://..."

json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://..."]
    }
  }
}

传输协议

协议	场景	推荐度
HTTP	远程云服务	推荐
Stdio	本地进程	推荐
SSE	服务端推送	已废弃，迁移到 HTTP

常用 MCP 服务器

服务	用途
GitHub	Issues、PR、代码审查
Sentry	错误监控
Notion	文档、数据库
Slack	消息通知
PostgreSQL / MySQL	数据库查询
Figma	设计稿
Jira	任务管理

动态工具加载

当 MCP 工具数量超过上下文窗口 10% 时，Claude Code 自动启用 Tool Search——工具描述按需加载，不预加载全部。

机制选择决策树

快速参考表

场景	推荐机制	理由
"必须用 pnpm，禁止 npm"	Rules	编码规范，路径匹配
"后端必须用 JDK 24"	CLAUDE.md	全局约束
"一键部署到远端服务器"	Skill (disable-model-invocation)	有副作用的手动工作流
"代码审查专家"	Agent	需要隔离上下文、限制工具
"每次编辑后自动 lint"	Hook	确定性执行
"查询 Jira 任务状态"	MCP	外部服务集成
"React 到 Vue 转换规范"	Skill (user-invocable: false)	领域知识，AI 自动应用
"从需求到交付全自动"	Skill + Agent 编排	复杂工作流

加载时机与上下文管理

什么时候加载什么

组件	加载时机	加载量	上下文影响
CLAUDE.md	会话启动	完整内容	始终占用
Rules（匹配路径）	会话启动	匹配的规则	始终占用
Auto Memory	会话启动	前 200 行	始终占用
Skill descriptions	会话启动	所有描述	始终占用（注意控制数量）
Skill 完整内容	手动/AI 触发时	单个 Skill	按需加载
Agent	委派时	独立上下文	不影响主对话
MCP 工具	会话启动	预加载/按需	Tool Search 优化
Hooks	事件触发	Shell 命令	不占上下文

上下文预算陷阱

所有 Skill 的 description 会在每次会话开始时加载。如果你有 50 个 Skill，每个 description 100 字，就是 5000 字的固定消耗。保持 description 精准简短。

实战案例：Autopilot Skill 分析

下面以一个真实的 autopilot（全自动需求到交付）Skill 为例，分析其设计得失。

架构概览

.claude/skills/autopilot/
├── SKILL.md                      # 主编排文件（370 行）
├── phases/
│   ├── enforcement.md            # 阶段门禁协议（198 行）
│   ├── testing-requirements.md   # 测试设计规范（122 行）
│   ├── ralph-loop-config.md      # 循环实施配置（144 行）
│   └── reporting.md              # 报告生成规范（161 行）
└── references/
    ├── test-credentials.md       # 测试凭据
    └── playwright-standards.md   # Playwright 规范

总计 7 个文件，约 1000+ 行指令，编排 8 个阶段的全自动流水线。

设计亮点

1. 子 Agent 编排契约（四种模式）

模式 1：结构化 JSON 返回——子 Agent 必须返回 {status, summary, artifacts} 信封
模式 2：显式路径注入——dispatch 时在 prompt 中列明所有参考文件路径
模式 3：磁盘 checkpoint——每个阶段写入 JSON 状态文件，支持崩溃恢复
模式 4：三层强制门禁——Task blockedBy + 磁盘校验 + 8 步切换清单

这套编排契约解决了 AI 子 Agent 的三大痛点：返回格式不确定、找不到参考文件、状态丢失无法恢复。

2. 认知捷径免疫

明确列出 AI 可能产生的"跳过冲动"并强制阻断：

危险想法	强制行为
"只是 UI 改动，不需要测试"	Phase 4 强制执行
"直接实现更快"	必须走 Ralph Loop
"测试报告太重了"	Phase 6 零跳过门禁

这是对抗 LLM 倾向性的高级技巧。

3. 文件拆分策略

将 1000+ 行指令拆分为 7 个文件，遵循 Skill 的最佳实践：

SKILL.md（370 行）作为主编排入口
phases/ 目录存放各阶段的详细规范
references/ 目录存放共享参考数据
子 Agent 通过显式路径注入按需读取

这避免了将所有内容塞入单一 SKILL.md 导致上下文爆炸。

存在的问题

问题 1：SKILL.md 本身过重（370 行）

官方建议 SKILL.md 保持 500 行以内，当前已接近上限。更关键的是，每次调用都会将 370 行全部加载到上下文，包含大量重复的协议说明。

建议：将"子 Agent 编排契约"（模式 1-4）抽取为独立的 phases/orchestration-protocol.md，SKILL.md 只保留阶段概览和调度逻辑。

问题 2：过度依赖 AI 遵守流程

尽管设计了三层门禁，但核心执行者仍是 AI。AI 可能：

生成格式不符的 JSON 信封
在 8 步切换清单中遗漏步骤
在崩溃恢复时误判 checkpoint 状态

建议：将关键门禁验证迁移到 Hooks。例如，Phase 切换时通过 PreToolUse Hook 验证 checkpoint 文件是否存在，而不是依赖 AI "记得"去验证。

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/skills/autopilot/scripts/validate-phase-gate.sh"
          }
        ]
      }
    ]
  }
}

问题 3：缺乏外部状态管理

当前所有状态通过磁盘 JSON 文件 + Task 系统 + AI 记忆三重保证，但：

Task 系统是会话内存，不跨会话
磁盘 JSON 需要 AI 主动读写
没有外部进程监控执行进度

建议：考虑引入 MCP 服务器作为状态管理层，或使用 Hook 在每个阶段完成时写入标准化状态文件。

问题 4：单个 Skill 承担了 Agent 编排器的职责

Autopilot 本质上是一个多 Agent 编排系统，但它被实现为一个 Skill。这导致：

主对话上下文持续消耗在编排协议上
所有编排逻辑由 AI 解释执行，缺乏程序化保证
难以测试和调试单个阶段

建议：将 autopilot 重构为一个顶层 Agent（.claude/agents/autopilot.md），利用 Agent 的 skills 字段预注入编排规范，maxTurns 控制执行上限。各阶段的子 Agent 也改为正式 Agent 定义。

yaml

---
name: autopilot
description: "全自动从需求到交付流水线"
tools: Read, Write, Edit, Bash, Glob, Grep, Task
model: opus
maxTurns: 50
skills:
  - autopilot-orchestration    # 编排协议
  - testing-requirements       # 测试规范
memory: project                # 跨会话记忆
---

问题 5：依赖不存在的插件

Phase 5 依赖 ralph-loop 插件，但这是一个自定义插件而非 Claude Code 官方插件。如果插件不可用或行为变化，整个 Phase 5 将失败。

建议：增加 fallback 路径——当 ralph-loop 不可用时，回退到手动循环调用 /opsx:apply。

改进架构建议

改进后的架构:

.claude/
├── agents/
│   └── autopilot.md              # 顶层编排 Agent（200 行）
├── skills/
│   ├── autopilot-phases/
│   │   ├── SKILL.md              # 阶段编排协议（作为知识注入）
│   │   ├── phases/               # 各阶段详细规范
│   │   └── references/           # 共享参考资料
│   ├── test-design/              # 独立的测试设计 Skill
│   └── report-generation/        # 独立的报告生成 Skill
├── hooks/
│   └── phase-gate-validator.sh   # 阶段门禁的确定性验证
└── settings.json                 # Hook 配置

核心改进：

Agent 做编排，Skill 做知识注入，Hook 做门禁验证
每个阶段可独立测试和复用
门禁验证从"AI 自觉"变为"确定性执行"

跨项目复用方案

方案 1：Claude Code Plugin（官方推荐）

最佳方案

Claude Code 有官方的 Plugin Marketplace 系统，这是复用配置的最佳途径。

Plugin 能封装什么

组件	支持
Skills	✅
Agents	✅
Commands	✅
Hooks	✅
MCP 服务器	✅
Rules	部分（通过 Skill 注入）

创建 Plugin

Plugin 以 GitHub 仓库为载体，通过 Marketplace 分发：

your-org/claude-plugins/
├── marketplace.json         # 插件注册表
├── plugins/
│   ├── autopilot/
│   │   ├── plugin.json      # 插件元数据
│   │   └── skills/          # 打包的 Skills
│   ├── testing-toolkit/
│   │   ├── plugin.json
│   │   ├── skills/
│   │   └── agents/
│   └── deploy-suite/
│       ├── plugin.json
│       ├── skills/
│       └── hooks/

安装与使用

bash

# 添加自定义 Marketplace
/plugin marketplace add your-org/claude-plugins

# 安装插件
/plugin install autopilot@your-org

# 查看已安装插件
/plugin list

安装作用域

作用域	位置	共享范围
User	`~/.claude/settings.json`	所有个人项目
Project	`.claude/settings.json`	团队共享（Git）
Local	本地	个人，不共享
Managed	系统	组织级管理

方案 2：Git Symlinks（轻量级）

对于不需要 Marketplace 分发的场景，可以用符号链接共享：

bash

# 共享 Rules
ln -s ~/shared-claude-rules .claude/rules/shared

# 共享单个 Skill
ln -s ~/claude-skills/autopilot .claude/skills/autopilot

# 共享 Agent 定义
ln -s ~/claude-agents/qa-expert.md .claude/agents/qa-expert.md

局限

依赖本地文件系统，不能通过 Git 分享给团队
更新需要手动同步
不支持版本控制

方案 3：MCP Server（可编程工具封装）

当你需要封装的不只是指令，还包括可执行逻辑时，MCP Server 是更好的选择：

typescript

// mcp-server/src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "vibeflow-tools",
  version: "1.0.0"
});

// 注册自定义工具
server.tool("deploy", { env: z.string() }, async ({ env }) => {
  // 执行部署逻辑
  return { content: [{ type: "text", text: `Deployed to ${env}` }] };
});

server.tool("run-tests", { suite: z.string() }, async ({ suite }) => {
  // 执行测试
  return { content: [{ type: "text", text: `Tests passed` }] };
});

配置到项目中：

json

// .mcp.json
{
  "mcpServers": {
    "vibeflow-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "./mcp-server/src/index.ts"]
    }
  }
}

优势

用 TypeScript/Python 编写复杂逻辑
跨项目复用（发布为 npm 包）
可编程的工具，而不仅仅是文本指令
社区生态丰富（100+ 官方和社区 MCP Server）

方案对比

维度	Plugin	Symlinks	MCP Server
封装粒度	Skills + Agents + Hooks	文件级	可执行工具
团队分享	✅ Marketplace	❌ 本地	✅ npm 包
版本管理	✅ Git tag	❌	✅ semver
复杂逻辑	Markdown 指令	Markdown 指令	TypeScript/Python
学习成本	低	极低	中
推荐场景	团队标准化	个人复用	工具化封装

社区模板参考

项目	特色
serpro69/claude-starter-kit	预配置 MCP + Skills + Agents + Hooks
zbruhnke/claude-code-starter	按技术栈（TS/Python/Go/Rust）预设
affaan-m/everything-claude-code	Anthropic 黑客松获奖配置
trailofbits/claude-code-config	专业团队工作流
halans/cc-marketplace-boilerplate	Plugin 开发模板

总结：构建你的 Claude Code 工程化体系

分层架构

┌────────────────────────────────────────┐
│          MCP（外部集成层）               │
│    GitHub · Sentry · DB · Slack        │
├────────────────────────────────────────┤
│          Hooks（确定性保障层）            │
│    Lint · Gate · Notification          │
├────────────────────────────────────────┤
│          Agents（专家执行层）            │
│    QA · Architect · Debugger           │
├────────────────────────────────────────┤
│          Skills（能力封装层）            │
│    Deploy · Test · Review · Autopilot  │
├────────────────────────────────────────┤
│          Rules（条件规范层）             │
│    Frontend · Backend · Node · Testing │
├────────────────────────────────────────┤
│          CLAUDE.md（全局约束层）          │
│    Tech Stack · Commands · Constraints │
└────────────────────────────────────────┘

核心原则

CLAUDE.md 保持精炼——只写 Claude 猜不到的，200 行以内
Rules 做条件过滤——按路径匹配，模块化拆分
Skills 做能力封装——可复用的知识和工作流
Agents 做隔离执行——独立上下文，专家委派
Hooks 做确定性保障——关键操作零遗漏
MCP 做外部连接——集成第三方服务和工具
Plugin 做跨项目复用——团队标准化分发

记住

越确定性的行为用越底层的机制（Hook > Rule > Skill > Agent prompt）。 越灵活的行为用越高层的机制（Agent > Skill > Rule > Hook）。

Claude Code 扩展机制指南 ​

为什么需要理解扩展机制？ ​

七大扩展机制一览 ​

一、CLAUDE.md — 项目级"宪法" ​

定义与定位 ​

加载层级（优先级从低到高） ​

应该写什么 ​

大小控制 ​

文件引用语法 ​

二、Rules — 模块化条件规则 ​

定义与定位 ​

文件结构 ​

路径条件加载 ​

Rules vs CLAUDE.md ​

最佳实践 ​

三、Skills — 可复用知识与工作流 ​

定义与定位 ​

文件结构 ​

YAML Frontmatter 配置 ​

加载机制（重要） ​

变量替换 ​

使用场景决策树 ​

最佳实践 ​

四、Agents — 隔离的专家子进程 ​

定义与定位 ​

Skill vs Agent 对比 ​

文件结构 ​

配置示例 ​

关键配置项 ​

持久记忆 ​

内置 Agent ​

使用场景 ​

五、Commands — 快捷指令 ​

定义与定位 ​

文件结构 ​

Commands vs Skills ​

迁移建议 ​

六、Hooks — 确定性自动化 ​

定义与定位 ​

配置方式 ​

可用事件 ​

退出码语义 ​

Matcher 过滤 ​

实战示例 ​

使用场景 ​

七、MCP — 外部工具集成 ​

定义与定位 ​

配置方式 ​

传输协议 ​

常用 MCP 服务器 ​

动态工具加载 ​

机制选择决策树 ​

快速参考表 ​

加载时机与上下文管理 ​

什么时候加载什么 ​

实战案例：Autopilot Skill 分析 ​

架构概览 ​

设计亮点 ​

存在的问题 ​

改进架构建议 ​

跨项目复用方案 ​

方案 1：Claude Code Plugin（官方推荐） ​

Plugin 能封装什么 ​

创建 Plugin ​

安装与使用 ​

安装作用域 ​

方案 2：Git Symlinks（轻量级） ​

方案 3：MCP Server（可编程工具封装） ​

方案对比 ​

社区模板参考 ​

总结：构建你的 Claude Code 工程化体系 ​

分层架构 ​

核心原则 ​

参考链接 ​

Claude Code 扩展机制指南

为什么需要理解扩展机制？

七大扩展机制一览

一、CLAUDE.md — 项目级"宪法"

定义与定位

加载层级（优先级从低到高）

应该写什么

大小控制

文件引用语法

二、Rules — 模块化条件规则

定义与定位

文件结构

路径条件加载

Rules vs CLAUDE.md

最佳实践

三、Skills — 可复用知识与工作流

定义与定位

文件结构

YAML Frontmatter 配置

加载机制（重要）

变量替换

使用场景决策树

最佳实践

四、Agents — 隔离的专家子进程

定义与定位

Skill vs Agent 对比

文件结构

配置示例

关键配置项

持久记忆

内置 Agent

使用场景

五、Commands — 快捷指令

定义与定位

文件结构

Commands vs Skills

迁移建议

六、Hooks — 确定性自动化

定义与定位

配置方式

可用事件

退出码语义

Matcher 过滤

实战示例

使用场景

七、MCP — 外部工具集成

定义与定位

配置方式

传输协议

常用 MCP 服务器

动态工具加载

机制选择决策树

快速参考表

加载时机与上下文管理

什么时候加载什么

实战案例：Autopilot Skill 分析

架构概览

设计亮点

存在的问题

改进架构建议

跨项目复用方案

方案 1：Claude Code Plugin（官方推荐）

Plugin 能封装什么

创建 Plugin

安装与使用

安装作用域

方案 2：Git Symlinks（轻量级）

方案 3：MCP Server（可编程工具封装）

方案对比

社区模板参考

总结：构建你的 Claude Code 工程化体系

分层架构

核心原则

参考链接