克劳德代码子代理集合

面向测试驱动开发的实验性 NPX 安装程序

此工具会安装一组专为测试驱动开发和快速原型设计而打造的 AI 代理。它目前仍处于实验阶段，带有明确的设计理念，是我为了加快自己的 MVP 开发工作而构建的。

安装后的内容

npx claude-code-collective init

您将获得 30 多个专业代理，它们强制执行 TDD 方法论，并尝试更智能地利用真实文档而非凭猜测来完成任务。

为何创建此工具

我厌倦了以下问题：

• AI 给出的代码没有测试
• 必须手动查找库文档
• 不同项目之间开发方式不一致
• 需要手动拆解复杂功能

因此，我构建了这些代理，它们能够：

1. 始终先编写测试（红 → 绿 → 重构）
2. 使用 Context7 获取真实文档
3. 根据任务需求将工作分配给相应的专家代理
4. 智能地分解复杂请求

安装后的具体内容

核心实现代理（强制 TDD）

• @component-implementation-agent - 带有测试和现代模式的 UI 组件
• @feature-implementation-agent - 带有全面测试的业务逻辑
• @infrastructure-implementation-agent - 带有测试设置的构建系统
• @testing-implementation-agent - 能真正测试功能的测试套件
• @polish-implementation-agent - 在保留测试的前提下进行性能优化

质量与验证

• @quality-agent - 代码审查和标准检查
• @devops-agent - 部署和 CI/CD 设置
• @functional-testing-agent - 使用 Playwright 进行浏览器测试
• @enhanced-quality-gate - 全面的验证门控机制
• @completion-gate - 任务验证和完成检查

研究与情报（实验性）

• @research-agent - 基于 Context7 的文档查找
• @prd-research-agent - 智能的需求分解
• @task-orchestrator - 智能的任务并行化

系统与协调

• /van 命令 - 路由到 @task-orchestrator 的入口点
• @task-orchestrator - 中央路由枢纽，负责选择合适的专家代理
• @behavioral-transformation-agent - 系统行为设置
• @hook-integration-agent - TDD 强制自动化
• @van-maintenance-agent - 系统维护和更新

此外还有 20 多个其他专业代理，用于特定的开发任务。

安装选项

快速安装（推荐用于试用）

npx claude-code-collective init

其他可选方案（按需选择）

# 仅核心代理，适合轻量级项目
npx claude-code-collective init --minimal

# 仅关注测试框架
npx claude-code-collective init --testing-only

# 仅行为系统和钩子
npx claude-code-collective init --hooks-only

# 交互式设置，可自由选择
npx claude-code-collective init --interactive

实际安装内容

your-project/
├── CLAUDE.md                    # 代理的行为规则
├── .claude/
│   ├── settings.json           # 钩子配置
│   ├── agents/                 # 代理定义文件（30 多个）
│   │   ├── prd-research-agent.md
│   │   ├── task-orchestrator.md
│   │   ├── lib/
│   │   │   └── research-analyzer.js  # 复杂度分析引擎
│   │   └── ... (更多代理)
│   └── hooks/                  # TDD 强制脚本
│       ├── test-driven-handoff.sh
│       └── collective-metrics.sh
└── .claude-collective/
    ├── tests/                  # 测试框架模板
    ├── metrics/                # 使用情况跟踪（用于开发）
    └── package.json           # 测试设置（Vitest）

工作原理

1. /van 命令会路由到 @task-orchestrator（路由枢纽），该代理会分析请求并将其分配给相应的专家。
2. 研究阶段：代理使用 Context7 获取真实文档。
3. 先写测试：在任何实现之前先编写测试。
4. 实现：编写最少的代码使测试通过。
5. 重构：在保持测试通过的情况下进行代码清理。
6. 交付：您可以看到添加了哪些测试以及最终结果。

每个代理遵循的 TDD 合同

