🎼 Claude Code 编排工具包

用于 Claude Code 的专业自动化和编排系统

完整的工具包包括 33+ AI 代理、质量门控、健康监控 和 工作流自动化，用于构建健壮且生产就绪的项目。

---

📋 目录

• 概述
• 特性
• 关键创新
• 快速开始
• 安装
• 文档
• MCP 服务器配置
• 项目结构
• 斜杠命令
• 代理生态系统
• 技能库
• 使用示例
• 配置
• 最佳实践
• 故障排除
• 贡献
• 许可证

---

🎯 概述

Claude Code 编排工具包 是一个全面的自动化框架，旨在通过 Claude Code 加速您的开发工作流程。它提供：

• 🤖 33+ 专用 AI 代理 — 虫害、安全、依赖项、死代码清理等的编排器和工作者
• ⚡ MCP 服务器管理 — 针对不同用例的 6 个预配置的 MCP 设置（600-5000 令牌）
• 🔧 20+ 斜杠命令 — 健康检查、SpecKit、工作树管理、发布
• 📊 质量门控 — 自动类型检查、构建、测试、覆盖率、安全审计
• 🎯 技能库 — 15+ 可重用的验证、报告和自动化工具
• 📈 健康监控 — 跟踪代理性能、成功率和生态系统健康状况

---

✨ 特性

🤖 AI 代理生态系统

• 健康编排器 — 完整的工作流用于虫害、安全、依赖项、死代码
• 开发工作者 — LLM 服务、TypeScript 类型、成本计算专家
• 测试工作者 — 集成测试、性能优化、移动响应性
• 数据库工作者 — Supabase 审计、API 构建器、数据库架构
• 基础设施工作者 — Qdrant、质量验证者、编排逻辑
• 元工作者 — 代理创建者、技能构建者

⚙️ MCP 服务器配置

根据需要在 6 个优化的 MCP 配置之间切换：

配置	服务器	令牌使用	使用场景
基础	上下文7 + 顺序思维	~600	最小化日常使用
Supabase	基础 + Supabase（单个）	~2500	数据库工作
Supabase-全	基础 + Supabase（双）	~3000	多项目数据库
N8N	基础 + n8n 自动化	~2500	工作流自动化
前端	基础 + Playwright + ShadCN	~2000	UI/UX 开发
全部	所有服务器启用	~5000	最大能力

🚀 斜杠命令

• 健康检查 — /health-bugs，/health-security，/health-deps，/health-cleanup，/health-metrics
• SpecKit — /speckit.analyze，/speckit.specify，/speckit.implement，/speckit.checklist
• 工作树管理 — /worktree-create，/worktree-list，/worktree-cleanup，/worktree-remove
• 发布管理 — /push（自动版本提升和变更日志）
• 翻译 — /translate-doc（英语 ↔ 俄语）

📊 质量门控

自动化验证脚本：

• 捆绑大小检查 — 确保生产捆绑包保持在限制内
• 安全审计 — 扫描高/关键 npm 漏洞
• 代码覆盖率 — 验证测试覆盖率是否达到阈值

🎯 技能库

可重用工具：

• 计划验证、报告生成、变更日志创建
• Git 操作、错误解析、模板渲染
• 质量门控执行、回滚管理
• 优先级评分、版本提取

---

🔑 关键创新

🎯 编排模式

范式转变：将 Claude Code 从直接做一切转变为作为将复杂任务委托给专门子代理的编排器。

为什么重要：

• 上下文保存：主 Claude Code 保持精简（~10-15K 令牌 vs 标准使用中的 50K+）
• 专业化：每个子代理在其领域是专家（修复漏洞、扫描安全、数据库架构）
• 质量保证：每次委托后强制验证（读取文件 + 运行类型检查）
• 无限工作：可以在项目上无限期工作而不会耗尽上下文

核心规则（来自 CLAUDE.md）：

1. 首先收集完整上下文 — 在委托之前阅读代码、搜索模式、检查提交
2. 委托给子代理 — 提供完整上下文 + 验证标准
3. 验证结果 — 绝不跳过验证（读取修改后的文件，运行类型检查）
4. 接受/拒绝循环 — 如果验证失败，则重新委托并进行修正
5. 按任务提交 — 每完成一项任务后运行 /push patch

