diff --git a/AGENTS.md b/AGENTS.md index ddd78085..a1820a12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,6 +68,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台。本文 ## P0: 长期参考入口 - CLI 与 route: `docs/reference/cli.md`。 +- 文档治理与过程蒸馏: `docs/reference/docs-governance.md`。 - DevOps hygiene、source truth、worktree 语义合并与清理: `docs/reference/devops-hygiene.md`。 - 开发环境和 D601/Master 边界: `docs/reference/dev-environment.md`。 - HWLAB: `docs/reference/hwlab.md`。 diff --git a/docs/reference/docs-governance.md b/docs/reference/docs-governance.md new file mode 100644 index 00000000..c010f848 --- /dev/null +++ b/docs/reference/docs-governance.md @@ -0,0 +1,53 @@ +# 文档治理与过程蒸馏 + +本文是 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 文档 + +`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 审核为主。完成后只提交本次文档治理相关文件;若工作区存在并行修改,不得把无关文件加入提交。