# 文件树与落地路径：这套规范在一个真实工程项目里长什么样

governed_by：D-014、D-020、D-108
**本文属于载体实例，效力为零。** 它是"文档 + 目录"这一种载体上的**一个**实现，不是落地要求。用任务系统字段、结构化数据或别的形态承载同一套职责，同样满足规范。

## 0. 先给判据，再给树

**一个文件存在的理由是"它承载哪个部件的哪条最小职责"，不是"树里有这一行"。** 遇到树里没画的东西，按这条判据判，不要硬塞进最近的一格（09 §5，D-020）。

树里每一行都标了它对应的章。**看不懂某一行为什么存在，就去读那一章的「最小职责与接口」**——那里是语义，这里只是一种摆法。

<a id="not-14-files"></a>

## 1. 头号结论：14 个部件 ≠ 14 个文件

四个平面 14 个部件是**职责划分**，不是目录结构。按各章 §3 的 L0 形态逐条读下来，**一人一工具的项目落地是 5 个文件**——其余九个部件在这一档要么是某个文件里的一节，要么根本不需要新工件（比如 24 工具与执行环境的 L0 形态就是"命令行加一份工作副本"）。

**照着 14 章建 14 个目录是这套规范最容易犯的错**，也正是它自己要防的失败：规则只增不减、启动固定开销吃掉窗口。

## 2. L0 · 一人一工具（5 个文件）

```
项目根/
├─ AGENTS.md           ← 入口（加载合同是其中一节）。一切从这里进，且只有这一份
├─ ACCEPTANCE.md       ← 要做什么、做到什么算完成
├─ WORK.md             ← 做到哪了、怎么恢复、谁确认过
├─ PLAYBOOK.md         ← 只有本项目知道的做法与踩过的坑
├─ FAILURES.md         ← 出过的错，一份不分区的清单
└─ （代码、测试、构建照项目原样，不动）
```

| 文件 | 承载哪些部件的 L0 职责 | 对应模板 | 对应 01 §3.1 路径 |
|---|---|---|---|
| `AGENTS.md` | **22 上下文装配** 唯一加载清单（写在纸上也算）；**`docs/11-项目知识.md`** 短入口；**21 调度与拆分** 停机条件；**31 守卫** 不可逆动作清单与当前权限范围 | [AGENTS](AGENTS.md)；加载合同一节按 [CONTEXT_MANIFEST](CONTEXT_MANIFEST.md) 填 | `AGENTS.md` |
| `ACCEPTANCE.md` | **10 意图与验收** 一份清单，自己确认、自己冻结；每条带稳定 ID 与可观察结果 | [PRD](PRD.md) | `docs/product/acceptance/` |
| `WORK.md` | **20 状态工件** 进度 / 工作项 / 交接三类**在 L0 允许合成一份**；**32 证据** 完成声明后跟一段六项字段的短记录；**`docs/40-人的检查点与授权.md`** 五处确认由同一人在同一处做；**25 执行者** 本次"合同"——要什么、不要什么、怎么算完成 | [PROJECT_STATUS](PROJECT_STATUS.md) + [WORK_ITEM](WORK_ITEM.md) + [SESSION_HANDOFF](SESSION_HANDOFF.md) | `docs/state/STATUS.md` + `docs/state/work/` + `docs/state/handoff/` |
| `PLAYBOOK.md` | **23 方法库** 几条踩过的坑，每条写清它防的是什么；**12 记忆治理** 一个候选区，自己定期过一遍 | — | `docs/knowledge/PLAYBOOK.md` |
| `FAILURES.md` | **33 评估与演进** 失败 Case 清单加一次定期减法；每条规则写下时就绑定它防的失败与删除条件 | — | `docs/knowledge/FAILURES.md` |