📋 SpecKit 增强：规划阶段 0

SpecKit（由 GitHub 提供）提供了结构化的开发工作流程。我们增强了它，增加了 规划阶段 0。

规划阶段 0 责任：

1. 执行者分配：

   • [EXECUTOR: 主] — 只有简单的任务（1-2 行修复，简单导入）
   • [EXECUTOR: 现有代理] — 如果与现有子代理完全匹配
   • [EXECUTOR: 将来代理名称] — 如果没有匹配（代理需要创建）

2. 元代理创建：

   • 在单条消息中启动 N 个 meta-agent-v3 调用来并行创建代理
   • 原子性规则：1 任务 = 1 代理调用
   • 创建后：请求用户重启 Claude Code

3. 研究解决：

   • 简单研究：代理使用可用工具解决问题
   • 复杂研究：在 research/ 目录中创建提示

为什么重要：确保在实施开始前存在所有必要的代理，使并行任务执行成为可能，防止上下文溢出。

🤖 元代理：代理工厂

meta-agent-v3 在 2-3 分钟内根据项目模式创建新的专用代理：

• 工作者 — 从计划文件执行任务（5 阶段结构）
• 编排器 — 协调多阶段工作流（返回控制模式）
• 简单代理 — 独立工具

如何工作：

1. 加载架构文档（ARCHITECTURE.md + CLAUDE.md）
2. 确定代理类型和需求
3. 生成 YAML 前置 + 结构 + 验证 + 错误处理
4. 写入适当位置
5. 验证是否符合项目模式

🔄 返回控制模式

编排器协调工作流而不直接调用工作者：

编排器 → 创建计划文件 → 发送准备就绪信号 → 退出
↓
主会话 → 通过任务工具调用工作者
↓
工作者 → 执行 → 验证 → 报告 → 退出
↓
编排器 → 恢复 → 验证 → 下一阶段

为什么不使用任务工具？使用任务工具会导致嵌套上下文，破坏隔离目的。

⚙️ 动态 MCP 切换

问题：每个 MCP 服务器消耗 500-1500 令牌的上下文预算。

解决方案：switch-mcp.sh 脚本在 6 个配置之间动态切换：

• 基础（~600 令牌）：上下文7 + 顺序思维（日常使用）
• Supabase（~2500）：+ Supabase（数据库工作）
• 前端（~2000）：+ Playwright + ShadCN（UI 工作）
• 全部（~5000）：所有服务器（当需要时）

好处：通过仅加载所需内容节省 500-4500 上下文令牌。

🌳 工作树 + VS Code 集成

并行功能开发：

