文档治理与过程蒸馏

本文是 UniDesk 本机文档治理的长期参考，适用于 AGENTS.md、CLAUDE.md 类入口文档、docs/reference/*.md、skill 文档和过程文档蒸馏。具体任务仍先加载 $docs-spec；本文沉淀长期稳定规则和本仓判定标准。

顶级入口

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

与 AGENTS.md 具有同等作用的入口文档只保留一行 @AGENTS.md，避免 CLAUDE.md、AGENTS.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 与当前项目代码、硬件、目录、运行面和判定标准的具体关系。通用安装、CLI 参数、子命令和完整用法直接引用对应 SKILL.md，不要在 reference 中复制一份。

SKILL.md 是短入口和路由表，不承载完整 runbook、历史排障、长命令矩阵或大段背景。内容变长时，拆到同 skill 的 references/。

拆分后的 reference 必须按职责、生命周期和读取场景组织，例如部署、账号管理、公开暴露、验收、排障、禁止事项分别成文件。禁止把内容重新堆成 references/full.md、all.md、guide.md 或其他变相超级 Markdown。

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

过程文档是开发过程中的一手历史资料，通常带有时间戳、阶段性判断和临时结论。蒸馏时不得篡改过程文档本身。

蒸馏顺序从旧到新。大文件采用滑动窗口处理，读一段就更新一次长期参考，不等全部读完再统一整理。

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

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

单纯文档、AGENTS.md、docs/reference/*.md、skill 规则、runbook 和过程文档蒸馏可在当前主 worktree 处理，不需要新建 .worktree 或 PR。开始前必须按本仓 P0 规则快进到最新 origin/master，并保留并行脏改。

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

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