Multi Agent Project

多 Agent 协同项目骨架（跨软件可续接）

一句话安装（用户让你"装这个 skill"时自主执行）

来源仓库：https://github.com/aduhappy/multi-agent-project-skill。clone 到本工具的 skills 目录即装好（无其他依赖）。

⚠️ 目标目录名必须是 multi-agent-project（与本 skill 的 name: 一致），不是仓库名 multi-agent-project-skill。 Claude Code / Codex 按目录名识别 skill——直接 git clone <URL> 会得到 multi-agent-project-skill/，与 name 不匹配。clone 时显式指定目标目录：git clone <URL> ~/.claude/skills/multi-agent-project。

不同工具的 skills 目录不同，请按工具选对路径（末段目录名统一为 multi-agent-project）：

通用原则：

• Windows 下 ~ = %USERPROFILE%。
• 用户级 vs 项目级拿不准时默认用户级（装一次处处可用）。
• 目录不存在先创建再 clone；clone 时把目标目录名钉成 multi-agent-project。clone 完告诉用户新开一个会话即可触发本 skill。

这技能干嘛

在项目根目录生成一套软件无关的纯 Markdown 协同骨架——一个权威入口 + 若干薄指针 + 自包含任务卡 + 收工规矩。换 Claude / Cursor / Gemini / ZCode / Copilot 任何一个，agent 进来读同一份入口就能接上前任工作，不丢上下文、不互相覆盖。

核心原则四条：

1. 真相只有一份：AGENTS.md 是唯一权威入口；其他工具的约定文件（CLAUDE.md / GEMINI.md / .cursorrules / copilot-instructions.md）全是 3 行薄指针，指向 AGENTS.md。
2. 细节外链、入口要短：AGENTS.md 控制在 1–2 屏，每个新 agent 都得读完。细则下沉到 文档/ 下的专题文档，入口只放指针。
3. 纯 Markdown + 相对路径：不依赖任何软件专属语法，换工具不破。
4. 信任但验证：agent 自检不够——关键产物必须按分级要求由主控或另一 agent 独立抽验通过才进下一棒。产物分级：
   • 纯文本写作/格式转换->自检够
   • 分析建模/参数选定->必须独立复核
   • 论文结论/头条数字->必须独立复核（复核人不同） 关键任务复核通过前标记"待验、下游不得启用"。

何时触发

• 用户说"开新项目/新课题""怎么组织文档让 AI 协同""AGENTS.md 怎么写""多个 agent 接力"。
• 现有项目 agent 经常问重复问题、找不到状态、覆盖彼此产出。
• 用户要把"手工总结的协同经验"固化成可复用结构。

不适用：单文件小脚本（不需要多 agent 协同）、已有完善 AGENTS.md 且不需要重新生成的项目、纯翻译或知识问答。

怎么用（两种模式）

模式 A：从零生成骨架

0. 先建决策登记表（空表也行），再写其他。 在 AGENTS.md 的 3.5 节预置一张决策登记表（一行一决策），所有后续 agent 建模/取数前先 grep 这张表。模板中已预制空表。
1. 先读后问——在向用户提问前，先读取项目中已有的 README、目录结构、已有文档和代码。能从项目中推断的（项目语言、数据源类型、工具偏好）不要问，直接给合理默认值；只问"用户特有的、没法从项目中推断的"信息。然后一次性问全（别挤牙膏）：项目根目录、一句话目标、要兼容哪些 AI 工具、是否云同步目录、涉及哪些数据源。
2. 加问一条硬约束清单："列出本领域'不可混用'的维度（口径/单位/坐标系/分辨率/时期/林龄分层等）。写成硬规则，后续所有 agent 必须遵守。"——这是最常被忽略但一错就全错的铁律。
3. 从 assets/ 复制 AGENTS.md 到根目录，填入用户给的内容。
   • 占位符规则（重要）：用户明确给的信息直接填；用户没给的，优先给合理默认值（基于项目主题推断）并简短标注"默认值，可改"；只有"用户特有的、没法合理推断"的细节（如具体 DOI、密码、账号）才留 【待填】。判据：AGENTS.md 正文里 【待填】 越少越好，理想是 0 个。