## 交付完成
✅ 先编写测试（红色阶段）
✅ 实现通过测试（绿色阶段）
✅ 代码经过重构以提高质量（重构阶段）
📊 测试结果：X/X 通过

管理命令

# 检查已安装内容及运行状态
npx claude-code-collective status

# 验证安装完整性
npx claude-code-collective validate

# 修复损坏的安装
npx claude-code-collective repair

# 清除所有内容
npx claude-code-collective clean

# 获取帮助
npx claude-code-collective --help

当前状态（坦诚评估）

表现良好的方面

• TDD 的强制执行有效减少了大量 bug
• Context7 的集成远优于代理凭猜测获取信息
• 路由系统通常能正确分配任务给合适的代理
• 复杂任务的分解确实很有帮助

实验性和不足之处

• 部分代理仍在优化中
• 研究阶段有时会比较慢
• 钩子系统需要重启（受 Claude Code 限制）
• 文档分散在各个文件中

已知局限性

• 需要 Node.js >= 16
• 安装后必须重启 Claude Code
• 对 TDD 有较强偏好（如果您不喜欢测试，请跳过）
• 部分代理可能过于细致或缓慢，不适合简单任务

测试安装效果

安装完成后：

# 1. 验证所有内容是否正确安装
npx claude-code-collective validate

# 2. 检查状态
npx claude-code-collective status

# 3. 重启 Claude Code（钩子需要加载）

# 4. 试用一下
# 在 Claude Code 中输入：“用 React 构建一个简单的待办事项应用”
# 预期结果：系统会进入研究阶段 → 分解任务 → 编写测试 → 实现功能

故障排除

安装失败

• 检查 Node.js 版本：node --version（需 >= 16）
• 清除 npm 缓存：npm cache clean --force
• 尝试强制安装：npx claude-code-collective init --force

代理无法正常工作

• 重启 Claude Code（钩子需要重新加载）
• 检查 .claude/settings.json 是否存在
• 运行 npx claude-code-collective validate

测试未运行

• 确保您的项目中已安装测试运行器（Jest、Vitest 等）
• 检查测试是否实际写入文件
• 查看代理提供的 TDD 完成报告

研究速度较慢

• Context7 可能存在连接问题
• 代理可能过于细致（具体情况因人而异）
• 检查 .claude-collective/metrics/ 中的时间数据

系统要求

• Node.js: >= 16.0.0
• NPM: >= 8.0.0
• Claude Code: 支持 MCP 和钩子系统
• 重启: 安装后必须重启（受钩子限制）

这是什么，又不是什么

是什么

• 面向快速原型开发的实验性辅助工具
• 专注于测试驱动开发（TDD）的AI智能体集合
• 我用于构建个人MVP的自用项目
• 坚持测试先行的开发理念

不是什么

• 生产级企业软件
• 保证完美运行
• 遵循任何官方标准
• 可以替代思考或理解代码的能力

为什么选择TDD？

因为根据我的经验：

• 先写测试能促使更优秀的设计思维
• 在缺陷修复成本较低时就能发现并捕获错误
• 良好的测试覆盖率让重构更加安全
• 带有测试的代码在未来更容易进行修改

这些智能体会强制执行上述原则，因为我相信这能带来更好的结果。如果你不认同TDD的理念，那么这个工具可能并不适合你。

研究型功能（实验性）

为了让智能体更好地适应现代开发需求：

• Context7集成：实时、最新的库文档支持
• ResearchDrivenAnalyzer：智能化复杂度评估
• 智能任务拆分：仅在真正需要时才创建子任务
• 最佳实践应用：基于研究的模式推荐

这些功能目前仍处于实验阶段，有时可能会过度思考，但总体来说还是很有帮助的。

解决常见智能体问题

AI智能体往往不够可靠。为此我设计了以下机制来应对这些问题：

智能体忽视TDD规则：通过钩子系统强制执行测试先行，确保任何代码都不会在未通过测试的情况下被提交。

