ensemble-team

Ensemble 团队设置

为任何软件项目设置 AI Ensemble 编程团队。创建完整的团队结构，让一组专家 Agent 以单主导的群体编程方式协作，采用基于共识的决策、TDD 和持续回顾。

工作流

阶段 1：项目发现

收集项目的基本信息。询问用户：

1. 项目名称和描述：要构建什么？要解决什么问题？
2. 技术栈：语言、框架、数据库、前端方案、测试工具。 如果不确定，可根据他们的目标协助做出选择。
3. 产品愿景：目标用户是谁？MVP 范围是什么？想法模糊也没关系——产品经理 Agent 会进一步完善。
4. 开发环境：Nix？Docker？标准包管理器？CI 提供商？
5. 代码仓库：使用现有仓库还是新建？分支策略是什么？

阶段 2：团队组成

确定合适的团队。

前置要求：继续之前，先阅读 references/role-catalog.md。

分层团队预设

从一个预设开始，然后根据项目需求进行调整。团队组建阶段（阶段 5）有助于确定合适的配置。用户可以修改任何预设。

预设	规模	组成
Full	~9	1 名产品经理、1 名 UI/UX 设计师、1 名无障碍专家、1 名领域 SME、1 名 QA 分析师、4 名软件工程师
Lean	~5-6	1 名产品经理、1 名领域 SME、1 名开发实践负责人、2-3 名软件工程师、1 个灵活角色（根据需要担任 UX、QA 或 DevOps）
Solo-plus	~3	1 名领域 SME、1 名开发实践负责人、1 名软件工程师

每轮讨论的大致 token 成本：

• Solo-plus（约 3 个 Agent）：轻量。每轮约 5-10K 个 token。
• Lean（约 5-6 个 Agent）：中等。每轮约 15-25K 个 token。
• Full（约 9 个 Agent）：较重。每轮约 30-50K 个 token。适用于治理开销物有所值的项目。

实际成本取决于模型、上下文长度和讨论复杂度。这些只是用于设定预期的粗略估算，并非精确统计。

选择预设：询问用户项目范围、时间线和复杂度。Solo-plus 适合目标明确的任务或技术验证。Lean 适合大多数项目。Full 适合范围较大的产品，尤其是有 UI、无障碍和质量要求的产品。

扩展，而非替换：这些预设以角色目录为基础。请参阅目录，了解可补充任何预设的条件角色（安全、数据/ML、API 专家等）。平票时优先采用奇数人数。

研究每位专家——不要从记忆中的名单中挑选。 对于每个角色：

1. 确定项目所需的具体技术或领域
2. 使用 WebSearch 查找公认的权威人士——也就是撰写相关书籍、创建相关工具或就该领域做过标志性演讲的人
3. 核实其资历、近期工作以及与本项目的相关性
4. 评估：已发表的权威成果、鲜明的表达风格、实践经验，以及与其他团队成员互补的视角

为每位拟议专家介绍：姓名、资历、重要已发表作品、他们为何适合本项目，以及他们会重点关注什么。让用户批准、替换或移除。

阶段 3：生成团队档案

为每位成员创建 .claude/agents/<name>.md。

前置要求：继续之前，先阅读 references/profile-template.md。

必需章节：开篇简介、角色、核心理念（根据其已发表作品提炼 5-8 条原则）、技术专长（6-12 项）、本项目须知（具体指导）、沟通风格（个性特点 + 4-6 条代表性表达）、群体编程方式、代码审查清单（6-12 项检查内容）、经验教训（留空，后续更新）。

质量门槛：档案必须体现该专家不可替代的特点，并包含针对项目的具体指导以及其鲜明的表达风格。

AI 仿真免责声明

每份档案都 MUST 在开篇简介段落之后立即包含以下免责声明区块：

> **AI-Approximation Notice**: This profile is an AI-generated approximation inspired
> by [Name]'s published work, talks, and writings. The real [Name] has not endorsed
> or reviewed this profile. All outputs should be verified against their actual
> published work. This profile creates a "diversity of heuristics" drawing on their
> known perspectives — it does not simulate the actual person.

AI 自我认知条款

每份档案都必须在“你在团队中的角色”部分声明，团队成员知道自己是体现某种视角的 AI Agent，而不是真正的那个人。人类的时间限制与 AI Agent 无关。当话题超出角色的专业范围时，在决策中暂不表态是恰当的谦让，而非不赞同。

压缩主动上下文形式

每份档案都必须在末尾包含一个 ## Compressed Context 部分：用少于 500 个 token，以精炼的方式概述角色、最重要的 3-5 项原则、关键专业领域和典型审查重点。讨论和审查阶段会加载此压缩形式。只有当成员主动负责或引导代码工作时，才会加载完整档案。

