交接文档、QA 失败反馈、升级报告：三个模板的用法

2026-08-09

多 agent 协作最先崩的地方，从来不是某个 agent 不会干活，而是两个 agent 之间的交接。上一个丢过来一句”我做完了”，下一个只能靠猜；QA 打回一句”有问题”，开发方不知道从哪查起；卡住了没人知道该找谁拍板，于是就一直卡着。

agency-agents 仓库的 strategy/ 目录针对的正是这一段。它的 nexus-strategy.md 第 11 章 Handoff Protocols 里给了三个模板：NEXUS Handoff Document（交接文档）、QA Failure Feedback（QA 失败反馈）、Escalation Report（升级报告）。strategy/coordination/ 子目录下还有两份文件，handoff-templates.md（357 行）是 agent 之间的交接文档模板，agent-activation-prompts.md（401 行）是各 agent 的激活提示词。

这篇讲的是这三个模板的用法：在哪触发、怎么落地、怎么验收、什么时候别用。

先把一个误会打掉：它们不会被”安装”

很多人以为把仓库克隆下来跑一遍安装脚本，这套协同流程就生效了。不是的。

按仓库自己的口径，strategy/ 目录不是 division，里面没有可安装的 agent——divisions.json 的 _note 写得很直白：strategy/ 存放的是编排方法论（orchestration doctrine），不是可安装的 agent。scripts/check-divisions.sh 里的 NON_DIVISION_DIRS 把它连同 integrations/、examples/、scripts/ 一起排除在外。一个目录要成为 division，必须至少包含一个带 frontmatter 的 agent 文件，而 strategy/ 下的 playbook 和 runbook 没有 agent frontmatter。

结论很清楚：./scripts/install.sh 不会把这三个模板拷进 ~/.claude/agents/。它们是给人读、给人抄进自己项目的文档。

更要紧的是第二层：**NEXUS 是一套写在 markdown 里的方法论，不是可执行的调度器。**它靠提示词让模型按阶段推进，没有任何代码在强制执行阶段顺序或质量门。所以这三个模板不会自动阻塞任何东西——它们能起作用，前提是你自己在流程里把它们当成硬性交付物。

怎么把这三份文件拿到手

# 只要最新一次提交，别拉整个历史
git clone --depth 1 https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# 协同层的两份模板文件
ls strategy/coordination/

# 定位第 11 章 Handoff Protocols 在 nexus-strategy.md 里的行号
grep -n "Handoff Protocols" strategy/nexus-strategy.md
grep -n "^## " strategy/nexus-strategy.md

逐项解释一下为什么是这几个选项：

--depth 1 是因为这个仓库带着 200 多个 agent markdown 和七篇 playbook，你要的只是当前内容，不需要历史。
第二条 ls 直接落到 strategy/coordination/，是因为第 11 章的三个模板讲的是协议，coordination/ 下的 handoff-templates.md 才是可以整段抄走的模板文本，两者要对照着看。
两条 grep -n 是为了拿行号：nexus-strategy.md 有 1110 行，第 11 章之外还有第 10 章 Agent Coordination Matrix（含 10.1 全量跨 division 依赖图）、第 12 章 Quality Gates、第 13 章 Risk Management、第 14 章 Success Metrics、第 15 章 Quick-Start Activation Guide。列一遍 ## 标题比一路翻页快。

Windows 上执行这几条要在 Git Bash 或 WSL 里跑，grep 在 PowerShell 里不是同名命令。仓库脚本本身标注的平台支持也是 Linux、macOS（bash 3.2+）、Windows Git Bash / WSL。

以上为按目录结构组合的示例命令，未逐项实测，以仓库最新内容与各脚本 --help 的实际输出为准。

三个模板分别在哪个环节触发

三个模板不是三选一，是三个不同的失败面。

**交接文档（Handoff Document）——阶段之间与 agent 之间的正常流转。**NEXUS 划了七个阶段，Phase 0 Discovery 到 Phase 6 Operate，每个阶段在 playbooks/ 下有一份对应文档。QUICKSTART.md 给的 NEXUS-Full 激活提示词最后两句是设计意图的浓缩：

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

