governance

治理文档

创建和管理治理文档：用于架构决策的 ADR，以及用于需求变更的 CR。

文档选择

需求	文档	指南
技术／架构决策	ADR	reference/adr-guide.md
需求或范围变更	CR	reference/cr-guide.md

治理引用边界

治理标识符（CR-、ADR-、FR-、NFR- 和 AC- 前缀后跟数字）应出现在 docs/ 下的治理文档库中，以及 Git 元数据中——包括提交消息、分支名称和拉取请求描述——不得写入源代码、测试名称或面向用户的文档。若要将实现关联回对应的治理文档，请在提交消息中写入标识符，并在代码中描述行为本身；完整的模式定义、允许和禁止使用的范围以及原因，请参阅 reference/cr-guide.md#governance-reference-boundary。

ADR 工作流

仅文档任务。 创建 ADR 是一项仅涉及文档的任务。无需编译代码、运行测试或执行 lint。

创建架构决策记录时，请使用以下检查清单：

- [ ] Read the template: templates/ADR.md
- [ ] Check docs/adr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/adr/ADR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Set status to "proposed"

模板 frontmatter： 创建的 ADR 应包含反映具体决策的 name 和 description，且不包含模板元数据。模板的 name 和 description 描述的是模板本身，因此应替换；模板不包含其他需要复制的元数据。

严格要求：

• 文件命名：ADR-NNNN-{title}.md（四位数字、小写字母、连字符）
• 初始状态：proposed
• 位置：项目的 docs/adr/ 文件夹

灵活要求（视具体情况调整）：

• 备选方案部分的详细程度
• 所列后果的数量
• 是否包含图表（复杂决策建议包含）

CR 工作流

仅文档任务。 创建 CR 是一项仅涉及文档的任务。无需编译代码、运行测试或执行 lint。

创建变更请求时，请使用以下检查清单：

- [ ] Read the template: templates/CR.md
- [ ] Check docs/cr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/cr/CR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Write acceptance criteria in Gherkin format
- [ ] Decide whether the change has a user surface: fill in the Model-Based Testing section if it does, remove the section if it does not
- [ ] Set status to "proposed"

模板 frontmatter： 创建的 CR 应包含反映具体变更请求的 name 和 description，且不包含模板元数据。模板的 name 和 description 描述的是模板本身，因此应替换；模板不包含其他需要复制的元数据。

严格要求：

• 文件命名：CR-NNNN-{title}.md（四位数字、小写字母、连字符）
• 初始状态：proposed
• 位置：项目的 docs/cr/ 文件夹
• 验收标准：Gherkin 格式（Given-When-Then）
• 需求关键词：RFC 2119（MUST、SHOULD、MAY）

灵活要求（视具体情况调整）：

• 文档长度（复杂变更至少 250 行）
• 图表数量
• 影响评估的深度
• 是否包含基于模型的测试部分（由用户界面测试决定）

实施已编写的 CR

CR 创建后，reference/cr-implementation-workflow.md 将提供与项目无关的 Agent 团队工作流，涵盖从评审到分阶段实施、最终定稿、验证、差距修复和文档编写的全过程。该工作流遵循宿主项目自身的构建、lint 和测试约定。

模板

• ADR：templates/ADR.md
• CR：templates/CR.md

参考指南

有关生命周期的详细信息、最佳实践和示例，请参阅：

• ADR 指南：reference/adr-guide.md
• CR 指南：reference/cr-guide.md
• CR 实施工作流：reference/cr-implementation-workflow.md — 用于实施现有 CR 的 Agent 团队工作流

提交消息格式

治理文档由人类负责提交。准备提交时，请使用以下格式：

• ADR：docs(adr): add ADR-NNNN {title}
• CR：docs(cr): add CR-NNNN {title}