4. 按用户勾选的工具，复制对应薄指针文件（CLAUDE.md / GEMINI.md / copilot-instructions.md 等），内容统一是"以 AGENTS.md 为准"；Cursor 用户推荐用 .cursor/rules/multi-agent.mdc（现代格式，从 assets/multi-agent.mdc 复制——它带 description/globs/alwaysApply frontmatter，缺了规则不生效），.cursorrules 为 legacy 备用。用户没勾的工具不要生成。
5. 建 文档/任务规划_<主题>.md（从 assets/任务规划_模板.md 复制）。如果项目有多个任务卡，同时拷入 assets/任务卡_README.md（任务卡目录索引模板，列依赖链和当前状态）。每张任务卡末尾自带『📋 派发提示词（复制即用）』块——把卡里字段填进去，用户复制即可贴给任何 agent 冷启动执行，不用每次重写委派话术。建卡时顺手填好这段。 🟡 多树 / 迁移场景再拷 assets/迁移协议.md 与 assets/经验教训.md 到 文档/——AGENTS.md §5 的两条指针指向它们，不拷就是死链。
6. （可选）按需建：文档/委派任务模板.md（从 assets/委派任务模板.md 复制，给主控 agent 派活用）、文档/决策记录/（存放 ADR）、文档/词汇表.md（项目术语）。注意：这些是可选模板，小项目跳过，别让入口变臃肿。
7. 推导数据集目录：从用户描述的数据源拆分——每类数据一个目录（例：用户说"MODIS + Landsat"→ 建 MODIS/ 和 Landsat/ 两个目录；用户说"问卷 + 实测"→ 建 问卷/ 和 实测/）。每个数据集目录放 来源.txt（从 assets/来源.txt 复制）。没明确数据源的项目可跳过这步。
8. 代码归位：建 scripts/ 目录 + scripts/README.md（从 assets/scripts_README.md 复制）。把用户已有的脚本列表填进去（如果有），或留空等后续 agent 填充。同时拷入 check_handoff.py（从 assets/check_handoff.py 复制）——收工交接自检脚本，agent 每次收工跑 python scripts/check_handoff.py 验证 §3/§4/STATUS 已更新。在 AGENTS.md §5 铁律里约定"脚本不散落根目录"。
9. 建 STATUS.md（从 assets/STATUS.md 复制）——空模板，第一个 agent 收工时填增量 handoff（本 agent 做了什么/动了哪些文件/踩了什么坑）。
10. 把用户的环境、约束写成 §铁律、§路径约定。
11. 跑完后告诉用户：骨架生成了哪些文件、有哪些"默认值"需要他确认、有哪些 【待填】 需要他补。

模式 B：诊断已有项目

B1：烂项目修补（零文档或文档混乱）

用户已有项目但协同乱——agent 反复问重复问题、互相覆盖、找不到状态。先读现有 README/任何文档/目录结构，对照 §文件骨架 和 §AGENTS.md 的板块 检查缺什么，给出全量修补清单（缺薄指针？入口缺失？任务卡不自包含？没来源.txt？没收工规矩？）。用户确认后补齐。先读后改，绝不直接覆盖已有文件。

B2：好项目增强（已有好文档，只缺薄指针）

用户已有完善的项目文档（如 AI_COLLABORATION_PLAN.md / README.md / 详细 wiki），但 AI 工具不会自动读它（Codex/Claude 默认读 AGENTS.md，不会主动发现自定义文件名）。只加一个 AGENTS.md 薄指针（3 行），指向已有文档；再按用户勾选的工具加对应的薄指针文件（CLAUDE.md 等）。不动任何已有文档。判据：加完后，新 agent 进门 → 读 AGENTS.md → 跳转到已有文档 → 获得完整上下文，无需用户手动说"先读 XX 文件"。

