完善AI-NSES文档治理规则

2026-07-24 10:05:28 +07:00
parent 5df2910465
commit 79fb1aef2d
12 changed files with 424 additions and 25 deletions
--- a/docs/import/reusable/ai-native-software-engineering-standard.md
+++ b/docs/import/reusable/ai-native-software-engineering-standard.md
@@ -2,7 +2,7 @@

 | 项 | 内容 |
 | --- | --- |
-| Version | 0.1 |
+| Version | 0.2 |
 | Scope | 可复用软件工程标准 |
 | Audience | 人类开发者、产品人员、架构师、AI Agent |

@@ -137,10 +137,12 @@ project/

 职责：记录具体功能规格。每一个 Feature 对应一个 Spec。

-生命周期：Draft -> Approved -> Implemented -> Archived。
+生命周期：Draft -> Approved -> Implemented -> Superseded / Archived。

 规则：Spec 完成以后保留，不删除。

+如果既有项目已经有 `docs/project/requirements/` 等历史目录，可以通过项目级 adoption 文档建立映射；但新增重要 Feature 仍应使用 Spec 模板的结构表达背景、目标、非目标、业务规则、接口或交互契约、验收标准和测试范围。
+
 ### docs/guidelines/

 读者：开发、测试和 AI Agent。
@@ -208,6 +210,70 @@ Idea

 Documentation Update 属于 Definition of Done，不能跳过。

+### 8.1 Definition of Ready
+
+进入实现前，复杂 Feature 或会影响跨模块协作的变更必须满足：
+
+- 需求来源明确，知道是谁提出、解决什么问题。
+- 目标和非目标明确，避免实现时扩大范围。
+- 受影响的用户、业务流程、接口、数据模型、权限、安全、审计或外部系统边界已经列出。
+- 前端、后端、测试或第三方系统的分工已经明确。
+- 验收标准已经可测试，至少有主要 Given / When / Then 场景。
+- 未确认问题已经列出；如果问题影响业务规则或安全边界，应先确认再实现。
+
+简单 bugfix 或纯内部重构可以不用新建完整 Spec，但仍应在任务说明中写清目标、范围和验证方式。
+
+### 8.2 Definition of Done
+
+Feature 完成前必须确认：
+
+- 实现满足本次 Spec、Change Request 或任务说明。
+- 相关自动化测试、类型检查、lint、构建或手工验证已经运行，或明确说明无法运行的原因。
+- 受影响的需求、Spec、Workflow、Domain、ADR、接口契约、安全边界和 Project State 已同步。
+- 对外或跨团队契约发生变化时，调用方文档和测试说明已同步。
+- 没有把 Secret、真实客户数据、构建产物、临时文件或无关本地变更纳入交付。
+
+### 8.3 Change Request
+
+当一个已 Approved 或 Implemented 的 Spec 发生需求变更时，优先新增或更新 Change Request，而不是把讨论散落到聊天记录中。
+
+Change Request 至少说明：
+
+- 变更背景。
+- 原规则。
+- 新规则。
+- 影响范围。
+- 迁移或兼容策略。
+- 前端、后端、测试和文档待办。
+- 验收标准。
+
+小变更可以直接追加到原 Spec 的“变更记录”章节；跨前后端、权限、安全、数据模型或第三方契约的变更应单独成文。
+
+### 8.4 Traceability Matrix
+
+复杂 Feature 应维护需求追踪表，用于连接需求、实现、测试和文档。
+
+推荐字段：
+
+| 需求项 | 后端状态 | 前端状态 | 测试状态 | 文档位置 | 当前状态 |
+| --- | --- | --- | --- | --- | --- |
+| 示例需求 | Pending / Done / N/A | Pending / Done / N/A | Pending / Done / Blocked | Spec / Contract / README | Draft / Approved / Implemented |
+
+追踪表可以放在 Spec、Project State 或专项 checkpoint 文档中；关键是让新 Agent 能快速判断“文档写了但代码没做、代码做了但文档没写、后端做了但前端没做、前端需要但后端没做”。
+
+### 8.5 Agent Handoff
+
+给 AI Agent 分派任务时，建议使用统一交接结构：
+
+- 背景：为什么做。
+- 目标：本次必须完成什么。
+- 边界：本次不做什么。
+- 必读文档：从入口文档到具体 Spec / Contract。
+- 影响范围：后端、前端、测试、第三方、数据、权限、安全、审计。
+- 验收标准：可执行或可观察的检查项。
+- 允许写操作：是否允许改代码、改文档、造数据、点确认按钮或清理测试数据。
+- 输出要求：代码位置、测试结果、文档更新清单、风险和下一步建议。
+
 ## 9. AI Working Principles

 - AI 应先理解，再开发。