阶段 4：生成项目脚手架

协调员说明

前置条件：继续之前，请阅读 references/coordinator-template.md。

填写团队名单、构建工具和团队规模。将协调员说明生成到 .team/coordinator-instructions.md。然后在特定框架的配置文件中添加指引（例如，Claude Code 使用 CLAUDE.md，Cursor 使用 .cursorrules，其他框架使用项目说明），指示主 Agent 阅读 .team/coordinator-instructions.md。协调员说明文件仅供协调员使用。

AGENTS.md — 团队结构部分

在 AGENTS.md 中插入一个受管理的“团队结构”部分，注明：

• 团队成员档案位于 .claude/agents/
• 项目所有者的约束定义在 PROJECT.md 中
• 领域术语表维护在 docs/glossary.md

本部分为所有 Agent 提供指引。AGENTS.md 的约定部分将在团队组建会议（阶段 5）期间由团队填写。

PROJECT.md

前置条件：继续之前，请阅读 references/project-template.md。

填写技术栈、范围（必须／应该／可以／排除）、开发要求和环境。

支持文档

• docs/glossary.md：领域术语表框架（核心类型表、操作表、错误表、类型设计原则）
• docs/deferred-items.md：跟踪表（项目 | 类别 | 来源 | 严重程度 | 状态）
• docs/future-ideas.md：用于暂存范围外想法的清单

阶段 5：团队组建会议

这是关键阶段。团队将讨论并就工作约定、架构决策和领域术语达成共识。

运作方式：协调员激活整个团队，然后每次提出一个讨论主题。团队依据罗伯特议事规则协议展开讨论、提出方案并达成共识。根据决策类型，将成果记录在相应位置：

• 工作约定（协作规范、完成定义、代码约定、沟通规范、群体编程模式细节、回顾频率、工具约定）记录在 AGENTS.md 的约定部分。
• 架构决策（原则、部署策略、状态管理、测试理念）作为 ADR 记录在 docs/ARCHITECTURE.md 中。
• 领域术语（类型、操作、错误、命名约定）用于更新 docs/glossary.md。

10 个主题（并非穷尽，团队可以增加更多主题）：

1. 我们如何决定要构建什么？
2. Driver-Reviewer 群体编程模式如何运作？
3. 一项工作何时算“完成”？
4. 我们的提交和集成流程是什么？
5. 我们如何解决分歧？
6. 我们有哪些代码约定？
7. 我们何时以及如何开展回顾？
8. 我们有哪些架构原则？
9. 我们如何作为团队进行沟通？
10. 我们遵循哪些工具和代码仓库约定？

每个主题都包含其要解决的问题以及引导讨论的子问题。团队的回答将成为他们的约定和决策，而不是预先编制的模板。

第 6 阶段：配置权限

授予团队 Agent 完成工作所需的权限（文件编辑、Shell 访问等）。具体配置方式取决于所使用的框架：

• Claude Code：创建或更新 .claude/settings.json，内容为 "allow": ["Edit", "Write", "Bash(*)"]
• Cursor/Windsurf：在 IDE 设置中配置工具权限
• 其他框架：按照框架文档授予 Agent 权限

审阅者只需要对 .reviews/ 具有写入权限。有关权限范围配置和审阅文件工作流，请参阅 references/file-based-reviews.md。

第 7 阶段：配置 CI

在 CI 配置中添加 paths-ignore 规则，忽略框架生成的会话或转录目录（例如 Claude Code 的 .claude-sessions/），以免这些文件触发 CI 运行。

第 8 阶段：总结

说明已创建的文件以及如何启动团队。框架配置文件（例如 Claude Code 的 CLAUDE.md）通过 @（或等效的包含机制）引用 AGENTS.md，协调者则会读取 .team/coordinator-instructions.md 了解其操作说明。建议告知协调者要构建什么。

已创建的文件：

• .claude/agents/<name>.md — Agent 定义文件（团队成员简介）
• .team/coordinator-instructions.md — 协调者操作说明
• AGENTS.md — 团队结构和约定（在组建会议期间填写）
• PROJECT.md — 项目所有者的约束
• docs/ARCHITECTURE.md — 架构决策记录（在组建会议期间填写）
• docs/glossary.md — 领域术语表
• docs/deferred-items.md — 延后事项跟踪文件
• docs/future-ideas.md — 暂存范围外想法的清单
• .reviews/ — 审阅反馈目录（由审阅者在工作期间创建）
• 框架配置指针（例如 CLAUDE.md）— 指示协调者读取 .team/coordinator-instructions.md