每个阶段之间都有质量门、所有评估都要有证据。交接文档就是过质量门时那份”我交出去的到底是什么”的凭据。

**QA 失败反馈（QA Failure Feedback）——Phase 3 的 Dev↔QA 循环打回时用。**激活提示词里 Phase 3 写的就是 Build (Dev↔QA loops — all engineering + Evidence Collector)。这一环最容易退化成”测了，不行，你再改改”。模板存在的意义是逼着打回方把复现路径和证据一起给出来，而不是把二次定位的成本整个甩给开发方。仓库在 Testing division 里专门放了 testing-evidence-collector 这个 agent，证据不是顺口一提的要求。

**升级报告（Escalation Report）——超出当前 agent 决策范围时向上抛。**仓库只给了模板名与用途，没有给一张”什么时候该升级”的判定清单，下面这条口径是我们自己总结的：判断标准不是”这事很难”，而是”这事我决定不了”——涉及跨 division 的取舍、要改已定的架构或范围、要花钱、有合规风险。至于”该抛给谁”，第 10 章 Agent Coordination Matrix 里 10.1 那张全量跨 division 依赖图就是现成的地图。

落到自己项目里：一个最小骨架

下面这份骨架是我们按第 11 章三个模板的名称与用途自己写的最小可用版本，不是仓库原文。仓库原文请打开 strategy/nexus-strategy.md 第 11 章与 strategy/coordination/handoff-templates.md 对照，字段以那里为准。放这份骨架只是为了说明”落地时该长什么样”：

<!-- docs/handoff/phase-2-to-3.md -->
# Handoff: Phase 2 Foundation → Phase 3 Build
from: engineering-devops-automator
to: engineering-frontend-developer
phase: 2 -> 3

## 交付了什么
- （具体产出物路径，不是"搭好了脚手架"）

## 已知未做的部分
- （明确列出，别让下游自己发现）

## 下游需要的前置条件
- （环境变量名、依赖版本、需要谁开权限）

## 证据
- （构建日志 / 截图 / 命令输出的位置）

<!-- docs/qa-failure/2026-08-09-login.md -->
# QA Failure Feedback
from: testing-api-tester
to: engineering-backend-architect

## 现象
## 复现步骤（可执行，不是描述）
## 期望 vs 实际
## 证据位置
## 影响范围判断（阻塞发布 / 可延后）

<!-- docs/escalation/2026-08-09-scope.md -->
# Escalation Report
from: project-manager-senior
to: agents-orchestrator

## 阻塞是什么
## 我已经尝试过什么
## 需要谁做什么决定（写清决策项，不是"求指导"）
## 不决定的后果与时间点

from / to 里为什么写的是 engineering-devops-automator、testing-api-tester、agents-orchestrator 这种形式，下一节专门讲——这是这套设计里最值得抄走的一条。

产出物这块只说有依据的部分：这些文件是你自己写进自己仓库的，NEXUS 没有任何代码会替你生成它们，也不会有脚本去校验它们的字段。目录名 docs/handoff/ 是我们编的示例，你换成任何位置都行。

模板里必须写 slug，不能写显示名

runbooks.json 的 _note 解释了 roster 里为什么一律引用 slug：slug 是 agent .md 文件的文件名主干（corpus id），比如 engineering/engineering-frontend-developer.md 对应 engineering-frontend-developer，specialized/agents-orchestrator.md 对应 agents-orchestrator。

_note 特别提醒了两点：文件名主干并不总是带 division 前缀；显示名带前缀、而且会漂移。所以 roster 引用 slug——slug 抗改名、可测试。仓库里 scripts/check-runbooks.sh 干的就是这一件事：守住”每个 slug 都能解析到真实存在的 agent 文件”。

这条经验跟 agency-agents 本身没什么关系，任何项目都能用：**跨文件引用要引用稳定 id，不要引用展示名。**你在交接文档里写”前端开发”，三个月后有人把这个 agent 改了名或换了 division，这份文档就变成一句无法追溯的话；写 engineering-frontend-developer，至少还能 grep 得到。

