# Multi Agent Project

> 初始化或重构"跨 agent、跨软件可续接"的项目文档骨架。当用户开新项目/新课题、想建立多智能体协同工作流、提到 AGENTS.md / CLAUDE.md / GEMINI.md / .cursorrules / copilot-instructions / 项目记忆 / agent 接力 / 换软件继续 / 上下文丢失，或现有项目缺统一入口导致每个 agent 反复问相同问题、互相覆盖、接不上前任工作时使用。即使是"帮我建个项目文档""怎么让多个 AI 工具协同""开个新课题要准备什么"这类模糊请求也适用。

- Skill: `aduhappy/multi-agent-project` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add aduhappy/multi-agent-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aduhappy/multi-agent-project/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aduhappy (https://skillmd.com/u/aduhappy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aduhappy/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`）**：

| 工具 | 用户级安装路径 | 项目级安装路径 |
|---|---|---|
| **ZCode / Codex CLI** | `~/.agents/skills/multi-agent-project` | `<项目>/.agents/skills/multi-agent-project` |
| **Claude Code** | `~/.claude/skills/multi-agent-project` | `<项目>/.claude/skills/multi-agent-project` |
| **Cursor** | N/A（用 rules） | `.cursor/rules/`（现代格式）或 `.cursorrules`（legacy）|

通用原则：
- 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 或主控） |
| 论文结论/头条数字 | 端点均值、百分比变化、方向判定 | **必须独立复核**（复核人不同） |
| 数据整理/可视化 | CSV 清洗、图表生成 | 自检够（有自动化检查时） |

**① 委派（主控 → 执行 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 诊断，先读后改、增量修补。