# 文档治理与过程蒸馏

- 本文适用于：

  - `AGENTS.md`、`CLAUDE.md` 类入口文档；
  - `docs/reference/*.md`；
  - skill 文档；
  - 过程文档蒸馏。

- 使用要求：

  - 具体任务先加载 `$docs-spec`；
  - 本文只沉淀长期稳定规则和本仓判定标准。

## 中文与单行治理

- 自然语言标题和正文统一使用中文；发现非中文内容时先翻译再继续。
- 新写内容必须使用中文。
- 一个自然语言单行不得堆叠多个独立约束、步骤、条件或并列事实。
- 发现过长单行时立即处理，不等待集中清理。
- 过长内容一律按语义拆成主项与下级列表；禁止只做自然换行或物理折行来伪装拆分。
- 命令、路径、URL、代码、协议名、字段名和机器可读单值可以保留原文或长行。

## 顶级入口

- `AGENTS.md` 职责：

  - 只作为项目级顶级索引；
  - 用于快速定位命令、入口、技能和长期参考文档；
  - 不承载实现细节、参数说明或长流程；
  - 不承载历史排障、日志、JSON、trace dump 或一次性过程记录。

- 同级入口文档规则：
  - 与 `AGENTS.md` 具有同等作用的入口文档只保留一行 `@AGENTS.md`；
  - 避免 `CLAUDE.md`、`AGENTS.md` 或其他入口出现多套口径。

- 命令与工作流索引：

  - 每个命令或工作流最多保留一条主索引；
  - 多个功能点使用短子列表；
  - 子列表分别指向对应的 `docs/reference/*.md` 或 skill；
  - 子列表只写一句话摘要；
  - 不展开背景和用法。

`AGENTS.md` 的体积、拆分和输出 dump 治理细则见 `docs/reference/agent-instruction-hygiene.md`。

## 长期参考

- `docs/reference/` 内容边界：

  - 只记录长期稳定、可重复复用的入口、前置条件和约束；
  - 记录职责边界和判定标准；
  - 不写日期、一次性执行记录或实测流水账；
  - 不写 changelog 式内容或容易过时的临时结论。

- 详细说明归属：

  - 优先进入职责明确的独立参考文档；
  - 再回到 `AGENTS.md` 维护一句话索引；
  - 跨文档重复时，选择或新建唯一权威出处；
  - 其他位置只交叉引用。

- 知识更新分为：

  - 增加新知识；
  - 删除过时知识；
  - 修正错误知识；
  - 合并重复知识。

- 新旧材料冲突时：

  - 以新的稳定结论替换旧结论；
  - 删除或压缩旧说法。

`docs/reference/` 不维护 YAML/config 已能表达的以下内容作为第二真相：

- 业务策略数值和阈值；
- 冷却时间和退避窗口；
- 容量或价格。

- 长期参考只保留：

  - “数值以 YAML/config 为准”；
  - 同步入口；
  - 渲染入口；
  - 验证入口。

- 业务策略数值规则：

  - 不得要求新增合同测试；
  - 不得增加代码硬范围；
  - 不得增加 schema 内容校验；
  - 配置校验只检查格式、类型、必填项和可渲染性。

- 涉及 skill 的长期参考必须写清该 skill 与以下内容的具体关系：

  - 当前项目代码和硬件；
  - 当前目录和运行面；
  - 当前判定标准。

- 通用用法归属：

  - 通用安装直接引用对应 `SKILL.md`；
  - CLI 参数和子命令直接引用对应 `SKILL.md`；
  - 完整用法直接引用对应 `SKILL.md`；
  - 不得在 reference 中复制一份。

## Skill 文档

- `SKILL.md` 是短入口和路由表，不能承载：

  - 完整 runbook；
  - 历史排障；
  - 长命令矩阵；
  - 大段背景；
  - 内容变长时，拆到同 skill 的 `references/`。

- reference 拆分规则：

  - 按职责、生命周期和读取场景组织；
  - 部署、账号管理、公开暴露、验收、排障和禁止事项分别成文件；
  - 禁止重新堆成 `references/full.md`、`all.md` 或 `guide.md`；
  - 禁止创建其他变相超级 Markdown。

- reference 路由规则：

  - `SKILL.md` 必须明确何时读取哪个 reference；
  - Agent 按任务加载最小必要文件；
  - 单个 reference 继续变长时，继续按职责拆分；
  - 在旧文件保留短索引或迁移说明。

## 过程文档蒸馏

- 过程文档定义：
  - 属于开发过程中的一手历史资料；
  - 通常带有时间戳、阶段性判断和临时结论；
  - 蒸馏时不得篡改过程文档本身。
- 蒸馏顺序：
  - 从旧到新；
  - 大文件采用滑动窗口；
  - 读一段就更新一次长期参考；
  - 不等全部读完再统一整理。

- 过程结论规则：

  - 新的稳定结论覆盖旧结论；
  - 长期参考只简述总体发展过程和关键节点；
  - 避免把发展过程写成流水账；
  - 越早期的过程越应压缩。

- 重要过程节点：
  - 可以交叉引用原始过程文档、issue 或 PR；
  - 长期参考必须保留可直接复用的当前规则、边界和验证入口。

## 本机工作流

- 以下工作可在当前主 worktree 处理，不需要新建 `.worktree` 或 PR：

  - 单纯文档；
  - `AGENTS.md` 和 `docs/reference/*.md`；
  - skill 规则和 runbook；
  - 过程文档蒸馏。

开始前必须按本仓 P0 规则快进到最新 `origin/master`，并保留并行脏改。

- 本机工作流例外边界：
  - 只覆盖文档和规则本身；
  - 不得夹带源码、配置、部署或 Secret；
  - 不得夹带运行面变更或 issue lifecycle 写操作。

- 收尾要求：

  - 以最小语法、链接、grep 和 diff 审核为主；
  - 只提交本次文档治理相关文件；
  - 工作区存在并行修改时，不得把无关文件加入提交。
