文档规范（写之前先看这一页）

定位：回答「写文档时该放哪、该长什么样、什么时候该删」。读者：要给本仓添文档的人与 agent。 权威边界：本页只做导航与判据 —— 每条规则的正文只有一处，本页只指路，不复述。那样做是刻意的：同一条规定写两遍，两遍迟早不一致（见下方「一条规则只写一次」）。

一、该放哪：按生命周期分层，不按主题

本仓文档站的分层判据是这篇东西的生命周期，不是它讲什么：

层	放什么	生命周期	在哪
Agent 指引	每次会话都要进上下文的规则	常驻，有字数预算	根 `AGENTS.md` 与各 app 的 `AGENTS.md`
决策记录	为什么这么定、当时否掉了什么	活：决策改了要改它或标记被取代	`content/adr/`
现状文档	现在是什么样、怎么用	活：随代码改，改代码就该改它	`content/monorepo/` · `backend/` · `frontend/` · `shared/`
调研	外部世界的 as-of 快照	冻结：不随代码维护，冲突以代码为准	`content/industry-research/`
归档	带日期的过程文档（设计 / 计划 / 评审）	冻结，但索引里有「归宿」列	`content/archive/`

判断口诀：「它会不会随代码变？」 会 → 现状文档；不会、且讲的是当时的判断 → 归档；不会、且讲的是外部世界 → 调研；一句话就得记住 → agent 指引。

⚠️ 未闭环事项禁止只靠归档了事：一篇里还有开着的待办时，必须先把它们抽到架构待办事项或对应的现行文档，才能归档。归档区的读者不会去追一个还开着的事项 —— 那条待办就等于消失了。
归档区索引必须写「归宿」（哪条结论已被取代、当前该看哪篇）。判据是很直接的：没有归宿列时，「未执行」与「已执行完毕」在表里长得一模一样。
具体条目见 archive/index.md 的「归档约定」一节（那里是唯一真源）。

同一个规定只允许有一个家，其他地方一律写成指针。理由是行为性的，不是洁癖：写两遍就会有两次机会漂移，而漂移不会被任何门禁拦住（没有工具知道你想说的是哪条规定）。

已定的几个「家」：

规定	唯一真源
写 md 时别写原始 `$`、围栏语言要标对、新增页面要登记 sidebar	`apps/docs/AGENTS.md` 的重要约定
ADR 的形态（编号 / Status 枚举 / 必需小节 / index 双向对齐）	`adr/index.md`，由 `pnpm lint:adr` 机械校验
归档的收录判据与「归宿」列	`archive/index.md`
门禁有几段、各段凭什么	`packages/tooling/scripts/src/ci/prepush.ts` 的表（正文里只许写判据）
文档引用的包名 / 仓库路径要真实存在	`pnpm lint:docs-refs` 的实现注释
别写会腐烂的计数	`apps/docs/AGENTS.md` 重要约定 8（根 `AGENTS.md` 只做指路）

读者最需要的不是「这篇讲什么」，而是「我该花时间读它吗、它算不算数」。所以：

> **定位**：这篇解决什么问题。
> **读者**：谁需要读它。
> **权威边界**：它与哪些文档冲突时以谁为准。

本页与 Turbo 缓存边界的开头就是范例。它尤其适合「调研 / 评审 / 一次性分析」这类结论未必长期成立的文档。

把「我没验过的」「我推测的」「依赖外部条件的」集中列出来，而不是让它们散在正文里冒充确定结论。判据：如果一条结论被人当事实引用会造成损失，它就该出现在这一节或带明确限定词。

配套一条更硬的纪律（来自一次真实的评审教训）：「找不到背书」不等于「这是最佳实践」，也不等于「这是反模式」 —— 前者是 absence of evidence，只能如实写成「未找到公开依据」。这与本仓门禁的「宁可漏报不可误报」是同一条口径。

门禁	管什么
`pnpm build:docs`	死链就是构建失败；新增页面没登记 sidebar 也会在评审里被指出来
`pnpm lint:docs-refs`	正文反引号里引用的包名 / 仓库路径必须真实存在
`pnpm lint:doc-ts`	标成 `ts` 的围栏块必须能按 TypeScript 解析
`pnpm lint:adr`	ADR 的形态
`pnpm lint:doc-budget`	常驻上下文文件不许膨胀（用不到一半也算失败）
`pnpm lint:turbo-cache`	文档改动有没有进 docs 构建的缓存键（改文档不重建 = 死链校验被跳过）

加一条门禁要接进哪几处，见架构地图的「新增一条门禁的五步接线清单」。