每个阶段之间都有质量门，所有评估都要有证据

2026-08-09

agency-agents 仓库里有一段 QUICKSTART.md 给出的 NEXUS-Full 激活提示词，把 Phase 0 到 Phase 6 七个阶段各自该上哪些 agent 全列了一遍，最后收尾是干巴巴的两行：

Quality gates between every phase. Evidence required for all assessments.

翻成人话就是「每个阶段之间都有质量门，所有评估都要有证据」。这两句是整段提示词里最容易被划过去的部分，但它恰恰是这套东西跟「一次性丢一堆角色给模型」的区别所在。这篇就把这两句话在仓库里的落点找出来，顺便给你一个判断依据：同样是「门」，什么时候该写成脚本，什么时候只能写成清单。

先把 NEXUS 定性清楚：它没有执行器

第一件必须说明白的事：NEXUS 是一套写在 markdown 里的方法论，不是一个能跑起来的调度器。

divisions.json 的 _note 里写得很直接——strategy/ 目录放的是编排方法论（orchestration doctrine），不是可安装的 agent。也就是说这个目录下一个带 frontmatter 的 agent 文件都没有，scripts/check-divisions.sh 会把它排除在 division 之外。它的内容是 nexus-strategy.md 这样的长文档、七篇 playbook、四个场景 runbook，加上一份机器可读的 runbooks.json。

QUICKSTART.md 自己对 NEXUS 的定位是：不用再一个个激活 agent 然后指望它们能配合，而是明确定义谁做什么、什么时候做、每一步的质量怎么验证。N-E-X-U-S 展开是 Network of EXperts, Unified in Strategy。

请注意「明确定义」的实现方式：它靠的是提示词，让模型自己按阶段推进。没有任何一行代码在强制执行阶段顺序，也没有任何代码在拦截不合格的交付物。 你在提示词里写「Quality gates between every phase」，模型认不认这个账、认到什么程度，是模型的事。把它理解成「编排引擎」或者「自动化框架」，一开始就会对错期望。

质量门写在哪几章

nexus-strategy.md 的章节结构跟 playbooks/ 下七个文件是一一对应的：

Phase	名称	playbook 文件
0	Intelligence & Discovery	`phase-0-discovery.md`
1	Strategy & Architecture	`phase-1-strategy.md`
2	Foundation & Scaffolding	`phase-2-foundation.md`
3	Build & Iterate	`phase-3-build.md`
4	Quality & Hardening	`phase-4-hardening.md`
5	Launch & Growth	`phase-5-launch.md`
6	Operate & Evolve	`phase-6-operate.md`

七个阶段之外，文档还有第 10 章 Agent Coordination Matrix（含一份全 division 依赖关系图）、第 11 章 Handoff Protocols、第 12 章 Quality Gates、第 13 章 Risk Management、第 14 章 Success Metrics、第 15 章 Quick-Start Activation Guide。

「质量门」有独立一章（第 12 章），这在意料之中。真正值得留意的是第 11 章 Handoff Protocols，它给了三个模板：NEXUS Handoff Document、QA Failure Feedback、Escalation Report。再配上 coordination/ 目录里的 handoff-templates.md（357 行）和 agent-activation-prompts.md（401 行），构成的是一份「上一个 agent 产出什么、下一个 agent 收到什么」的契约。

判断依据在这里：一个阶段之间的门要能起作用，光有「门」不够，还得有「门上要出示什么」。三个模板里有两个是给失败路径准备的——QA 没过怎么反馈、事情要往上捅怎么写升级报告。一套只定义了顺利交接、没定义失败回退的流程，本质上就是排班表，不是质量门。你自己做流程设计的时候可以拿这个当检查项。

「证据」在花名册里的落点

第二句「所有评估都要有证据」不是空话，它在 255 个 agent 里有具体对应物。Testing division 一共 9 个 agent，其中两个是专门冲着这件事去的：

testing-evidence-collector，显示名 Evidence Collector。它的 vibe 原文是 Screenshot-obsessed QA who won’t approve anything without visual proof，description 里进一步写了 Default to finding 3-5 issues, requires visual proof for everything。
testing-reality-checker，显示名 Reality Checker，vibe 是 Defaults to “NEEDS WORK” — requires overwhelming proof for production readiness。

这里必须提醒一句：这些句子是写给模型的人设文本，是在设定语气和默认立场，不是对任何真人履历或实际效果的陈述。「默认找出 3 到 5 个问题」是提示词里给的行为倾向，不是它真会稳定找出 3 到 5 个问题的承诺。

真正有信息量的是这两个 agent 在激活提示词里被排到了哪一阶段。原文里，Phase 3 Build 那一行是 Dev↔QA loops — all engineering + Evidence Collector；Reality Checker 则在 Phase 4 Harden，跟 Performance Benchmarker、API Tester、Legal Compliance Checker 一起。

★ 这个排法本身就是判断依据：Evidence Collector 不在最后的验收阶段，而是嵌在 Phase 3 的开发与 QA 循环里。证据是过程中采集的，不是收尾时补的。这跟很多团队的实际做法正好相反——先做完再回头找截图、补日志、凑记录，那时候拿到的东西已经不是证据了，是事后叙述。你要把这套思路搬进自己项目，第一件该改的不是加一道验收，是把取证动作提前塞进开发循环。

同一个思路在 runbooks.json 的事故响应 runbook 里还有一次体现。incident-response 是四个 runbook 里唯一用 NEXUS-Micro 模式的，它的 agent 分成两组：always 组 6 个，含 support-infrastructure-maintainer、engineering-devops-automator、engineering-backend-architect、engineering-frontend-developer 等；post-fix 组 4 个，是 testing-evidence-collector、testing-api-tester、testing-workflow-optimizer、product-sprint-prioritizer。

