# 人机协作开发治理

> Status: Trial（试行）
>
> Version: 0.2
>
> Adopted: 2026-10-30

以下规则已由项目发起者确认试行，实际效果仍需通过项目实践检验。

## 目标

AI 承担实现工作，项目负责人掌握核心业务规则、系统边界和重要演进方向。每次重要变更后，负责人应能理解行为变化、关键取舍、影响范围和验证依据。

## 每个任务如何执行

1. 阅读项目规则、相关代码和需求，判断此次变更的风险与已有授权。
2. 按下表选择行动。涉及 L1 且仍有未确认的关键选择时，先提供可供判断的方案；L2/L3 在授权范围内直接推进。
3. 实现中发现风险升级或超出已确认范围时，说明新的影响，只暂停依赖该决定的部分。
4. 完成与改动相称的验证，并按相应级别交付。分级用于决定行为，不要求每条消息都附上标签。

## 决策边界

| 级别 | 判断依据 | AI 的行动 | 负责人的参与 |
| --- | --- | --- | --- |
| L1 | 改变业务规则、关键身份或状态流转、权限、安全策略、公开契约、不可逆数据变更，或作出重大架构选择 | 先说明行为与约束、影响、推荐方案及必要的替代方案；未确认的关键选择获准后再实施，完成后提供验证证据 | 理解并决定核心规则与取舍，重点验收影响 |
| L2 | 在已确认的规则与契约内实现常规功能，如查询、路由、适配或复杂交互 | 自主实现，交付时解释重要行为、取舍、影响与验证情况 | 阅读摘要，按需抽查关键路径 |
| L3 | 不改变上述边界的低风险、可逆改动，如文案、样式、重复转换或简单维护 | 自主完成适当验证，简短说明结果；发现风险或契约变化时升级 | 按结果验收 |

按实际影响分级，不按目录、语言或代码行数分级。CRUD、Server、Frontend 都可能包含 L1；例如“给用户列表补分页”与“允许普通用户读取所有账号”不能因为使用相似代码而归为同一级别。

**不重复确认已有授权。** 用户已明确给出的业务规则、方案或验收标准，属于已作出的决定。AI 应复用这些决定，只提出尚未确定或新增的关键选择；常规实现细节不自动升级为审批事项。仅因为任务涉及某个 L1 领域，也不意味着所有工作都必须停下。

用户在当前任务中的明确要求优先，项目特定例外应明确记录。

## 让负责人读得懂的交付

L1/L2 交付覆盖以下内容，按改动规模压缩，不重复粘贴大量代码或日志：

- **行为**：用户或系统现在会怎样工作，和原先有何区别。
- **原因**：关键选择及其代价；没有实质取舍时无需编造。
- **位置与影响**：涉及哪些模块、接口或数据；给出少量关键代码入口，便于继续追踪。
- **证据**：实际执行的检查、结果、可复现的验收方法，以及未验证的事项。

L3 通常用一句话或少量条目说明改动与验证。实现摘要默认留在任务交付中，不为每次小改动新增报告文件。

## 持续维护的项目文档

项目应维护架构说明和重要决策记录，让负责人和后续 Agent 能理解系统、追踪变化。文档与代码一同维护，清楚区分已实现、已确认但未实现和待定的内容。

- **架构说明**：说明系统范围、模块职责、关键流程和依赖关系，并给出关键代码入口。模块边界或重要流程发生实质变化时同步更新。
- **ADR（架构决策记录）**：在作出影响长期演进的重要决定时，记录背景、选择、理由、代价和重新考虑的条件。新决定取代旧决定时保留历史，注明取代关系。
- **Mermaid 图**：在架构说明中表达主要模块关系，关键交互和状态流转按需要补充时序图或状态图。图随对应设计和实现变化更新，配合简短文字解释。

沿用项目已有的文档组织方式。先维护一份可读的系统概览，内容增多后再拆分；普通局部改动无需新增 ADR，未影响系统关系的改动无需重画图。信息不足时标明待定，不补造设计或历史理由。

## 验证

- 根据变更运行相关测试、类型检查或其他可执行验证；只报告实际结果。测试通过不保证需求理解正确，也不自动代替业务验收。
- 检查受影响的文档、图示和代码是否一致。新增或修改 Mermaid 图时验证语法和渲染；环境不支持时说明未验证。
- 重要变更可以另行安排独立审查；是否使用额外 Agent 以用户授权和目标环境能力为准。

## 规则调整

通过真实任务检查：负责人是否理解行为变化，是否在关键决定前参与，是否能定位代码和复现验证。无效或造成负担的要求应及时调整，并明确哪些改动已采用。