1. 为不同功能创建工作树：/worktree-create feature/new-auth
2. 将 .worktrees/* 添加到 VS Code 工作区文件夹（参见 .claude/settings.local.json.example）
3. 通过文件夹选择器切换功能
4. 并行运行多个 Claude Code 会话

好处：3-5 个功能并行，无上下文污染，独立测试。

🔔 Webhook 集成

任务完成通知（.claude/settings.local.json.example）：

{
  "hooks": {
    "停止": [
      {
        "类型": "命令",
        "命令": "notify-send 'Claude Code' '任务已完成！'"
      }
    ]
  }
}

使用场景：Slack 通知、系统警报、Telegram 机器人、日志文件。

好处：开始任务，切换到其他项目，任务完成后收到通知。

🎯 技能 vs 代理

技能（15+）：可重用工具（<100 行），无状态，通过 Skill 工具调用

• 示例：run-quality-gate，validate-plan-file，generate-report-header
• 无上下文隔离，在调用者的上下文中运行

代理（33+）：有状态工作流，上下文隔离，通过 Task 工具调用

• 示例：bug-hunter，security-scanner，database-architect
• 完全上下文隔离，多步过程

📐 非传统的 CLAUDE.md

标准做法：在 CLAUDE.md 中存储整个项目历史

• 问题：浪费上下文令牌在历史数据上

我们的创新：CLAUDE.md 作为行为操作系统

• 仅包含编排规则（无项目历史）
• 定义如何在委托前收集上下文
• 规定在委托后进行验证规则
• 强制上下文保存

结果：主 Claude Code 保持精简，所有上下文按需收集。

---

🚀 快速开始

# 1. 克隆或下载此仓库
git clone https://github.com/maslennikov-ig/claude-code-orchestrator-kit.git
cd claude-code-orchestrator-kit

# 2. 设置环境变量
cp .env.example .env.local
# 编辑 .env.local 以包含您的凭据

# 3. 选择 MCP 配置
./switch-mcp.sh
# 根据需要选择选项 1-6

# 4. 重启 Claude Code
# 您的编排系统已准备好！

---

📦 安装

先决条件

• 已安装 Claude Code
• Node.js 18+（用于 MCP 服务器）
• Docker（可选，用于 n8n MCP 服务器）
• Git（用于版本控制功能）

设置步骤

1️⃣ 复制到您的项目

# 选项 A：将整个 .claude 目录复制到您的项目
cp -r claude-code-orchestrator-kit/.claude /path/to/your/project/

# 选项 B：克隆并用作模板
git clone https://github.com/maslennikov-_ig/claude-code-orchestrator-kit.git my-project
cd my-project
rm -rf .git
git init

2️⃣ 配置环境变量

# 复制示例到本地
cp .env.example .env.local

# 编辑以包含您的凭据
# Supabase 所需：
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_ACCESS_TOKEN=your-token
SUPABASE_DB_PASSWORD=your-password

# 顺序思维所需：
SEQUENTIAL_THINKING_KEY=your-smithery-key
SEQUENTIAL_THINKING_PROFILE=your-profile

# n8n 可选：
N8N_API_URL=https://your-n8n.com
N8N_API_KEY=your-n8n-key

重要：不要将 .env.local 提交到 git！它已经在 .gitignore 中了。

3️⃣ 选择 MCP 配置

./switch-mcp.sh

根据您的工作流程选择配置：

• 选项 1 — 基础（最小，~600 令牌）
• 选项 2 — Supabase（数据库工作）
• 选项 3 — Supabase-全（多项目）
• 选项 4 — N8N（自动化工作流）
• 选项 5 — 前端（UI/UX 开发）
• 选项 6 — 全部（所有功能）

4️⃣ 重启 Claude Code

切换 MCP 配置后，重启 Claude Code 以应用更改。

5️⃣ 配置本地设置（可选）

# 复制设置示例到本地
cp .claude/settings.local.json.example .claude/settings.local.json

# 编辑以包含您的偏好
# - 选择要启用的哪些 MCP 服务器
# - 配置任务完成挂钩
# - 根据您的工作流程定制

6️⃣ 验证安装

# 检查当前 MCP 配置
./switch-mcp.sh
# 选择选项 0 查看活动服务器

# 在 Claude Code 中尝试一个健康命令
/health-bugs

---

📚 文档

综合指南

文档	描述
常见问题解答	关于代理、MCP 配置和工作流的常见问题
架构	包含 Mermaid 图表和工作流模式的系统设计
教程：自定义代理	创建工作者、编排器和技能的逐步指南
用例	实际案例研究，附带指标和经验教训
性能优化	令牌使用优化和成本减少策略
迁移指南	将编排工具包添加到现有项目
路线图	未来计划和社区驱动的功能请求

深度文档

位于 docs/Agents Ecosystem/：

• AGENT-ORCHESTRATION.md — 使用编排器
• QUALITY-GATES-SPECIFICATION.md — 质量门控规范
• REPORT-TEMPLATE-STANDARD.md — 工作者的标准报告格式
• spec-kit-comprehensive-updates.md — SpecKit 自定义指南

快速链接

• 新用户：从 快速开始 → 教程
• 想要示例：查看 用例 和 使用示例
• 需要帮助：查看 常见问题解答 → 故障排除
• 优化成本：阅读 性能优化
• 迁移：遵循 迁移指南

---

🔌 MCP 服务器配置

所有 MCP 配置都存储在 ./mcp/ 目录中。

可用配置

基础（mcp/.mcp.base.json）

{
  "mcpServers": {
    "context7": { ... },              // 库文档
    "server-sequential-thinking": { ... }  // 增强推理
  }