把「取证、回测、流程优化、重排优先级」单独编成修复之后的一组，等于在流程里明写了一句：修完不算完。这是这套 runbook 里最值得抄的一处设计。

另一层门：这一层是真的会让构建失败的

上面讲的都是「靠自觉」的门。仓库里还有另一层，那一层是 shell 写的，跑起来会给退出码。两层千万别混为一谈。

scripts/lint-agents.sh 对每个 agent markdown 做五道检查，而且分了级：

检查	级别
拒绝 CRLF 行尾	ERROR
frontmatter 分隔符存在	ERROR
必填字段齐全（`name` / `description` / `color`）	ERROR
推荐章节存在（Identity / Core Mission / Critical Rules）	WARN
正文有实质内容（词数 < 50 报警）	WARN

CRLF 那一条的源码注释解释得很清楚：行尾多一个 \r，后面的 frontmatter 检查就会报出令人困惑的 missing frontmatter，可文件开头明明就是 ---。所以干脆把它提到第一道拦掉。这是很典型的「把误导性报错换成准确报错」的门，Windows 用户尤其容易撞上。

另一个更有意思的是 scripts/check-agent-originality.sh。它防的是「换皮 agent」：把已有 agent 做一次查找替换，换掉里面的国家名或平台名，这种东西在评审里很难被发现——能合并、格式也规范——但会用重复内容把库撑肿。它的算法是把候选 agent 跟整个花名册对比，先把专有名词做实体中性化（源码里列的包括 vietnam、china、douyin、tiktok、korea、japan 这类词，注释说会随新市场继续扩充），再算 8 词 shingle 的重叠率。

阈值是两个环境变量，都有默认值、都可覆盖：

变量	默认	含义
`ORIGINALITY_FAIL`	`40`	达到或超过该百分比视为重复，退出码 1
`ORIGINALITY_WARN`	`20`	达到或超过该百分比给警告，不失败

★ 阈值本身不稀奇，稀奇的是源码注释里给了校准依据：在现有 agent 库里，任意一对之间最差的相似度约 1.5%，中位数 0%。所以默认把失败线放在 40，是留了非常宽的误判安全边界——双位数在这个库里就已经是强异常了。

这一条是本文最值得你搬走的方法：定阈值之前，先在现有语料上把分布量出来，再照着分布留边界，并把这个校准过程写进注释。否则 40 这个数字对后来的人就是天上掉下来的，谁也不敢动。顺带说明，1.5% 和 0% 是这个库的校准值，不是对任意 agent 库都成立的普适结论。

除此之外还有三个一致性守门脚本：check-divisions.sh 守 division 列表跟磁盘目录、convert.sh 与 lint-agents.sh 里的数组、workflow 的路径过滤器是否一致；check-tools.sh 守 tools.json 跟 install.sh 的 ALL_TOOLS、convert.sh 的转换器集合是否一致，条目缺 id/label/kebab/format/installKind/dest 任一项就失败；check-runbooks.sh 守 runbook 里引用的每个 slug 都能解析到真实存在的 agent 文件。

check-agent-originality.sh 里还有个细节值得学：它的 division 列表是直接读 divisions.json 的，不在脚本里硬编码一份拷贝。注释写明了理由——硬编码的字面量会悄悄跟目录漂移，读文件则不可能。

那么，你的项目里哪些门该写成脚本

把两层放一起看，边界就清楚了。判断依据大致是三条：

判定是否唯一。「frontmatter 缺不缺 color」有唯一答案，能写脚本；「这个提示词写得好不好用」没有唯一答案，只能写成清单交给人或模型评。仓库自己也没越界——脚本层查的是结构（lint-agents.sh）和重复度（check-agent-originality.sh），它们都不评估提示词质量，别把「lint 过了」当成「agent 好用」。
失败信号是否明确。写成脚本的门必须能给出「哪个文件、哪一行、违反了哪条」，否则跑绿了没人信、跑红了没人修。CRLF 那条之所以要单独提前，就是因为不提前的话失败信号会指向错误的地方。
误判代价是否可控。原创性检查敢开成 ERROR，前提是校准数据显示正常样本离阈值极远。你手上如果没有这个分布，那这道门只能先开成 WARN。

至于 NEXUS 那一层，模式与阶段划分是建议而非约束。文档给的三种激活模式——NEXUS-Full（全部 agent，12 到 24 周）、NEXUS-Sprint（15 到 25 个 agent，2 到 6 周）、NEXUS-Micro（5 到 10 个 agent，1 到 5 天）——这些周期和数量都是文档建议的时间尺度，不是实测数据，更不是「用 Sprint 模式两到六周就能做出 MVP」的承诺。同时激活十几二十个 agent 也是有代价的，上下文占用和成本都会上去，具体多少我们没有测过，不给数字。

真要动手，务实的顺序是：先把你项目里那几条能唯一判定的规则写成脚本挂进 CI，这是能立刻兑现的部分；再把「阶段之间要出示什么」写成交接模板，包括失败路径怎么反馈；最后才考虑要不要按 NEXUS 那样铺开整条流水线。跳过前两步直接上第三步，你得到的会是一段很长的提示词和一堆没有证据支撑的「已完成」。

延伸阅读

本文依据 agency-agents 官方仓库（github.com/msitarzewski/agency-agents）的 README、 tools.json、divisions.json、scripts/ 下的安装与校验脚本整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装或运行过其中任何 agent。目录、脚本与安装路径随上游更新而变动，请以仓库最新内容与 ./scripts/install.sh --help 的实际输出为准。