文件骨架（生成后长这样）

<项目根>/
├── AGENTS.md                          ← 唯一权威入口（顶部 TL;DR 3 行 + 七板块，所有工具默认读）
├── STATUS.md                          ← 增量 handoff（本 agent 做了什么/动了哪些文件/踩了什么坑，收工落盘）
├── CLAUDE.md                          ← 薄指针 → "以 AGENTS.md 为准"
├── GEMINI.md                          ← 薄指针（同上，可选）
├── .cursorrules                       ← 薄指针（Cursor 用，可选）
├── .github/copilot-instructions.md    ← 薄指针（Copilot 用，可选）
├── 文档/
│   ├── 任务规划_<主题>.md             ← 自包含任务卡（含"交付前必做"清单 + 可选建议模型）
│   ├── 任务卡_README.md               ← 任务卡目录索引（依赖链 + 当前状态表，可选）
│   ├── 委派任务模板.md                ← 给 AI agent 委派任务的标准话术（复制填，可选）
│   ├── 迁移协议.md                    ← 整棵树换位置时才读（可选，多树项目建议带）
│   ├── 经验教训.md                    ← 规则背后的实测案例（可选，规则与理由分离）
│   ├── 决策记录/                      ← 关键技术决策（可选，见 advanced.md）
│   └── 词汇表.md                      ← 项目术语（可选）
├── <数据集名>/                        ← 每个数据集一个目录
│   ├── 来源.txt                       ← DOI/URL/日期/口径/单位
│   └── ...
├── scripts/                           ← 代码归位（推荐：脚本不散落根目录）
│   ├── README.md                      ← 每个脚本一句话：干嘛/输入/输出/谁写的
│   └── check_handoff.py               ← 收工交接自检脚本（跑这个验证 §3/§4/STATUS 已更新）
└── 进度日志.md                        ← 带日期戳的变更流水（可选）
> 已归档标记：已完成且不会再读的文档，在文件名或指针区标注此标记--新 agent 无需再读全文，节省认知负荷。

并列多线课题（软件 / 论文 / 专利 这类）

一个课题下有几条并列的线——各自独立推进、又共享同一套口径。 不要塞进一个 AGENTS.md，也不要各写各的互不相干。

🔴 关键前提：agent 的工作目录通常直接设在某一条线上（如 .../01_软件）， 不是设在课题根。所以线级必须自包含，根不能在关键路径上。

<课题根>/
├── AGENTS.md          ← 🔴 纯索引：三条线在哪 · 权威口径文档在哪 · 哪些路径不许动
├── STATUS.md          ← 只记跨线的事
├── 01_软件/  AGENTS.md · STATUS.md · 薄指针 · 自己的子目录   ← agent 实际待的地方
├── 02_专利/  同上
└── 03_论文/  同上

四条规矩：

1. 🔴 根只做索引，不放内容。三条线在哪、权威口径文档在哪、哪些路径不许动——就这些。 根一旦有了独有内容，而 agent 又不从根进，那份内容就会没人看、然后漂移。
2. 🔴 跨线共享的口径住在一份「权威文档」里，各线直接指它，不经过根。 典型是「不可混用维度」「关键数字定义」。 各线只链过去，绝不复述——复述就是给漂移开口子。
3. 各线自包含：每条线有自己完整的 AGENTS.md / STATUS.md / 薄指针， agent 只被丢进这一条线也能干活，不必读上级。
4. 🔴 同名文件两层并存是设计，不是重复：根和各线都有 AGENTS.md / CLAUDE.md 很正常。 不许合并、不许"去重"、不许用任一方覆盖另一方——一覆盖就把某一层的规则整条抹掉。

📌 收工自检在线级跑，不在根跑：cd 03_论文 && python ../scripts/check_handoff.py。 索引型根没有 TL;DR / §3 现状，在根跑必然 FAIL，那是设计不是缺陷——记得在根写明这句。