怎么验收

模板类的东西最容易变成走过场，所以验收得是可执行的动作，不是”大家认真填”。

第一步，校验模板里引用的 slug 都能落到真实文件。Claude Code 的 per-agent 落点是 .claude/agents/{slug}.md，所以装过之后可以这样自查：

# 把 docs/ 下所有模板里的 from:/to: 取出来，逐个检查对应 agent 文件是否存在
grep -rhoE '^(from|to): [a-z0-9-]+' docs/ | awk '{print $2}' | sort -u | while read slug; do
  [ -f "$HOME/.claude/agents/$slug.md" ] || echo "MISSING: $slug"
done

这是把 check-runbooks.sh 的思路搬到自己项目里的通用做法，不是仓库提供的脚本。如果你装的时候用了 --path 覆盖安装目录，或者设了 CLAUDE_CONFIG_DIR 这类环境变量，路径要相应换掉。

第二步，人工检查这几处：

交接文档有没有”已知未做的部分”。只写做了什么的交接，等于没交接。
QA 失败反馈里的复现步骤能不能直接照着执行。写成一段描述就是把定位成本甩了回去。
升级报告有没有写清”需要谁做什么决定”。写成”请指导”的升级报告会在收件方那里再卡一轮。
三份文档里的 agent 引用是不是全都是 slug 形式。

最容易在哪一步出错？就是最后一条。写文档的时候顺手写显示名读起来更顺，等到要追溯或者写校验脚本时才发现对不上。

什么情况别这么干

一个人的项目别上这套。NEXUS 文档给的三种模式里，NEXUS-Micro 建议 5–10 个 agent、周期 1–5 天，用于 bug 修复、内容战役、单一交付物；NEXUS-Sprint 建议 15–25 个、2–6 周；NEXUS-Full 是全部 agent、12–24 周。这些都是文档给出的建议区间，不是实测数据，也不是承诺。就算按最小的 NEXUS-Micro 算，交接文档这套三件套对单人开发基本是纯负担——你交接给的是你自己。

**需要强制阻塞的场景，模板兜不住。**再说一遍，没有任何代码在执行质量门。如果你要的是”没过检查就不许合并”，得自己接 CI，模板只是让人写清楚，不能让流程停下来。

同时激活十几二十个 agent 是有代价的，上下文占用和成本压力都在，这里不给任何量化数字（我们没有测过）。真要试，先用 install.sh --division 或 --agent 收窄安装范围，比一次性把 255 个 agent 铺进全局配置目录务实得多。

事故响应是个反过来的例子。runbooks.json 里 incident-response 是唯一一个用 NEXUS-Micro 的 runbook，它的 always 组是 6 个 agent，包括 support-infrastructure-maintainer、engineering-devops-automator、engineering-backend-architect、engineering-frontend-developer 等；关键是它还有一个 post-fix 组，4 个 agent：testing-evidence-collector、testing-api-tester、testing-workflow-optimizer、product-sprint-prioritizer。

把”取证 + 回测 + 流程优化 + 重排优先级”放在修复之后单独一组，意思是修完不算完。这一组恰好是三个模板密度最高的地方：取证要交接文档、回测不过要 QA 失败反馈、影响面超出预期要升级报告。哪怕你嫌这套流程重，事故复盘这一段也值得单独留着。

延伸阅读

本文依据 agency-agents 官方仓库（github.com/msitarzewski/agency-agents）的 README、 tools.json、divisions.json、strategy/ 下的编排文档与 scripts/ 下的安装与校验脚本整理，核对日 2026-08-09。本文内容为仓库源码与文档口径，我们没有安装或运行过其中任何 agent，也没有按 NEXUS 跑过任何一次流程。文中标注为”我们自己写的骨架”的部分不是仓库原文，请以 strategy/nexus-strategy.md 第 11 章与 strategy/coordination/handoff-templates.md 的实际内容为准。目录、脚本与安装路径随上游更新而变动，请以仓库最新内容与 ./scripts/install.sh --help 的实际输出为准。