**命名以 [01 §3.1](../标准/01-项目管理标准.md#doc-tree) 为准，本表只是"模板名 → 落地名"的映射；项目实际落点以 `governance/project.yaml` 的 `layout.artifacts` 声明为准。**

**表中与本文其余处的 `NN 章名` 指标准仓 `docs/NN-*.md` 的研究正文，未随发布内嵌。**
表中 11、40 两处直接写成 `docs/NN-*.md` 路径形态而非 `NN 章名`，是同一回事——只是这两章的名字恰好让 `check_single_authority.py` 的数值判据（数字+量词+名词）误判成重复数值声明，换个写法避开，不改变所指。

**没有独立文件的两个部件**：30 验证与测试的 L0 形态是"从验收条目派生几条真能跑的检查"——它们落在项目原有的测试目录里；24 工具与执行环境的 L0 形态就是命令行加一份工作副本。

**L0 的真正门槛不是文件数，是两条纪律**：① 每条状态记录带工作副本身份（仓库 / 分支 / 提交）与时间；② 跑不了的检查写"未定"，不留空、不折算为通过。

## 3. L1 · 一人多会话（+3，主题是"跨会话的连续性"）

```
项目根/
├─ AGENTS.md               ← 增：按当前工作项参数化（一个精确路径的字段）
├─ work/
│  ├─ current.md           ← 从 WORK.md 拆出：实时状态源
│  ├─ handoff.md           ← 交接两半：叙事摘要 + 活动工作集引用
│  └─ artifacts/           ← 工具返回的原文落在可回读位置，不随历史逐轮携带
└─ …（L0 其余不变）
```

对应 01 §3.1 路径：`work/current.md` → `docs/state/work/`（工作项一件一文件），`work/handoff.md` → `docs/state/handoff/`，`work/artifacts/` → `docs/state/artifacts/`。

变的不是文件多少，是**三件事成为默认**：新会话先读状态再动手；会话结束与压缩同等对待、之前先把状态与教训外部化；验证固定为独立会话，只挂产出物与标准。

## 4. L2 · 团队（+5，主题是"责任分离与一致性"）

```
项目根/
├─ AGENTS.md               ← 增：按角色与环境参数化，优先级显式
├─ DECISIONS.md            ← 08 效力元治理：决策 + 生效登记表（唯一效力源）
├─ GATES.md                ← 31：Gate 合同（判据类型 / 检查器自检 / 未知默认值 / 屏障 / 失效探测）
├─ SOURCES.md              ← 11：权威记录源的指派**具名到人**
├─ eval/
│  ├─ diagnostic/          ← 33：按用途分三区，诊断类只给统计摘要
│  ├─ screening/           ← 筛选与最终验证类**不得被会修改 Harness 的执行者读取**
│  └─ manifest.md          ← 实验身份、版本、预先声明的阈值
├─ memory/                 ← 12：候选池，个人与团队分源挂载、按身份过滤
├─ tools/check_*.py        ← 项目自加的检查器（标准自带的随插件分发，命令 `std-check`）；确定性判断下沉为程序
└─ …
```

对应 01 §3.1 路径：`DECISIONS.md` → `docs/decisions/`（每份 `ADR-*.md`，`README` 是索引），`GATES.md` → `governance/GATES.md`；`SOURCES.md`、`eval/`、`memory/` 在 01 §3.1 树里没有对应行。

对应模板：[ADR](ADR.md)（DECISIONS，落地为 `docs/decisions/ADR-*.md`）、[Eval Manifest](EVAL_MANIFEST.md)（eval/manifest）、[架构说明](ARCHITECTURE.md)。[项目状态](PROJECT_STATUS.md)自 L0 起即 `WORK.md` 的摘要部分，见 §2。

**L2 是第六条不变量第一次真正生效的档位**——组织已有系统进入回路，内部 / 外部标注与跨边界写纪律开始有对象。

## 5. L3 · 无人值守（+3，前置条件是"有一个判定器"）

```
项目根/
├─ policy/budget.md        ← 预算与范围在创建时固化，执行中只能收窄
├─ policy/judges.md        ← 判定器及其覆盖域、归属人（自动晋升的允许域）
├─ ops/liveness.md         ← 活性巡检；待补偿清单非空即不得宣告完成
└─ …
```

**L3 的准入条件不是工具，是一句话**：有一个不需要人在场就能拒绝坏输出的判定器。没有它，前面三档做得再全也上不了 L3。

## 6. 哪些默认加载，哪些按需——这是 22 章的心脏

**树画出来是给人看的；每次推理实际看见什么，只由 `AGENTS.md` 的加载合同一节决定。**

| | L0 | L1 | L2 |
|---|---|---|---|
| **默认加载** | `AGENTS.md`、`ACCEPTANCE.md` 的当前条目、`WORK.md` | + 当前工作项、`handoff.md` | + 生效登记表、角色可见的能力集 |
| **按需** | `PLAYBOOK.md` 按触发条件、`FAILURES.md` 只在做删减或补绑定时 | + `artifacts/` 按引用回源 | + `eval/`、`memory/` 按身份过滤后检索 |
| **不加载** | 历史、无关模块、聊天记录、已取代的决策全文 | 同左 | 同左 |

三条要点：**清单只做路由，不复制被路由文档的正文**；**链接不递归展开**；**"可能有用"不是加载理由，但给少了也有补偿成本**。

## 7. 六条实测错法（来自本仓库 30 条真实失败，不是设想）

1. **不要抄副本。** 版本号、提交号、条数、状态值——任何"某处已有权威"的值，在别处写一份便于阅读的投影，它必然漂移。本仓库这一条**复发六次以上**，每次都是同一方在刚删掉上一份之后又新造一份。
2. **不要建第二份清单。** 第二份加载清单、第二份议程、第二份状态登记处——建了就要同步，同步就会忘。
3. **不要按状态拆表。** 把"待办 / 已完成"物理分成两张表，行的**位置**就成了状态值的第二处表示，每次变更要人工搬行。
4. **新检查的验收不是"跑一遍 PASS"。** 四步：① 验字节（控制字符在 grep 里隐身）② 注入前先断言待替换串存在 ③ 反例测试确认它真报 ④ 跑全仓看误伤。**任一步拿到空输出一律记未定**——空输出最常见的原因是采集根本没跑起来。本仓库写过的检查里，有两条曾"恒为通过、其实不检查"，而"跑一遍看到 PASS"完全察觉不到。
5. **引用片段要写清外延。** `文件#锚点` 指的是"锚点到下一个锚点"还是"锚点到文件尾"？不写清，同一项会被两个人算出相差 35% 的两个体量。
6. **"当前工作项"字段填工作项，不要填一份登记表。** 填了登记表，它就会和加载清单里的某一行撞成同一个片段，于是同一段内容既必须读又不许读。

## 8. 对照：本仓库自己就是一个 L1 实例

| 本仓库的文件 | 对应上表 | 差异 |
|---|---|---|
| 标准仓 `CONTEXT_MANIFEST.md` | `AGENTS.md` 的加载合同一节 | 单列成一份文件；多了按运行类型的两个视图列（交付型 / 事实型） |
| 标准仓 `PROJECT_STATUS.md` | `WORK.md` 的摘要一半 | — |
| 标准仓 `docs/决策日志.md` | `DECISIONS.md`（L2 项） | 本仓库提前建了，因为它的产出**就是规则** |
| 标准仓 `docs/失败Case清单.md` | `FAILURES.md` | 仍是 L0 形态：不分区 |
| 标准仓 `docs/附录-载体实例/仓库工作须知.md` | `PLAYBOOK.md` | — |
| 标准仓 `docs/附录-载体实例/*.py` | `tools/check_*.py`（L2 项） | 同样提前建了 |
| — | `ACCEPTANCE.md` | **没有**。本仓库不交付软件，没有验收条目实例——这也是它无法完整检验自身的原因 |

**最后一句**：这棵树是一种摆法。真正不变的是各章「最小职责与接口」里那几句话——**换工具时重写的是这棵树，不是那几句话**。