📌 判据：一个 agent 只被丢进 03_论文/，读完该线 AGENTS.md + 它指向的权威口径文档， 就能开工——不用问人、不用翻聊天记录、不用读上级。

AGENTS.md 的板块（顺序即优先级）

照 assets/AGENTS.md 模板填。顶部先有一个 TL;DR 块（3 行：当前阶段/下一步/阻塞） 让新 agent 扫一眼就知状态；下面 8 个板块（模板编号 1–7，其中路径约定单独编号为 §5.5，因为太重要不能和铁律混在一起）：

0. TL;DR（进门速读）——3 行：当前阶段、下一步、阻塞。每次收工更新。新 agent 不用读完全文就知道干到哪了。
1. 一句话北极星——这项目到底干嘛、给谁、什么基调（语气、投稿/交付目标、别耽误哪条主线）。
2. 当前故事/方法——最新定下来的方向 + 核心方法 + 最近换过什么、为什么。
3. 现在在哪——每次收工更新，1–5 条带日期戳的累计快照。这是接力最关键的交接点。增量细节下沉到 STATUS.md，本节只留累计状态。
4. 任务看板——[ ]/[x] + 谁负责 + 依赖（T1→T2，哪些可并行）+ 已知风险。
5. 铁律/约定——违反会返工的：环境调用、绘图/数据规矩、命名、口径、收工规矩。含"新 agent（含子 agent）进门第一件事：读完 AGENTS.md 再动手"。 5.5. 路径约定——大文件去哪、小产物回哪（防多 agent 撞车、防云同步爆炸）。单独成节，别埋进铁律。
6. 深读指针——细节去哪个文档（任务细则、决策记录、词汇表、任务卡索引）。
7. 环境/工具——完整工具路径怎么调、env 锁。

STATUS.md vs AGENTS.md §3 的分工（防重叠）：STATUS.md 记增量（本 agent 这一轮做了什么、动了哪些文件、踩了什么坑）；AGENTS.md §3 记累计快照（当前整体进度，1–5 条）。两者不重复——STATUS.md 是"自上次以来的变化"，§3 是"现在整体到哪了"。

决策登记表（必建，非可选）

把具约束力的决策用一张有界、可 grep 的表收口——一行一决策：ID | 状态 | 决策 | 取值/口径 | 理由 | 日期 | 证据链接 | 取代了谁 | 被谁取代。放 AGENTS.md 的 3.5 节（紧邻任务看板）。它和散在 STATUS 长叙事里的自由式 ADR 不同：有界（一决策一行，永远读得完）、可查（grep 关键词秒命中权威行）、可追（双向 supersession 链——旧行的"被谁取代"指向新 ID，新行的"取代了谁"指回旧 ID，任何 agent 读到旧决策都能顺着链接找到当前有效版本）。状态只有两种：ACTIVE（有效）和 SUPERSEDED（已被取代）。变更规矩：改 ACTIVE 决策时不能静默覆盖——旧行标 SUPERSEDED、新增一行记新决策。模板在 AGENTS.md 的 6 节深读指针已预制空表。详卡存 文档/决策记录/。

实战教训：曾有两个 agent 对同一样本集编码不一致（R2 从 0.5 拖到 0.27），根因就是"剔除某点"的决策只躺在 600 行 STATUS 里没上浮。信滞后脚本、不信决策记录是这类事故的共同根因。

铁律与路径约定的边界（防 agent 混淆）

两个节分工不同，不重叠：

• 铁律 = 违反会返工的行为约束（不改原始数据/不静默改参数/不分进程绘图/口径不可混用等）。
• 路径约定 = 文件的物理位置约束（大文件去哪、小产物回哪、不往云同步盘塞 GB 级中间件）。
• 判据：铁律约束的是"你能不能做这件事"；路径约定约束的是"做了之后放哪"。铁律的"不改"不因路径约定而放松。

跨软件能续的硬要求（9 条）