@@ -217,6 +283,7 @@ Documentation Update 属于 Definition of Done，不能跳过。
 - UI 默认保持一致性，不过度设计。
 - 代码修改前先确认目标、边界和验收标准。
 - 涉及接口、安全、权限、数据模型或外部系统时，先读相关契约文档。
+- 涉及跨 agent 协作时，先确认 Spec、Change Request 或 handoff 是否足够清楚。

 ## 10. Documentation Rules

@@ -230,6 +297,8 @@ Documentation Update 属于 Definition of Done，不能跳过。

 不要维护一个 8000 行的 `DOMAIN.md`。应该按对象拆分成 `Order.md`、`Guest.md`、`Hotel.md`、`Email.md`、`Task.md`。

+通用标准只规定文档职责和流程。具体项目可以新增 Project Overlay，记录本项目专属的需求门禁、核心概念、交付格式和安全边界；Overlay 不应反向污染通用标准。
+
 ## 11. Documentation Update Rules

 完成 Feature 后必须检查：
@@ -241,6 +310,8 @@ Documentation Update 属于 Definition of Done，不能跳过。
 - Spec 是否需要改为 Implemented 或补充结果。
 - Project State 是否需要更新。
 - 安全、权限、接口契约是否需要同步。
+- Traceability Matrix 是否需要更新。
+- Change Request 是否需要关闭、合并到 Spec 或标记为 Superseded。

 如果没有文档变化，应明确说明：

@@ -258,6 +329,7 @@ No documentation changes required.
 AGENTS.md
 -> CONTEXT.md
 -> PROJECT_STATE.md
+-> 项目级 Overlay 或 Adoption 文档
 -> 相关 Domain
 -> 相关 Workflow
 -> 相关 Spec 或 ADR
@@ -274,3 +346,5 @@ AI-NSES 不限制编程语言、框架、数据库或 AI 模型。
 它适用于 Codex、Claude Code、Gemini CLI、Cursor，以及未来任何 AI Agent。

 它描述的是软件工程，不是某个具体工具。
+
+具体项目如果有更强的安全、合规、业务流程或多 agent 协作要求，应通过项目级 Overlay 补充，不直接把项目私有业务规则写入本通用标准。
--- a/docs/import/reusable/ai-native-templates/AGENT_HANDOFF.template.md
+++ b/docs/import/reusable/ai-native-templates/AGENT_HANDOFF.template.md
@@ -0,0 +1,57 @@
+# Agent Handoff 标题
+
+## 1. 背景
+
+说明本次任务从哪里来，要解决什么问题。
+
+## 2. 目标
+
+- 必须完成事项 1：
+- 必须完成事项 2：
+
+## 3. 边界
+
+- 不做事项 1：
+- 不做事项 2：
+
+## 4. 必读文档
+
+1. `AGENTS.md`
+2. `CONTEXT.md`
+3. `PROJECT_STATE.md`
+4. 项目文档索引
+5. 本次相关 Spec / Change Request / Contract
+
+## 5. 影响范围
+
+| 范围 | 是否影响 | 说明 |
+| --- | --- | --- |
+| 后端 | 是 / 否 |  |
+| 前端 | 是 / 否 |  |
+| 数据库 | 是 / 否 |  |
+| 权限 / 安全 / 审计 | 是 / 否 |  |
+| 第三方系统 | 是 / 否 |  |
+| 测试数据 | 是 / 否 |  |
+| 文档 | 是 / 否 |  |
+
+## 6. 验收标准
+
+- Given / When / Then：
+- Given / When / Then：
+
+## 7. 允许操作
+
+- 是否允许改代码：
+- 是否允许改文档：
+- 是否允许造测试数据：
+- 是否允许执行写操作：
+- 是否允许清理数据：
+
+## 8. 输出要求
+
+- 完成内容：
+- 未完成内容：
+- 代码或文档位置：
+- 测试命令和结果：
+- 风险：
+- 下一步建议：
--- a/docs/import/reusable/ai-native-templates/CHANGE_REQUEST.template.md
+++ b/docs/import/reusable/ai-native-templates/CHANGE_REQUEST.template.md
@@ -0,0 +1,61 @@
+# Change Request 标题
+
+| 项 | 内容 |
+| --- | --- |
+| 状态 | Draft / Approved / Implemented / Superseded / Archived |
+| 日期 | YYYY-MM-DD |
+| 提出人 | 按实际填写 |
+| 关联 Spec | 路径或编号 |
+| 影响范围 | Backend / Frontend / Test / Docs / Security / Integration |
+
+## 1. 变更背景
+
+说明为什么要改，当前问题是什么。
+
+## 2. 原规则
+
+- 原规则 1：
+- 原规则 2：
+
+## 3. 新规则
+
+- 新规则 1：
+- 新规则 2：
+
+## 4. 影响范围
+
+| 范围 | 是否影响 | 说明 |
+| --- | --- | --- |
+| 用户流程 | 是 / 否 |  |
+| 后端接口 | 是 / 否 |  |
+| 前端交互 | 是 / 否 |  |
+| 数据模型 | 是 / 否 |  |
+| 权限 / 安全 / 审计 | 是 / 否 |  |
+| 第三方契约 | 是 / 否 |  |
+| 测试数据 / 迁移 | 是 / 否 |  |
+
+## 5. 兼容和迁移
+
+- 是否兼容旧数据：
+- 是否需要数据清理：
+- 是否影响生产：
+- 回滚或恢复方式：
+
+## 6. 验收标准
+
+- Given / When / Then：
+- Given / When / Then：
+
+## 7. Agent 待办
+
+| Agent / 角色 | 待办 | 验证 |
+| --- | --- | --- |
+| 后端 |  |  |
+| 前端 |  |  |
+| 测试 |  |  |
+| 文档 |  |  |
+
+## 8. 文档更新
+
+- 需要更新的文档：
+- 不需要更新的文档及原因：
--- a/docs/import/reusable/ai-native-templates/README.md
+++ b/docs/import/reusable/ai-native-templates/README.md
@@ -18,4 +18,6 @@
 - `WORKFLOW.template.md`：业务流程文档模板。
 - `ADR.template.md`：架构决策记录模板。
 - `SPEC.template.md`：功能规格模板。