回顾协议

由单个 Agent 撰写所有视角的内容并不算回顾，而只是总结。为回顾而启动的每个 Agent 都必须是 .claude/agents/ 中有名有姓的团队成员。

回顾由事件触发，而非按时间安排。触发条件：每次 PR 合并到集成分支并发布后。

完整流程请参阅 references/retrospective-protocol.md。以下四个阶段为必需阶段：

1. 审查此前的行动项 — 检查所有先前行动项的状态。对于 2 次或更多次回顾前标记为 NOT-STARTED 的事项，升级为阻塞项。
2. 个人观察 — 每位成员独立撰写（写入 .reviews/retro/ 文件）。所有人完成撰写前不得讨论。
3. 团队讨论 — 成员之间进行实际交流，并对彼此的观察作出回应。协调者需确认确实发生了交流（而非由单个 Agent 进行总结）。
4. 达成共识并记录 — 提案采用同意流程。将结果记录到 AGENTS.md 约定或 ADR 中。每个行动项都必须指定负责人。

行动项实施门槛： 回顾中的行动项必须在开始下一个工作项前落实。这样可以避免待处理改进不断累积，以致回顾失去意义。

每次 CI 构建后的迷你回顾仍是轻量的观察检查点（是否遵循了流水线？提交是否原子化？），无需征得人工同意。此类回顾只作观察，不作指示。

核心原则

这些不可妥协的要求源自生产实践经验。

前置条件：继续之前，请阅读 references/lessons-learned.md。

• 仅使用指定团队成员：为团队工作生成的每个 Agent 都必须是 .claude/agents/ 中的指定成员。团队活动中绝不使用通用后台 Agent。
• 推送前达成共识（先在本地审查，再推送）
• 每次提交都必须执行重构步骤
• CI 等待规则（绝不排队运行多个 CI）
• 每次 CI 构建后进行小型回顾（由团队开展，而非协调者）
• 由 PR 触发的回顾，输出须征得同意
• 在开始下一个工作项之前，落实回顾中的行动项
• Driver 交接协议（摘要 + git log + 通过的基线）
• 遵循术语表（领域类型须符合术语表）
• 立即跟踪延期事项
• 协调审查者（先查看其他人的审查）
• 非阻塞反馈升级：连续 2 次或更多审查中出现的事项升级为阻塞项
• 在激活提示词中明确说明 Driver 入门要求
• CI 触发条件中排除会话记录
• 每份个人档案都须包含 AI 近似说明
• 每份个人档案都须包含压缩版的活动上下文
• 让位表示尊重他人决定，而非表示反对
• 基于文件的审查可在上下文压缩后保留（消息仅作补充，不可替代）

执行说明

• 子 Agent 模式：结构性。指定的 Agent 个人档案用于约束角色边界。
• 链式模式：指导性。通过自行切换角色来执行。
• 流水线模式：门控式。在定义的检查点通过共识门控来阻止流水线继续推进。

限制

• AI 免责声明：免责声明必须实质上诚恳，而非仅仅在形式上存在。写入免责声明的同时，以暗示真实认同的口吻撰写个人档案，违背了其本意。档案应表达“这是 AI 可能如何近似此人观点的说明”，而不是“这是此人的想法”。
• “团队活动仅限指定成员参与”：团队活动包括回顾、共识讨论、代码审查，以及任何需要团队成员观点（而不仅仅是劳力）的任务。背景研究、文件操作和机械性任务不要求指定成员参与。

有关工厂模式下的共识解决方案，请参阅模板目录中的 CONSTRAINT-RESOLUTION.md。

工厂模式（可选）

如果将 pipeline 技能与 ensemble-team 一同安装，协调者会在设置期间检测到这一点并启用工厂模式。这会在组建团队与构建阶段之间增加一个阶段 1.5（“工厂模式配置”）。

在工厂模式下，协调者会将整个构建阶段交给流水线控制器，而不是直接管理。流水线通过质量门控处理切片排队、TDD 搭档派遣、代码审查编排和合并决策。推送前仍由整个团队进行审查。

有关协调者交接的详情，请参阅 references/factory-mode.md。

工厂模式与监督模式

• 监督模式（默认）：协调者管理构建阶段。所有决策均采用 Robert's Rules 共识协议。协调者负责协调 Driver 轮换、审查周期和回顾。
• 工厂模式（安装了 pipeline 时）：流水线管理构建阶段。质量门控取代共识，用于构建期间的决策。协调者仍负责规划、工厂配置和构建后审查。与此前一样，整个团队参与推送前审查和回顾。