智能体绕过指令：使用CLAUDE.md行为操作系统，设置优先级指令以覆盖默认行为。

智能体中途停止工作：通过测试驱动的交接验证，确保任务要么完整完成，要么明确移交。

智能体虚构API：通过Context7集成，强制智能体使用真实、最新的文档。

智能体采取错误方法：通过@task-orchestrator中枢进行集中路由，防止智能体自行选择不当路径。

智能体破坏协作：采用中心辐射式架构，避免点对点通信带来的混乱。

智能体跳过质量环节：设置质量门控，只有达到标准后才能继续推进。

智能体丢失上下文：通过交接契约，在智能体切换时保留所需信息。

智能体输出不一致：为每个实现智能体统一规范TDD完成报告格式。

智能体关注错误优先级：利用ResearchDrivenAnalyzer评估复杂度，合理分配精力。

以上大部分措施都是通过钩子和行为约束自动执行的，并非单纯依赖智能体自觉遵守指令。

支持

这是一个个人项目，但：

• 如果你发现了bug或有任何建议，欢迎提交Issue；
• 对于小修复或改进智能体提示词的PR也十分欢迎；
• 请不要期待快速响应——毕竟这只是我的一个副业项目。

获取帮助：运行npx claude-code-collective validate进行诊断。

许可证

MIT许可证——你可以随意使用、修改甚至“破坏”它，只要对你有用就行。

---

实验性 | TDD导向 | 个人项目 | 请自行承担风险

更改日志

详细的版本历史和发布说明，请参阅CHANGELOG.md。

Claude Code Sub-Agent Collective 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 版本 >= 16.0.0
• NPM: 版本 >= 8.0.0
• Claude Code: 已安装并配置好，需支持 MCP (Model Context Protocol) 和 Hook 系统。
• 重启要求: 安装完成后必须重启 Claude Code 才能加载钩子脚本。

注意：本工具强依赖测试驱动开发 (TDD) 理念。如果您不习惯“先写测试后写代码”的开发模式，本工具可能不适合您。

安装步骤

1. 快速安装（推荐）

运行以下命令初始化项目，这将安装 30+ 个专注于 TDD 和专业文档查询的 AI 智能体：

npx claude-code-collective init

2. 选择性安装（可选）

如果您只需要部分功能，可以使用以下参数：

# 仅安装核心智能体（轻量级项目）
npx claude-code-collective init --minimal

# 仅关注测试框架
npx claude-code-collective init --testing-only

# 仅安装行为系统和钩子
npx claude-code-collective init --hooks-only

# 交互式安装（手动选择组件）
npx claude-code-collective init --interactive

3. 验证与激活

安装完成后，执行以下步骤以确保环境就绪：

# 验证安装完整性
npx claude-code-collective validate

# 检查状态
npx claude-code-collective status

重要：验证通过后，请重启 Claude Code，否则钩子脚本（Hooks）无法生效。

基本使用

安装并重启后，工具会自动接管您的开发流程。所有请求将通过 /van 命令入口路由至任务编排中心 (@task-orchestrator)。

使用示例

在 Claude Code 对话框中直接输入自然语言需求，例如：

Build a simple todo app with React

预期工作流程：

1. 研究阶段：智能体调用 Context7 获取真实的库文档，而非凭空猜测。
2. 任务拆解：@task-orchestrator 将复杂需求拆解为具体子任务。
3. 测试先行 (RED)：自动编写测试用例。
4. 代码实现 (GREEN)：编写最小化代码以通过测试。
5. 重构优化 (REFACTOR)：在保证测试通过的前提下优化代码。
6. 交付报告：输出包含测试结果和完成状态的报告。

管理命令

日常使用中，您可以使用以下命令管理工具状态：

# 查看帮助
npx claude-code-collective --help

# 修复损坏的安装
npx claude-code-collective repair

# 卸载所有组件
npx claude-code-collective clean