three-man-team角色拆解①：Architect如何写出零歧义的构建Brief，让AI开发不跑题

用 AI 写代码时，有没有遇到过这种情况：AI 默默加了没人要的功能、做到一半突然跑题、或者反复重读文件浪费 token？three-man-team是一个由 Architect（架构师）、Builder（构建者）、Reviewer（评审者）组成的三角色 AI 开发团队框架，源于真实生产环境的打磨。本文是角色拆解系列的第一篇，带你拆解 Architect 如何写出零歧义的构建 Brief，让 AI 开发不跑题、不超支。

为什么 AI 开发总容易跑题？

大多数 AI 编码工具的问题是"有能力但没纪律"：👇

• 明明只需要一个函数，它去读整个代码库
• 顺手加功能，没人要求的也写上
• 任务中途漂移，做着做着方向就变了
• 每次会话都烧 token 做不必要的工作

three-man-team 给出的答案不是"更好的提示词"，而是一套流程：三个角色、明确的交接文件、防止最昂贵失败模式的规则。

三角色默认名字是Arch（架构师）、Bob（构建者）、Richard（评审者），安装时可自由改名。其中 Architect 是整个团队的"固定点"——方向不清时大家都看它。它的设定见 ARCHITECT.md。

Architect 的三大职责：先对齐，再开工

在 ARCHITECT.md 中，Arch 的职责被清晰地分为三件事：

1. 和项目负责人对话——先判断问题是产品缺口还是代码缺口，描述代码当前行为，让对方确认是否符合预期，再给出修复建议
2. 指挥 Bob 和 Richard——写 Brief、启动 Builder、完成后再启动 Reviewer，全程锁定范围
3. 拥有部署权——没有 Arch 的确认和项目负责人的许可，任何东西都不上生产

这套设计背后的研究思路写在 METHODOLOGY.md 里：给 AI 一个人设（背景故事、价值观、声音）比一句"你是架构师"能激活更精准的行为模式。

零歧义 Brief 怎么写？看懂这份模板

Brief 不是聊天，而是一份写入handoff/ARCHITECT-BRIEF.md的结构化文件。每步覆盖重写，它不是日志，而是"当前生效的构建指令"。模板见 ARCHITECT-BRIEF.md。

一份合格的 Brief 由四个板块组成，一个都不能少：

## Step N — [要构建什么] ### Decisions - [决策或约束，只写决定，不写散文] ### Build Order 1. [先构建什么] ### Flags - Flag: [Builder 不允许猜的任何事] ### Definition of Done - [ ] [可验证的完成标准]

四个板块各自消灭一类歧义：

• 📌Decisions：只写决策和约束。"用框架内置校验器，不要自己写正则"就是一句决策，省掉 Builder 一次错误尝试
• 🔢Build Order：构建顺序明确，避免 Builder 自己发明一个顺序
• 🚩Flags：这是灵魂板块——"Builder 不能猜的东西"全部显式声明。AI 跑题的根源往往是替人做决定，Flag 直接掐断这个空间
• ✅Definition of Done：完成标准必须可验证。"做好邮件校验"是模糊的；"服务端返回的错误格式与现有错误一致"是可检查的

一个完整 Sprint：从需求到部署

看完模板，用官方示例 sprint-walkthrough.md 走一遍完整流程。项目负责人提出："注册表单的服务端没有校验邮箱格式，只有 JS 前端校验。" Arch 读相关文件、确认缺口、对齐方案后写出 Step 12 的 Brief：

## Step 12 — 注册流程的服务端邮箱校验 - 注册处理器中增加服务端邮箱格式校验 - 在数据清洗之后、写入数据库之前校验 - 返回的错误信息与现有错误格式保持一致 - JS 校验已存在 —— 不要修改它 - Flag: 使用框架内置校验器，不要用自定义正则

注意 Brief 里的每一条都对应一个具体动作或禁令，Builder 拿到手不需要做任何"理解意图"的工作。随后流程严格沿着工作流走：

Bob 读完 Brief 先报计划、得到确认才动代码；Richard 按 REVIEWER.md 对照 Brief 逐条核对，揪出"错误信息不可翻译"的问题打回；Bob 修完复审通过，最后由 Arch 部署并更新日志。没有任何一步被跳过。

为什么"文件交接"既省 token 又不跑题

three-man-team 的 agent 之间不用对话沟通，而是通过结构化文件交接（详见 how-it-works.md）：

• Architect 写ARCHITECT-BRIEF.md
• Builder 写REVIEW-REQUEST.md
• Reviewer 写REVIEW-FEEDBACK.md

这意味着每个角色都以干净的上下文启动，只读自己岗位需要的文件：Builder 永远不加载完整项目规格，Reviewer 永远不加载数据库 schema。token 浪费从"行为问题"变成"结构问题"——结构对了，行为自然对。配合每次会话自动加载的 token 规则（见 CLAUDE.md 与 token-optimization.md），纪律是内建在基础设施里的。

快速上手：三步让 Arch 开始写 Brief

git clone https://gitcode.com/gh_mirrors/th/three-man-team.git .claude/skills/three-man-team cd .claude/skills/three-man-team && ./setup

setup 会接管后续步骤并给出精确指令。每个项目使用团队时的启动提示词整理在 session-start.md，首次会话只需要一句：

You are the Architect on this project. Please read new-setup.md.

Arch 会自动完成项目上下文文件、团队命名和首次会话提示词的搭建。

本篇小结 🧭

• 跑题的根源不是模型能力，而是缺乏结构和交接纪律
• Architect 的零歧义 Brief = 四板块模板：Decisions / Build Order / Flags / Definition of Done
• 其中Flags（不许猜的清单）+ 可验证的完成标准是让 AI 开发不跑题的关键
• 文件交接 + token 规则，让流程既是质量保障，也是成本保障

下一篇角色拆解将继续拆解Bob：Builder 如何严格执行 Brief，敬请期待。