# 文档治理与过程蒸馏 - 本文适用于： - `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 审核为主； - 只提交本次文档治理相关文件； - 工作区存在并行修改时，不得把无关文件加入提交。