1. 纯 Markdown + 相对路径 + 标准文件名——别用某软件专属语法、别硬编码绝对路径。
2. 数据带 来源.txt（DOI/URL/下载日期/口径/单位/已知问题）——换人换 agent 都能溯源。
3. 收工规矩写进铁律——每个 agent 退出前更新 §现在在哪 + §任务看板 + 写/更新 STATUS.md（增量 handoff：本 agent 这一轮做了什么、动了哪些文件、踩了什么坑，不重复 §3 的全量快照）。收工时跑 python scripts/check_handoff.py 自检——验证 §3 日期新鲜（老项目可 --days N 放宽）、TL;DR 已填、STATUS.md 非模板、STATUS 日期 ≥ §3 日期、§4 看板存在、薄指针存在（认 .cursor/rules/*.mdc）；另含四条 advisory（决策登记表是否存在、多脚本口径常量是否漂移、入口/STATUS 是否体积失控、§4 看板是否全未勾选）。脚本已强制 UTF-8 输出，中文 Windows 管道/重定向不再崩。全过才算交接合格。
4. 路径纪律——"大文件进工作盘、小产物回仓库""复制不剪切，别动别人正在跑的路径"。
5. 新 agent（含子 agent）进门第一件事——读完 AGENTS.md（含 STATUS.md）再动手，不靠对话历史、不凭记忆乱猜。STATUS.md 会越长越没人读全——所以任何具约束力的决策（口径/排除清单/选定参数）必须上浮到 AGENTS.md §3 或决策登记表这层有界、必读的位置，别只躺在 STATUS 的长叙事里。取数/建模/复现前先查这层，别去信某个脚本里的硬编码。
6. 关键数字与口径参数单一来源、防漂移——关键数字（均值/百分比/面积等）只在 STATUS.md 或 AGENTS.md §3 一处写定，别处只引用不复述。口径参数/样本集/排除清单（用哪些点、剔哪些、阈值多少）同理：抽进唯一的 config（config/参数.yaml 或一张权威表），所有脚本读它、严禁在多个脚本里各自硬编码——两个脚本对同一集合编码不一致，是最隐蔽的接力事故源（自检看不出、格式检查也看不出）。收工前核对所有文档与脚本间一致性，同一数字差 1% 以上、或同一集合成员不一致，即视为 bug，必须先对齐再交。
7. 坏产物与被取代的脚本一并退役隔离——发现某 agent 的产物错了（数据/图/数字），立即：①目录改名加 _DEPRECATED 后缀或放入 _作废/ 子目录；②在 AGENTS.md §5 铁律节顶部用红字 > ⚠️ 【作废】<路径> 标注（别标在 §3——§3 是累计快照，坏产物标记应和铁律/规范放在同一节）；③更新 §4 看板状态为 [x] + 标注"作废"；④更新 STATUS.md 反映作废；⑤被某决策取代的旧脚本/方法同样退役——脚本顶部加 # _DEPRECATED → 见 <权威脚本/决策> 注释，别让它当成活口径把下家钓进去。绝不只靠记忆说"那个别用"——下游 agent 静默复用坏产物、或抄了一个滞后脚本的口径，比没产出更致命。
8. 开跑先自证身份（多树 / 迁移 / 克隆场景必做）——agent 的第一条动作是交身份回执：实际仓库根、git rev-parse --show-toplevel 与 HEAD、remote，逐项与任务卡写明的预期树标识比对，不一致立刻停下报告，不许继续。🔴 「当前目录是一个有效仓」≠「它是本任务指定的那棵树」——旧 clone 可以有相同 remote、相同分支、相同 AGENTS.md，光验「是不是仓」拦不住。所以任务卡必须给唯一标识——🔴 只能是仓库根的完整绝对路径，不能用 HEAD sha 当标识：HEAD 在 clone 之间相同（会放行错误的树），又会随正常提交变化（会拒绝正确的树）。🔴 也不要用 HEAD 黑名单（「HEAD 不得等于 <错误树 sha>」）——两棵树停在同一个 commit 时（刚 clone/复制完最常见）会把正确的树一起拦掉。🔴 判据只有一条：git rev-parse --show-toplevel == <仓库根的完整绝对路径>。不能只说「在项目根跑」。📌 已知代价：在役树合法迁移时路径会变，判据会在正确的树上失败——这是权衡不是解决：迁移是罕见事件、clone 混淆是常见事件。🔴 所以迁移后必须做三件事（缺一，下一个 agent 就会被正确的判据拦在正确的树外面）： ①【更新在途任务卡的路径判据】 —— 谁做：执行迁移的那个 agent（不是下一个）。 怎么找全：任务卡索引里状态为「待派发 / 进行中 / 待复核」的全部卡，逐张改。 完成证据：🔴 不是「全树命中为 0」——历史报告、归档、只读副本、第三方依赖里留有旧路径是正常且无害的，全树永远归不了零（本课题实测残留 78 处命中）。判据限定在「活动执行面」，而这个面必须是【算出来的闭集】、不是【圈出来的目录】：🔴 入口 = 验收编排器 / 构建脚本里实际被调用的那些文件（从编排器源码里机器提取，别手写清单）；🔴 面 = 从入口出发，沿 import 与 subprocess 调用递归展开的传递闭包。该面内命中为 0；报告要给出闭包是怎么算出来的（入口从哪来、展开到第几层、用什么解析）。🔴 不许用目录名圈定——目录既会漏（打包产物里的脚本副本、动态 import）也会多（废弃文件）。 🔴 落地时必须先定死这三件，否则判据不可比（实测撞出）： · 闭集里的「文件」指什么 —— 建议：源码与被读取的配置；排除产物、缓存、第三方依赖、打包副本。不定义则两个人算出两个数。 · subprocess 展开到哪一层 —— 静态字符串字面量必须展开；变量拼接/配置传入的静态不可判定，🔴 这类调用要在项目里显式登记一份清单，不能假装闭包能自动覆盖。 · 用什么解析 —— 有解析器就用 AST；环境没有解析器时如实标注「文本扫描」，🔴 不许用正则结果冒充 AST 闭包。 📌 面外命中不必逐条证明「无害」（那是散文不是判据）——「不在面内」本身就是判据；面外只需列清单备查。面外命中列成旧路径清单附在报告里，并写明每条为何无害。🔴 别忘了仓库之外：agent/工具的配置里也会写死项目路径（可写根、trusted 项目列表、IDE 工作区、定时任务）。迁移后不更新这些，下一个 agent 会在正确的树里被自己的工具拦住——本技能作者实测撞过：复审 agent 连着两轮交不出报告，根因就是它的 trusted 列表里没有新位置。 ②【在新位置重跑验收确认恢复】 —— 跑哪一套：迁移前那一次的同一套门、同一个编排入口、 同一个解释器（版本写进报告）。判据：🔴 只比 rc 不够——退出码相同而产物错了的情况真实存在。 除逐门 rc 一致外，还要对照关键产物的哈希与各门的汇总行。🔴 「关键产物」不许人工挑——取 manifest 里登记的那一组。 🔴 通常需要两份 manifest（实测撞出：发布 manifest 只登记交付包，不覆盖各门自己的产物）：发布 manifest（交付物 + 哈希）与回归 manifest（每门 → 它的产物路径 + 哈希）。缺哪份就先建哪份。 🔴 汇总行要能机器提取，前提是格式统一——实测同一项目里存在 N/M、PASS/FAIL、ALL_ZERO、自然语言等多种写法。先在项目里约定一条汇总行契约（字段与格式），门按契约打印；🔴 没有契约就不要把「汇总行对照」当判据——否则门会因格式而非事实失败。🔴 人工挑会退化成「挑几个好看的对一对」，和只比 rc 差不了多少。任何一项对不上都要解释，不许因为 rc 绿就放行。 证据：新旧两份 summary + 关键产物指纹一并留档。 ③【旧树留一份指向新位置的标记】 —— 🔴 它的用途是【导航与审计】，不是拦截： 给人看的线索、事后追溯的凭据。不要指望它挡住 agent—— 本条前半段已论证被动标记拦不住（实测：agent 读到「勿用」、还在报告里引用了， 然后照样在那棵树里干了一整轮；后来又有工具在挂着标记的树里写入了文件）。 拦截只靠 ① 的路径判据。
9. 关键测量必须双源交叉——会推翻结论、触发删除/迁移、或决定验收数的测量，必须用两种失效模式不同的方法各测一次；任务卡写明：被测量量的定义、两个来源、容差、裁决方式。🔴 两源不一致 → 结论记 UNKNOWN，停下游动作，禁止多数投票、禁止静默挑一个顺眼的。🔴 另一种同样要停的情形：两源在容差内「一致」，但分别落在验收阈值的两侧（一个判过、一个判不过）——「测量一致」不等于「结论一致」，此时同样记 UNKNOWN 并停下游，不许挑那个判过的。两源分歧首先说明的是**「被测量量或语义没钉住」，不是「哪个工具对」——先钉语义，钉不住就如实记 UNKNOWN。📌 不要照搬工业界的 2oo3 表决：那适用于被测量量无歧义的传感器冗余；而「同一个名词在两个 API 里语义不同」找第三个工具来投票不会解决问题**。📌 与第 6 条的区别：第 6 条管文档里的数字不许各处复述；本条管测量行为本身。

💡 一条真实接力教训（这 3 条规则就是这么来的）：某 agent 要重拟一条曲线，从一个滞后脚本里抄了样本集——那脚本还保留着早该剔除的坏点，而"剔除该点"的决策只躺在 600 行 STATUS 的深处，且两个脚本对它的编码恰好相反。结果该点把 R² 从 0.5 拖到 0.27，对外汇报被推翻。事后看，三处都本可拦住：决策没上浮到有界必读层（规则 5）、口径集合在多脚本里各自硬编码而非单一 config（规则 6）、被取代的旧脚本没打退役标记（规则 7）。信滞后脚本、不信决策记录是这类事故的共同根因。

核心工作流（agent 接力全流程）

一个典型的多 agent 交接生命周期包含 5 个显式步骤。跳过第③步"独立复核"是多数链路污染的根本原因。

① 委派 → ② 执行 + 自检 → ③ 独立复核 → ④ 接收入库 → ⑤ handoff 落盘

步骤详解

产物分级与复核要求（所有产出进下家前必须经过对应的复核阀门）：

① 委派（主控 → 执行 agent） 用标准话术（见下文模板或 assets/委派任务模板.md）明确：读什么、做什么、不碰什么、输出落哪、疑点记哪。

② 执行 + 自检（执行 agent） 执行任务，做完跑一遍 DoD（验收清单），确认输出完整、格式对、无报错。

③ 独立复核（主控或另一 agent 抽验关键数字） 别信自检——执行 agent 自检全过不代表产物无误（已被反复证明不够）。

• 主控或第三 agent 抽验关键数字：守恒（输入总和 ≈ 输出总和？）、边界（有无越界/未裁净？）、格数（行数/像元数符合预期？）、量级（单位是否差 10³？）、一致性（各文档中同一数字是否一致？）。
• 通过→进第④步；不通过→退回执行 agent 修复，并记录 ADR。
• 判据："独立复核通过"是进入下一棒的阀门，不是可选项。
• 🔴 复核方的结论同样要可证伪：复核方给出的判定、测量、归因，与执行方的产出同等地需要证据。复核方用单一来源下的断言、凭记忆写的数字、未实测的推测，不因为出自复核方就更可信。
• 🔴 执行方有权停下来质疑卡面，且质疑本身不计为失败：发现卡面事实有错、判据自相矛盾、或方案在当前环境不可行时，停下来报告比按错卡面跑完一轮更有价值。任务卡由出卡方写，出卡方也会错——没有哪一方是不可质疑的。

④ 接收入库 确认无误的产物正式落位，更新 来源.txt（如果是新数据）和 scripts/README.md（如果是新脚本）。

⑤ handoff 落盘 更新 AGENTS.md §3 现状 + §4 看板 + 写 STATUS.md。保证下个 agent 仅靠仓库 markdown 能续上。

💡 短链路（1–2 个 agent、产物简单）可跳过第③步；产出影响论文结论或下游管线的，必须走完 5 步。

两层续接（缺一不可）

• 硬续接（主依赖）：仓库里的 Markdown，软件无关，任何 agent/人都能读。这是真相源。
• 软续接（增强）：记忆层（Cursor memory / Claude memory）加速检索，但别让核心结论只活在记忆里——必须落回 Markdown。

判据：把所有记忆层删光，下个 agent 只靠仓库 Markdown 也能接上 → 合格。

给 AI agent 委派任务的标准话术

每次委派新 agent 时，用统一格式开头——效果远好于自由发挥。照 assets/委派任务模板.md：

请先阅读 AGENTS.md（含 STATUS.md 了解当前状态）。 不要修改原始数据（<路径>）和已有核心代码（<路径>）。 红线（不可触碰）：<列不可修改的生产参数/路径/数字。例：生产方程参数不可改、最终头条数字不可覆盖> 本次任务只处理阶段 X。 如果发现疑点或新问题，记录到 <指定文档>，不要直接修正。 输出落在 <指定路径>。 本任务已知坑：[列已知风险点] 交付前必自查：[守恒/边界/格数/量级…，逐条过]

这个模板的核心价值：让新 agent 冷启动时立即知道该读什么、不该碰什么、出问题往哪汇报。其中"已知坑"和"必自查"两栏是实战验证过的关键增量——引导 agent 在报完成前自拦截常见错误类型，大幅降低缺陷率。

对于影响论文结论或下游管线的关键任务，在话术末尾追加「交付后安排独立复核」指示（模板末段有进阶示例）。

派发提示词随卡走（推荐）：别让用户每次现填这段话术——每张任务卡末尾内置一份填好的『📋 派发提示词（复制即用）』块（见 assets/任务规划_模板.md T1 末尾）。卡建好时就把目标/边界/输入输出/已知坑/自查/收工填进去，用户要派活时直接复制那段贴给任何 agent（含跨工具、跨技能）即可，零现编。委派任务模板.md 只作字段含义参考。

进阶板块（按需启用，见 references/advanced.md）

核心七板块之外，这些在项目变大时有用，别一上来就全堆上：

• 决策记录（ADR）——记"为什么弃用某方法"，防止下个 agent 重新踩坑、重新质疑已定的事。
• 词汇表——项目特有术语/缩写，新 agent 不用猜。
• 进度日志——带日期戳的变更流水，比 §现在在哪 更细。
• 验收具体化——DoD 写成可运行检查命令，而非"完成了就行"。
• 标准 handoff 摘要——现状/下一步/未解决风险/关键文件路径。
• 命名约定 + 幂等性——输出文件带 _v1/日期/坐标系；可重跑脚本幂等（有缓存跳过）。
• 环境锁——conda env 钉 environment.yml，防跨机器重建漂移。
• 数据快照/不可变输入——原始数据只读带 hash，所有人在副本上动。
• 填好的 AGENTS.md 样例——references/example_filled_AGENTS.md，一个完整范例（虚构项目）。照着填比空模板直观得多。

自定义提醒

• 这套骨架来自真实科研项目（多 agent、多数据集、长管线、云同步）实战。复制后按领域裁剪：纯前端项目可砍掉 §路径约定 的"工作盘"部分；单 agent 小脚本项目 §任务看板 可简化。
• 模板占位符统一用 【待填】，填完删掉。
• 薄指针文件内容统一（见 assets/CLAUDE.md），别在每个里写不同规则——那会破坏"真相只有一份"。
• 不要覆盖用户已有的 AGENTS.md；如果是模式 B 诊断，先读后改、增量修补。