-
Notifications
You must be signed in to change notification settings - Fork 0
meta documentation workflow
徐苏洋 edited this page Aug 29, 2026
·
2 revisions
← 返回 Wiki 首页 | 元文档 · 文档维护规范 | 下一篇：原文档映射表 →
任何涉及需求变更或架构调整的修改，必须首先更新相关文档，然后再进行代码编写。
这一流程对大型项目至关重要，可确保开发过程的可控性。高质量的文档约束是高效 vibe coding 的基础：它能减少不必要的 token 浪费，保障后期优化迭代的可行性。必须避免出现代码与文档大面积不一致的情况，防止项目陷入混乱状态。
本 Wiki 是实现、评审与验收的唯一依据。当代码与文档冲突时：
- 不是「以代码为准，事后补文档」；
- 而是先判定哪一方正确，修正文档后再改代码，或修正代码使其符合文档。
任何「先写代码、以后补文档」的做法都被视为流程缺陷，与漏写测试同级。
文档分四层，约束只能自上而下传递：
需求说明 (01-requirements)
↓ 约束
整体架构 (02-architecture)
↓ 约束
技术细节 (03-details)
↓ 约束
项目排期 (04-roadmap)
- 下层文档不得引入上层未声明的需求、边界或能力。
- 若实现中发现下层需要突破上层约束，必须先修改上层文档并通过评审，不得在下层「就地放宽」。
- 例如：想让 Bot 读取协作会话 → 必须先修改协作能力需求 §23.1，而不是在实现里加一个例外分支。
文中「必须」「不得」「绝不」是强约束，违反即为缺陷。把强约束改为「建议」「尽量」属于需求变更，需走完整评审，不能在实现 PR 中顺手修改。
不同变更类型对应不同的文档更新范围。提交代码前先对照本表确认已更新的文档。
| 变更类型 | 必须先更新 | 通常还需更新 | 评审人 |
|---|---|---|---|
| 新增用户可见能力 | 协作能力需求 | 细节层对应文档、迭代计划、操作状态矩阵 | 产品 + 架构 |
| 调整能力边界／不做清单 | 定位与边界 | 所有引用该边界的下游文档 | 产品 + 架构 + 安全 |
| 新增／调整插件能力 | 插件化架构 能力矩阵 | 初始工程结构 | 架构 |
| 调整三层职责或凭证归属 | 三层总体架构 | 安全与合规 §31 | 架构 + 安全 |
| 新增／修改错误码 | 错误码目录 | 操作状态矩阵 | 架构 |
| 新增术语或品牌化 ID | 术语表 | 引用该术语的文档 | 架构 |
| 调整限流／配额／保留期 | 限流与配额基线 或保留策略基线 | 组织类型与订阅 | 架构 + 运维 |
| 涉及授权、内容授权、出站或执行路径 | 安全与合规 对应节 + §39 清单 | 测试与验收策略 安全回归用例 | 安全（必须） |
| 调整 SLO／容量目标 | 服务等级目标 | 迭代计划 验收段 | 运维 + QA |
| 调整阶段范围或验收条件 | 迭代计划 | 最小可运行骨架 | 项目管理 + QA |
| 关闭一条开放决策 | 开放决策 §50 | 该决策影响的所有文档 | 对应领域 |
| 纯实现重构（不改语义） | 无需更新 | — | 代码评审 |
1. 提出变更 → 说明动机、影响面、涉及的文档层
2. 更新文档 → 按上表更新最上层文档，再逐层向下同步
3. 文档评审 → 对应评审人确认；强约束变更需安全评审
4. 合入文档 → 文档变更单独提交，便于回溯
5. 编写代码 → 实现严格对齐已合入的文档
6. 补充测试 → 触及授权/出站/执行路径的必须补拒绝用例
7. 代码评审 → 评审人对照文档逐条核对
第 2 步与第 5 步不得颠倒顺序，第 4 步与第 5 步建议分开提交。
这是正常情况，处理方式是暂停实现、修正文档：
- 停止当前实现分支上的相关编码。
- 判断是文档描述错误、遗漏，还是需求本身需要调整。
- 按 3.1 流程更新文档并评审。
- 文档合入后恢复实现。
不得在代码中留下与文档冲突的实现并标注 // TODO: 文档待更新。
§50 开放决策中的每条问题都标注了最晚需要答案的阶段。关闭一条决策时：
- 在该条目处标注结论与决策日期。
- 同步更新受该决策影响的需求/架构/细节文档。
- 若结论改变了阶段范围，同步更新迭代计划。
阶段启动前必须关闭标注为该阶段的全部开放决策。
文档变更评审时逐条核对：
- 变更是否从最上层受影响的文档开始修改？
- 是否存在下层突破上层约束而上层未同步的情况？
- 强约束词（必须／不得／绝不）是否被无声弱化？
- 新增的状态、错误码、术语是否已登记到契约与规范附录？
- 新增能力是否在迭代计划中定级（P0–P4 或延后／不做）？
- 触及授权、内容授权、出站或执行路径时，是否补充了对应的安全清单条目与拒绝用例？
- 是否更新了受影响的交叉引用链接？
- 是否有「等实现完再补」的占位内容？（不允许）
代码评审时额外核对：
- 实现是否严格对齐已合入的文档，无未记录的行为差异？
- 部署可变值（限流、配额、保留期、权重）是否从配置读取而非硬编码为常量？
- 新增拒绝路径是否有断言错误码的测试用例？
- 完整保留优于精简：本 Wiki 的既有内容不做删减式「优化」。删除任何规范性内容都属于需求变更。
- 一份文档一个主题：新增内容应归入现有文档；仅当形成独立主题且篇幅可观时才新建文档，并同步更新首页目录与映射表。
- 交叉引用用相对链接：指向具体小节时带锚点，便于跳转。
-
表格中的数字标注来源：凡是可配置的数值，必须注明属于哪个版本化配置（
PlanLimits、RetentionPolicy、OrganizationAnalyticsPolicy等）。 - 不写「TBD」：未定问题一律进入§50 开放决策并标注最晚需要答案的阶段。