pikasTech-unidesk/docs/reference/docs-governance.md

文档治理与过程蒸馏

• 本文适用于：

  • 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 审核为主；
  • 只提交本次文档治理相关文件；
  • 工作区存在并行修改时，不得把无关文件加入提交。