+- `CHANGE_REQUEST.template.md`：已确认需求的变更请求模板。
+- `AGENT_HANDOFF.template.md`：给后端、前端、测试或文档 agent 的任务交接模板。
 - `ARCHITECTURE.template.md`：架构说明模板。
--- a/docs/import/reusable/ai-native-templates/SPEC.template.md
+++ b/docs/import/reusable/ai-native-templates/SPEC.template.md
@@ -2,9 +2,11 @@

 | 项 | 内容 |
 | --- | --- |
-| 状态 | Draft / Approved / Implemented / Archived |
+| 状态 | Draft / Approved / Implemented / Superseded / Archived |
 | 日期 | YYYY-MM-DD |
 | 负责人 | 按实际填写 |
+| 需求来源 | 用户 / 客户 / 业务方 / 内部发现 |
+| 关联 Change Request | 可为空 |

 ## 1. 背景

@@ -24,26 +26,50 @@

 说明谁会使用这个能力，在哪些场景使用。

-## 5. 业务规则
+## 5. Definition of Ready
+
+- 需求来源已确认：
+- 目标和非目标已确认：
+- 影响范围已确认：
+- 权限、安全、审计和数据边界已确认：
+- 前后端 / 测试分工已确认：
+- 未确认问题已列出：
+
+## 6. 业务规则

 - 规则 1：
 - 规则 2：

-## 6. 接口或交互契约
+## 7. 接口或交互契约

 说明请求、响应、权限、安全、审计和兼容性要求。

-## 7. 验收标准
+## 8. 需求追踪表
+
+| 需求项 | 后端状态 | 前端状态 | 测试状态 | 文档位置 | 当前状态 |
+| --- | --- | --- | --- | --- | --- |
+| 需求 1 | Pending / Done / N/A | Pending / Done / N/A | Pending / Done / Blocked |  | Draft / Approved / Implemented |
+
+## 9. 验收标准

 - Given / When / Then：
 - Given / When / Then：

-## 8. 测试范围
+## 10. 测试范围

 - 单元测试：
 - 集成测试：
 - 手工验证：

-## 9. 文档更新
+## 11. Definition of Done
+
+- 实现满足 Spec：
+- 测试已运行或说明无法运行原因：
+- 需求追踪表已更新：
+- Project State 已更新：
+- 接口、安全、权限、审计、集成契约已同步：
+- 无 Secret、真实数据、构建产物或无关本地变更：
+
+## 12. 文档更新

 完成后检查 Domain、Architecture、Workflow、ADR、Project State 是否需要更新。