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