# AI Coding Production Control Framework：AI 写完的代码如何不失控的工程规范

> 版本：v1.0
> 生成日期：2026-05-17
> 文档定位：AI 编程项目的架构约束文档、Agent 工作入口文档、AI 生成代码验收规范、工程团队协作规范、代码评审与 Release Gate、React + Python 前后端分离项目示例。
> 核心观点：**人的职责不是把 AI 生成的每一行代码都读完，而是先定义系统边界、架构抽象、接口契约、验收标准和高风险人工 Review 点，再让 AI 在这些约束内放大实现能力。**

---

## 总目录

- 第一卷：AI Coding 可控性通用框架
  - 0. 文档说明
  - 1. 核心问题：AI 写的代码为什么会失控
  - 2. AI Coding 三层控制模型
  - 3. 人与 AI 的职责边界
  - 4. AI Coding 失败模型与风险域
  - 5. 项目文档地图：AGENTS.md 作为 Agent 入口
  - 6. 第一层：架构层规范
  - 7. 第二层：模式与抽象层规范
  - 8. 第三层：实现层规范
  - 9. AI Coding 工作流
  - 10. AI 任务拆分与变更边界
  - 11. 代码评审策略：不逐行盯死，但要盯住风险
  - 12. 测试、CI 与质量门禁
  - 13. 安全、隐私、依赖与供应链
  - 14. 文档、证据留存与可追溯性
  - 15. 团队治理、角色分工与持续改进
  - 16. 通用 Release Gate
- 第二卷：React + Python 前后端分离项目示例
  - 17. 示例项目边界
  - 18. 推荐仓库结构
  - 19. AGENTS.md 最小可用模板
  - 20. 架构规范模板
  - 21. API 契约规范模板
  - 22. React 前端模式与抽象规范
  - 23. Python 后端模式与抽象规范
  - 24. 数据模型、状态与错误处理规范
  - 25. 测试策略模板
  - 26. 高风险人工 Review 清单
  - 27. React + Python Release Gate
- 第三卷：模板、映射关系与落地清单
  - 28. 三层控制模型映射表
  - 29. 不同项目阶段的最低文档集
  - 30. 不同 AI 工具的指令文件映射
  - 31. AI Coding Prompt 模板
  - 32. PR / Review 模板
  - 33. 常见失控场景与处置方案
  - 34. 与移动端生产可上线规范的衔接
  - 35. 补充风险
  - 36. 待确认问题
  - 37. 建议下一步拆分的专项文档
  - 附录 A：官方资料索引

---

# 第一卷：AI Coding 可控性通用框架

## 0. 文档说明

### 0.1 文档目的

本规范用于解决 AI 自动化编码、AI pair coding、Codex / Claude Code / Copilot / Cursor 等 Agent 参与开发后出现的典型问题：

> 功能看起来做完了，代码也能跑，但团队打开代码后发现系统结构不清楚、模块关系说不清、接口契约不稳定、抽象层混乱、维护者没有掌控感。

这类问题的本质不是“AI 代码一定不能用”，也不是“人必须逐行读完所有 AI 代码”。真正的问题是：

- 在 AI 写代码前，系统边界没有定义清楚。
- 架构层没有被团队确认。
- 模块划分和抽象模式没有被写成可执行规范。
- API 契约、数据流、错误处理、测试策略没有前置。
- AI 在实现层自由生长，形成了局部正确但全局混乱的系统。
- 团队把 Review 压力放到了最后一层实现代码，导致信息负担过重。

本规范的目标是建立一套 **AI Coding 的生产可控体系**：

- 让 AI 写代码前先读取架构与规范。
- 让 AI 的代码生成发生在被定义好的边界内。
- 让人类重点控制架构层、抽象层、接口契约和高风险实现点。
- 让 AI 负责放大实现层效率，而不是替代系统设计。
- 让每次 AI 变更都可追溯、可测试、可审计、可回滚。

### 0.2 适用范围

适用于以下场景：

- 个人使用 AI 辅助开发完整项目。
- 小团队使用 AI 自动化 Coding。
- 企业内部使用 Codex、Claude Code、Copilot、Cursor、Windsurf、Trae 等编码 Agent。
- 前后端分离项目。
- 移动端、Web、后端、SaaS、电商、AI 应用、内部工具等产品。
- 需要让 AI 基于项目规范生成代码、测试、文档、Review 意见的项目。

不局限于 React + Python。第二卷仅以 React + Python 前后端分离作为示例。

### 0.3 不适用范围

本规范不是：

- 某一个 AI 工具的完整使用手册。
- 替代代码审查、安全审计、合规审查的工具。
- 让 AI 完全自主上线代码的授权书。
- 法律、金融、医疗、隐私等高风险合规意见。

涉及支付、认证、授权、隐私、生产基础设施、数据迁移、财务、医疗、金融、法律、儿童数据、内容安全等高风险场景，必须额外做人工 Review 和专项评估。

### 0.4 目标读者

| 角色 | 关注重点 |
|---|---|
| 创始人 / 技术负责人 | 如何在 AI 加速开发时保持系统掌控感 |
| 架构师 | 系统边界、模块分层、接口契约、演进路线 |
| 前端工程师 | 组件、Hook、Service、状态、路由、请求、测试规范 |
| 后端工程师 | Router、Service、Repository、Model、事务、异常、API 规范 |
| QA / 测试 | AI 生成代码如何验收、如何自动化、哪些必须人工测 |
| 安全团队 | AI 生成代码的安全边界、依赖、Secrets、日志、权限 |
| 产品经理 | 需求如何变成可约束 AI 的规格说明 |
| DevOps / SRE | CI、灰度、回滚、监控、发布门禁 |
| AI Agent 使用者 | 如何写 AGENTS.md、CLAUDE.md、项目规则和任务模板 |

### 0.5 术语定义

| 术语 | 定义 |
|---|---|
| AI Coding | 使用 AI Agent 或 AI 辅助工具进行代码生成、修改、测试、重构和 Review |
| Agent | 能读取项目、编辑文件、运行命令、提交变更或辅助 Review 的 AI 编程执行体 |
| AGENTS.md | 项目级 Agent 指令入口文件，用于描述项目规范、工作流程、文档地图和约束 |
| CLAUDE.md | Claude Code 常用的项目记忆 / 指令文件，用于指导 Claude 在项目中的行为 |
| 架构层 | 定义系统边界、核心模块、外部依赖、数据流、部署和非功能约束的层级 |
| 模式与抽象层 | 定义代码组织方式、分层模式、组件模式、Service / Repository / Hook 等抽象的层级 |
| 实现层 | 函数、类、组件、页面、接口实现、测试代码等具体代码层级 |
| 接口契约 | API 请求、响应、错误码、鉴权、幂等、分页、版本兼容等约定 |
| Release Gate | 发布准入门槛，存在阻断项时不得合并、发布或全量上线 |
| Human Review Gate | 必须由人类审查的节点，尤其用于安全、支付、权限、隐私、数据迁移等高风险代码 |
| Progressive Loading | 让 Agent 按任务加载相关规范，而不是每次无差别读取全部文档 |

### 0.6 风险等级定义

| 等级 | 定义 | 处理要求 |
|---|---|---|
| Blocker | 会导致不能合并、不能发布、严重安全 / 隐私 / 支付 / 数据事故或系统不可理解 | 禁止合并或上线；已上线必须回滚、降级或关闭 |
| Critical | 严重影响可维护性、核心流程、质量、合规或后续扩展 | 必须修复后才能全量；可在严格灰度或隔离环境验证 |
| Major | 影响主要体验、代码质量或开发效率，但有临时方案 | 明确负责人和修复计划 |
| Minor | 不影响核心功能和架构稳定，主要是风格、文案或局部优化 | 可后续优化，但需记录 |

---

## 1. 核心问题：AI 写的代码为什么会失控

### 1.1 失控不是“代码跑不了”，而是“系统不可理解”

AI Coding 中后期最常见的问题不是代码完全不能运行，而是：

```md
- 功能看起来能用，但没人能说明为什么这么设计。
- 代码分散在很多地方，模块边界模糊。
- 相同逻辑被写了多个版本。
- API 调用到处都是，错误处理各写各的。
- 组件、Service、Model、Repository 的职责混在一起。
- 新需求来了，不知道该改哪里。
- 改一个功能会影响不相关模块。
- AI 总是自信地说“已完成”，但实际留下隐性风险。
```

因此，AI 写代码后的核心验收不是只看“功能是否跑通”，而要看：

```md
这个系统是否仍然可理解？
这个系统是否仍然可解释？
这个系统是否仍然可修改？
这个系统是否仍然可测试？
这个系统是否仍然可审计？
```

### 1.2 人类逐行 Review 不是唯一答案

如果 AI 一次性生成大量代码，人类逐行阅读会带来极高的信息负担。逐行 Review 适合高风险代码，但不适合作为所有 AI 代码的默认控制方式。

更有效的控制点是：

| 控制对象 | 为什么重要 | 是否必须人工控制 |
|---|---|---|
| 系统边界 | 决定 AI 能改哪里、不能改哪里 | 是 |
| 架构分层 | 决定代码未来如何长大 | 是 |
| 模块关系 | 决定需求变更时影响范围 | 是 |
| 接口契约 | 决定前后端、服务间、版本间是否稳定 | 是 |
| 抽象模式 | 决定 AI 生成代码是否一致 | 是 |
| 测试策略 | 决定功能是否可验证 | 是 |
| 高风险实现 | 支付、安全、权限、隐私、迁移等 | 是 |
| 普通实现细节 | 普通函数、页面、组件、样式 | 部分抽样 + 自动化 |

结论：

> 人不需要默认读完 AI 生成的每一行普通代码，但必须定义边界、抽象、契约、验收标准，并对高风险实现做人工 Review。

### 1.3 AI 加速编码后，人更容易绕过思考

AI 的危险之处不只是“可能写错”，更是“让编码变得太容易”。当开发者用一两句话让 AI 直接生成代码时，很容易跳过这些必要思考：

```md
- 这个需求属于哪个业务域？
- 要不要改现有架构？
- 这个模块的边界是什么？
- 前端和后端的契约是什么？
- 这个状态应该由谁维护？
- 这个数据是否涉及隐私？
- 这个接口是否需要幂等？
- 这个错误是否应该统一处理？
- 这个功能是否需要测试？
- 这个实现是否会影响旧版本？
```

AI 的速度不应该阻挡人的思考。正确顺序是：

```md
先想清楚业务、边界、架构、抽象、契约、验收。
再让 AI 在这些约束内编码。
```

---

## 2. AI Coding 三层控制模型

### 2.1 总览

AI Coding 的可控性应分为三层：

```mermaid
graph TB
  A[第一层：架构层] --> B[第二层：模式与抽象层]
  B --> C[第三层：实现层]
  A --> D[人类强控制]
  B --> D
  C --> E[AI 放大实现能力]
  C --> F[高风险人工 Review]
```

| 层级 | 控制内容 | 人类职责 | AI 职责 | 典型产物 |
|---|---|---|---|---|
| 第一层：架构层 | 系统边界、核心模块、数据流、外部依赖、非功能约束 | 定义、审查、冻结关键决策 | 解释、补全、生成图和文档草稿 | `01-architecture.md` |
| 第二层：模式与抽象层 | 分层模式、模块切分、接口契约、组件规则、错误处理、测试模式 | 定义团队规范，避免自由生长 | 按规范生成代码和建议 | `02-frontend-patterns.md`、`03-backend-patterns.md` |
| 第三层：实现层 | 函数、类、组件、页面、接口、测试代码 | 抽样 Review，高风险人工 Review | 主要实现、补测试、修复、重构 | 代码、测试、PR |

### 2.2 第一层：架构层

架构层回答：

```md
这个系统是什么？
边界在哪里？
核心模块有哪些？
模块之间怎么交互？
数据怎么流转？
哪些外部系统会接入？
哪些约束不能被破坏？
```

架构层要控制的是“系统骨架”。如果这一层没有定义，AI 会在实现层自由生长，导致后期无法理解。

### 2.3 第二层：模式与抽象层

模式与抽象层回答：

```md
前端组件怎么拆？
Hook 放哪里？
Service 放哪里？
状态怎么管理？
后端 Router / Service / Repository 怎么分工？
接口错误怎么返回？
异常怎么处理？
测试怎么写？
哪些命名和目录必须统一？
```

过去这些内容是“团队编码规范”。在 AI Coding 时代，它们也是 **Agent 的工作规范**。

### 2.4 第三层：实现层

实现层回答：

```md
具体函数怎么写？
组件怎么实现？
页面怎么渲染？
接口怎么调用？
单元测试怎么补？
异常分支怎么处理？
```

AI 最适合放大的就是这一层。前两层越清楚，第三层生成的代码越可控。

### 2.5 三层控制的核心原则

```md
第一层不清楚，不允许让 AI 大规模编码。
第二层不清楚，不允许让 AI 自由选择目录、抽象和模式。
第三层可以让 AI 高效生成，但必须受前两层约束。
高风险第三层代码必须人工 Review。
```

---

## 3. 人与 AI 的职责边界

### 3.1 人类应该控制什么

| 人类控制项 | 说明 | 原因 |
|---|---|---|
| 产品边界 | 做什么、不做什么、MVP 范围 | 防止 AI 扩展出不需要的功能 |
| 架构边界 | 系统模块、服务边界、外部依赖 | 防止自由生长 |
| 数据边界 | 数据所有权、隐私、缓存、持久化 | 防止数据泄露和串数据 |
| 接口契约 | 请求、响应、错误、鉴权、幂等、版本 | 防止前后端错位 |
| 抽象模式 | 目录、层级、职责、命名 | 防止重复和混乱 |
| 高风险代码 | 支付、权限、认证、迁移、安全、生产配置 | 防止 P0 事故 |
| Release Gate | 合并、发布、灰度、回滚标准 | 防止问题进入生产 |

### 3.2 AI 适合承担什么

| AI 适合项 | 说明 | 前提 |
|---|---|---|
| 生成普通实现代码 | 页面、组件、函数、Service、Repository | 已有规范和接口契约 |
| 生成测试代码 | 单测、集成测试、Mock、边界测试 | 测试策略明确 |
| 生成文档草稿 | README、API 文档、变更说明 | 架构和业务事实已确认 |
| 重构重复代码 | 抽函数、统一错误处理、整理目录 | 有模式规范 |
| 分析代码影响范围 | 查找调用链、识别变更风险 | 不替代人工判断 |
| 生成 Review Checklist | 基于规范检查 PR | 不能替代高风险人工 Review |
| 生成迁移计划草稿 | 数据库、接口、配置迁移 | 必须人工审查 |

### 3.3 AI 不应该独立决定什么

```md
- 是否改变系统架构。
- 是否新增核心模块。
- 是否变更 API 契约。
- 是否改变权限、认证、支付、风控逻辑。
- 是否新增第三方依赖或 SDK。
- 是否修改生产配置。
- 是否修改数据库 schema 或迁移逻辑。
- 是否删除历史兼容逻辑。
- 是否降低安全控制。
- 是否把调试、mock、测试入口放进生产。
```

这些操作必须进入 Human Review Gate。

---

## 4. AI Coding 失败模型与风险域

### 4.1 失败模型总览

| 风险域 | 典型表现 | 后果 | 阻断级别 |
|---|---|---|---|
| 架构漂移 | AI 新增目录、新增服务、新增抽象但无人确认 | 系统不可理解 | Critical |
| 模块边界混乱 | 前端组件直接调 API，后端 Router 写业务逻辑 | 难维护、难测试 | Critical |
| 接口契约漂移 | AI 改响应字段、状态码、错误结构 | 前后端不兼容 | Blocker / Critical |
| 隐式决策 | AI 自己选择技术方案但未记录 | 后续无法解释 | Major / Critical |
| 重复实现 | 相同工具函数、校验逻辑、错误处理多处重复 | 缺陷分散 | Major |
| 测试幻觉 | AI 声称已测试但没有真实跑测试 | 虚假完成 | Critical |
| 依赖膨胀 | 为小问题引入新库 | 供应链、包体积、漏洞风险 | Major / Critical |
| 安全漏洞 | Token 泄露、日志泄露、鉴权缺失、越权 | 数据事故 | Blocker |
| 数据迁移风险 | migration 不可回滚、旧数据不兼容 | 升级事故 | Blocker |
| 配置污染 | 测试环境、mock、debug 进入生产 | 生产事故 | Blocker |
| 过度工程化 | 简单需求被 AI 扩成复杂框架 | 维护成本上升 | Major |
| 局部正确全局错误 | 单功能能跑，但破坏全局模式 | 后续变更成本上升 | Critical |

### 4.2 最危险的不是错，而是“看似完成”

AI 常见输出是：

```md
我已经帮你完成了。
这不影响未来扩展。
这个实现是合理的。
```

但实际可能存在：

```md
- 没有跑测试。
- 没有覆盖异常分支。
- 没有说明改了哪些文件。
- 没有解释为什么这么设计。
- 没有检查旧接口兼容。
- 没有检查安全和隐私。
- 没有更新文档。
```

因此每次 AI 任务都必须要求输出：

```md
- 变更目标
- 变更文件
- 设计依据
- 影响范围
- 测试结果
- 未覆盖风险
- 需要人工确认的问题
```

---

## 5. 项目文档地图：AGENTS.md 作为 Agent 入口

### 5.1 为什么需要 AGENTS.md

AI Agent 不能只靠聊天上下文工作。项目需要一个固定入口，让 Agent 每次进入项目时知道：

```md
- 项目是什么。
- 哪些文档必须读。
- 当前任务应该读哪些专项规范。
- 哪些目录可以改。
- 哪些目录不能改。
- 代码应该按什么模式写。
- 做完后必须如何验证。
- 哪些情况必须停下来询问或人工 Review。
```

### 5.2 AGENTS.md 的定位

`AGENTS.md` 不应该塞满所有规范。它应该像地图：

```md
AGENTS.md = Agent 入口 + 文档索引 + 工作规则 + Release Gate 摘要
```

详细规范应拆到独立文档：

```md
/docs/ai-coding/
  00-project-context.md
  01-architecture.md
  02-api-contracts.md
  03-frontend-patterns.md
  04-backend-patterns.md
  05-data-model.md
  06-testing-strategy.md
  07-security-privacy.md
  08-review-release-gate.md
  09-task-templates.md
```

### 5.3 渐进式加载

不建议每次任务都让 AI 读取所有文档。更好的方式是：

```md
所有任务必须读：
- AGENTS.md
- 00-project-context.md
- 01-architecture.md 摘要
- 08-review-release-gate.md 摘要

前端任务额外读：
- 03-frontend-patterns.md
- 02-api-contracts.md，若涉及 API

后端任务额外读：
- 04-backend-patterns.md
- 05-data-model.md
- 02-api-contracts.md

安全 / 支付 / 权限任务额外读：
- 07-security-privacy.md
- 08-review-release-gate.md
```

### 5.4 CLAUDE.md / Copilot Instructions / Cursor Rules 映射

不同工具的项目指令文件不同，但逻辑相同：让工具先理解项目规则，再写代码。

| 工具 / 场景 | 推荐入口 | 说明 |
|---|---|---|
| Codex | `AGENTS.md` | Codex 官方支持项目级 AGENTS.md 指令入口 |
| Claude Code | `CLAUDE.md` | 可将 `CLAUDE.md` 写成项目记忆 / 规则，也可指向同一套规范 |
| GitHub Copilot | `.github/copilot-instructions.md`，以及 `.github/instructions/*.instructions.md` | 适合仓库级和路径级指令 |
| Cursor / Windsurf 等 | `.cursor/rules`、项目规则文件，按工具支持情况配置 | 建议引用同一套 `/docs/ai-coding` 规范 |
| 通用 Agent | `AGENTS.md` + `/docs/ai-coding` | 避免每个工具维护一份不同规范 |

可选做法：

```bash
# macOS / Linux 示例
ln -s AGENTS.md CLAUDE.md
```

注意：不同工具、不同操作系统和 Git 配置对符号链接支持不同。若团队环境复杂，可以让 `CLAUDE.md`、`.github/copilot-instructions.md` 保持简短，并在其中明确引用 `AGENTS.md` 和 `/docs/ai-coding`。

---

## 6. 第一层：架构层规范

### 6.1 架构层必须回答的问题

| 问题 | 必须写清楚什么 |
|---|---|
| 系统边界是什么 | 当前系统负责什么，不负责什么 |
| 核心模块是什么 | 用户、认证、订单、支付、内容、配置等模块 |
| 模块关系是什么 | 哪些模块可以调用哪些模块 |
| 数据流转是什么 | 数据从输入到存储、输出、同步如何流动 |
| 外部依赖是什么 | 支付、短信、邮件、对象存储、AI 模型、第三方 API |
| 非功能约束是什么 | 性能、安全、隐私、可靠性、可观测性、可扩展性 |
| 部署边界是什么 | 前端、后端、数据库、缓存、队列、CDN、对象存储 |
| 版本兼容是什么 | API 版本、旧客户端、数据库迁移、灰度策略 |

### 6.2 架构层文档模板

```md
# 01-architecture.md

## 1. 系统目标
- 本系统解决什么问题
- 当前版本范围
- 明确不做什么

## 2. 平台和技术栈
- 前端：React / TypeScript / Vite / ...
- 后端：Python / FastAPI / SQLAlchemy / ...
- 数据库：PostgreSQL / Redis / ...
- 部署：Docker / Kubernetes / ...

## 3. 系统边界
- 前端负责：页面、交互、输入校验、展示、客户端缓存
- 后端负责：业务规则、鉴权、数据持久化、支付校验、审计
- 第三方负责：支付、短信、邮件、对象存储、AI 模型等

## 4. 核心模块
| 模块 | 职责 | 主要输入 | 主要输出 | 不允许做什么 |
|---|---|---|---|---|

## 5. 数据流
- 用户操作 -> 前端校验 -> API -> Service -> Repository -> DB
- 异步任务 -> Queue -> Worker -> 状态更新 -> 通知

## 6. 外部依赖
| 依赖 | 用途 | 风险 | 降级方案 | 负责人 |
|---|---|---|---|---|

## 7. 非功能约束
- 性能
- 安全
- 隐私
- 可观测性
- 可回滚
- 可测试

## 8. 禁止破坏的架构规则
- 不允许前端直接绕过后端调用第三方支付确认结果
- 不允许 Router 写业务规则
- 不允许组件直接访问数据库或后端私有逻辑
- 不允许新增未登记的第三方依赖
```

### 6.3 架构层检查项

| 检查项 | 测试 / 验证方法 | 自动化可行性 | 阻断级别 | 通过标准 |
|---|---|---|---|---|
| 系统边界明确 | 阅读架构文档 + 需求对照 | 低 | Critical | 能说清系统负责和不负责什么 |
| 核心模块明确 | 架构图 + 模块表 | 中 | Critical | 每个模块有职责和禁止事项 |
| 外部依赖登记 | 依赖台账 + 配置检查 | 中 | Critical | 无未登记关键依赖 |
| 数据流清晰 | 画出核心流程数据流 | 低 | Critical | 核心流程可追踪 |
| 非功能约束明确 | 性能、安全、隐私、监控清单 | 中 | Major / Critical | 上线前有验收标准 |

---

## 7. 第二层：模式与抽象层规范

### 7.1 模式与抽象层的目标

这一层的目标是让 AI 在写代码时有稳定模式，而不是临时发挥。

必须回答：

```md
- 目录如何组织？
- 哪些文件放在哪？
- 前端组件怎么分？
- 后端 Router / Service / Repository 怎么分？
- 错误怎么处理？
- API 怎么请求？
- 状态怎么管理？
- 测试怎么写？
- 命名怎么统一？
```

### 7.2 抽象层不清楚时的典型事故

```md
- 页面里直接 fetch API。
- Hook 里写业务规则和持久化逻辑。
- Service 里拼 UI 文案。
- Router 里写数据库事务。
- Repository 返回业务 DTO。
- 错误处理到处 try/catch。
- 同一个 API 的响应类型重复定义。
- 多个组件各自实现 loading / error / empty 状态。
- 测试只测成功路径。
```

### 7.3 模式与抽象层模板

```md
# 03-frontend-patterns.md

## 1. 目录规范
## 2. 组件分层
## 3. Hook 规范
## 4. Service / API Client 规范
## 5. 状态管理规范
## 6. 表单和校验规范
## 7. 错误、Loading、Empty 状态规范
## 8. 路由和权限规范
## 9. 测试规范
## 10. 禁止事项
```

```md
# 04-backend-patterns.md

## 1. 目录规范
## 2. Router / Controller 规范
## 3. Service 规范
## 4. Repository 规范
## 5. Model / Schema / DTO 规范
## 6. 事务规范
## 7. 异常和错误码规范
## 8. 鉴权和权限规范
## 9. 日志与审计规范
## 10. 测试规范
## 11. 禁止事项
```

### 7.4 抽象层检查项

| 检查项 | 测试 / 验证方法 | 自动化可行性 | 阻断级别 | 通过标准 |
|---|---|---|---|---|
| 目录结构一致 | 静态扫描 + PR Review | 高 | Major / Critical | 新代码落在正确目录 |
| 分层职责清晰 | Review 关键文件 | 中 | Critical | 不跨层写逻辑 |
| 错误处理统一 | 测试错误分支 + 代码扫描 | 中 | Critical | API / UI 错误结构一致 |
| 测试模式明确 | 测试目录 + coverage + 用例审查 | 高 | Major / Critical | 关键分支有测试 |
| 禁止事项可检查 | lint、脚本、依赖扫描 | 高 | Critical | 禁止模式未出现 |

---

## 8. 第三层：实现层规范

### 8.1 实现层可以让 AI 放大效率

实现层包括：

```md
- 函数
- 类
- React 组件
- 页面
- Hook
- API Client
- Router
- Service
- Repository
- DTO
- 测试用例
- Mock 数据
- 文档片段
```

这些是 AI 最适合生成的内容，但必须遵守前两层约束。

### 8.2 实现层必须遵守的规则

```md
- 不得新增架构中不存在的核心模块，除非任务明确要求并通过架构 Review。
- 不得改变 API 契约，除非任务明确要求并更新 API 文档。
- 不得新增第三方依赖，除非说明原因、替代方案和风险。
- 不得在组件里直接写 API 细节。
- 不得在 Router 里写复杂业务逻辑。
- 不得绕过统一错误处理。
- 不得删除已有测试来让新代码通过。
- 不得把 mock、debug、测试入口放进生产路径。
- 不得硬编码 secret、token、API key、支付参数。
- 不得声称测试通过但没有提供命令和结果。
```

### 8.3 实现层什么时候必须人工 Review

以下场景不能只靠 AI Review：

| 场景 | 原因 | 阻断级别 |
|---|---|---|
| 支付金额、订单状态、回调验证 | 涉及资金和权益 | Blocker |
| 登录、认证、授权、权限 | 涉及账号安全和越权 | Blocker |
| 数据库 schema / migration | 涉及数据丢失和升级事故 | Blocker |
| Token、密钥、本地存储、日志 | 涉及敏感信息泄露 | Blocker |
| 用户隐私和数据采集 | 涉及合规风险 | Blocker / Critical |
| 生产配置、CI/CD、部署脚本 | 涉及生产事故 | Blocker |
| 删除兼容逻辑 | 可能影响旧版本用户 | Critical |
| 新增依赖 / SDK | 涉及供应链和隐私 | Critical |
| 风控规则 | 涉及黑灰产和误伤 | Critical |
| 法律、医疗、金融、儿童相关逻辑 | 高合规风险 | Blocker / Critical |

---

## 9. AI Coding 工作流

### 9.1 标准流程

```mermaid
graph LR
  A[需求输入] --> B[澄清边界]
  B --> C[检查架构影响]
  C --> D[检查模式与抽象]
  D --> E[生成任务计划]
  E --> F[人工确认高风险点]
  F --> G[AI 实现]
  G --> H[自动化测试]
  H --> I[AI 自检报告]
  I --> J[人工 Review]
  J --> K[合并 / 灰度 / 发布]
```

### 9.2 不允许直接进入编码的情况

当出现以下任一情况时，AI 必须先产出方案，而不是直接改代码：

```md
- 需求边界不清楚。
- 需要新增模块。
- 需要改 API 契约。
- 需要改数据库结构。
- 涉及支付、权限、认证、安全、隐私。
- 涉及删除旧逻辑。
- 涉及大范围重构。
- 需要新增依赖。
- 涉及生产配置。
- 现有文档与代码不一致。
```

### 9.3 AI 任务计划必须包含

```md
## Task Plan

1. 任务目标
2. 需求边界
3. 涉及模块
4. 需要读取的规范文档
5. 计划修改文件
6. 是否影响 API 契约
7. 是否影响数据库 / 缓存 / 配置
8. 是否影响权限 / 安全 / 隐私
9. 测试计划
10. 需要人工确认的问题
```

### 9.4 AI 完成后必须输出

```md
## Change Report

1. 本次完成了什么
2. 修改了哪些文件
3. 每个文件为什么修改
4. 是否遵守架构与模式规范
5. 是否改动 API 契约
6. 是否新增依赖
7. 是否涉及安全 / 隐私 / 支付 / 权限
8. 已运行的测试命令和结果
9. 未覆盖风险
10. 建议人工 Review 的点
```

---

## 10. AI 任务拆分与变更边界

### 10.1 任务必须小而明确

不建议给 AI 这样的任务：

```md
帮我把整个商城做完。
帮我重构一下项目。
帮我优化代码。
帮我把后端补完整。
```

应拆成：

```md
- 基于现有 API 契约，实现商品列表页面，不改 API。
- 为订单创建接口补充幂等校验，不改数据库结构。
- 将用户资料页面的 API 调用从组件迁移到 userService，保持 UI 不变。
- 为 authService 增加 token refresh 失败用例。
```

### 10.2 任务粒度标准

| 任务规模 | 适合 AI 直接实现吗 | 要求 |
|---|---|---|
| 单函数 / 单组件 | 可以 | 有明确输入输出 |
| 单页面 | 可以 | UI 状态、API、错误、测试明确 |
| 单接口 | 可以 | API 契约和业务规则明确 |
| 单模块 | 谨慎 | 先设计模块边界 |
| 跨模块功能 | 不建议直接实现 | 先出架构 / 任务拆分 |
| 大型重构 | 不允许直接实现 | 必须分阶段、可回滚 |
| 支付 / 鉴权 / 迁移 | 不允许自动完成后直接合并 | 必须人工 Review |

### 10.3 AI 变更边界声明

每个任务应声明：

```md
允许修改：
- src/features/product/**
- src/services/productService.ts
- tests/product/**

禁止修改：
- src/auth/**
- src/payment/**
- database/migrations/**
- deployment/**
```

---

## 11. 代码评审策略：不逐行盯死，但要盯住风险

### 11.1 Review 的核心变化

AI Coding 时代，Review 不应只问：

```md
这几行代码写得对不对？
```

还要问：

```md
这个变更是否破坏架构？
这个抽象是否和项目一致？
这个接口契约是否稳定？
这个变更是否可测试？
这个功能出了问题能否回滚？
这个代码是否引入安全、隐私、依赖风险？
```

### 11.2 Review 分层

| Review 层级 | 关注点 | 负责人 | 是否必须 |
|---|---|---|---|
| 架构 Review | 系统边界、模块关系、数据流 | Tech Lead / 架构师 | 大变更必须 |
| 抽象 Review | 分层、目录、命名、职责 | 模块 Owner | 必须 |
| 契约 Review | API、错误码、字段、版本兼容 | 前后端 Owner | 涉及接口必须 |
| 测试 Review | 单测、集成、边界、异常 | QA / Owner | 必须 |
| 安全 Review | 鉴权、隐私、日志、依赖、Secrets | 安全 / Senior | 高风险必须 |
| 实现 Review | 具体代码、可读性、性能 | 代码 Owner | 普通变更抽样，高风险全量 |

### 11.3 不必逐行读的代码

以下代码在规范充分、测试覆盖充分时，可以用自动化 + 抽样 Review：

```md
- 普通 UI 样式调整
- 简单展示组件
- 已有模式下的 CRUD 页面
- 已有 Service 模板下的普通 API 调用
- 普通表单校验
- 普通单元测试补充
```

### 11.4 必须重点读的代码

```md
- 影响鉴权、权限、Session、Token 的代码
- 影响支付、订单、退款、权益的代码
- 影响数据迁移、删除、清理的代码
- 影响外部回调、Webhook、签名验证的代码
- 影响日志、监控、审计的代码
- 影响生产配置、CI/CD、部署的代码
- 修改公共工具、公共中间件、全局状态的代码
- 删除旧兼容逻辑的代码
```

---

## 12. 测试、CI 与质量门禁

### 12.1 AI 生成代码必须可验证

AI 不能只说“已完成”。必须提供验证证据：

```md
- 运行了哪些测试命令
- 测试是否通过
- 哪些测试未运行，为什么
- 手动验证了哪些页面 / 接口
- 未覆盖哪些风险
```

### 12.2 CI 最低门禁

| 门禁 | 说明 | 阻断级别 |
|---|---|---|
| Lint | 代码风格和基础错误 | Major / Critical |
| Type Check | TypeScript / Python typing | Critical |
| Unit Test | 单元测试 | Critical |
| Integration Test | API / Service / DB 集成 | Critical |
| E2E Smoke | 核心流程冒烟 | Critical |
| Dependency Scan | 依赖漏洞和许可证 | Critical |
| Secret Scan | 密钥泄露扫描 | Blocker |
| Build | 生产构建可通过 | Blocker |
| Contract Test | API 契约测试 | Critical |

### 12.3 AI 不得规避测试

禁止：

```md
- 删除失败测试。
- 降低断言强度。
- 把失败测试标记 skip，除非有审批。
- 用 mock 掩盖真实集成问题。
- 只跑局部测试却声称全量通过。
- 不提供测试命令和结果。
```

### 12.4 测试策略矩阵

| 场景 | 必测内容 | 自动化可行性 | 人工要求 |
|---|---|---|---|
| 普通 UI | 展示、交互、错误态 | 高 | 抽样 |
| API | 成功、失败、鉴权、边界 | 高 | 契约 Review |
| 支付 | 取消、超时、回调、重复支付、对账 | 中 | 必须人工 |
| 权限 | 拒绝、永久拒绝、降级 | 中 | 关键路径人工 |
| 数据迁移 | 老数据、新数据、中断、回滚 | 中 | 必须人工 |
| 安全 | 越权、注入、日志、Secrets | 中 | 必须人工 |

---

## 13. 安全、隐私、依赖与供应链

### 13.1 AI 生成代码的安全基线

```md
- 不得硬编码 secret、token、API key、数据库密码。
- 不得在日志中打印 token、手机号、邮箱、地址、身份证、支付信息。
- 不得把敏感错误直接返回给前端。
- 不得绕过鉴权和权限校验。
- 不得信任客户端金额、用户 ID、角色、权限、订单状态。
- 不得忽略 TLS / HTTPS 错误。
- 不得引入未登记依赖。
- 不得把用户输入直接拼接到 SQL、命令、模板、URL。
- 不得让 WebView / JSBridge / Deep Link 直接触发敏感操作。
```

### 13.2 依赖治理

AI 很容易为了快速完成任务引入依赖。必须约束：

```md
新增依赖必须说明：
- 为什么需要
- 是否有内置替代方案
- 是否有更轻量替代
- 是否有安全漏洞
- 是否影响包体积
- 是否影响启动性能
- 是否有许可证风险
- 谁负责后续升级
```

### 13.3 AI / LLM 特有风险

如果项目本身使用 LLM 或 AI Agent，还必须检查：

```md
- Prompt Injection
- 不安全输出处理
- 训练 / 检索数据污染
- 模型拒绝服务和成本滥用
- 供应链风险
- 敏感信息泄露
- 工具调用越权
- 过度自治
- 错误信息导致用户误导
```

### 13.4 高风险安全任务必须人工 Review

AI 可以协助生成安全代码，但不能独立批准：

```md
- 鉴权中间件
- 权限模型
- 支付签名验证
- Webhook 验证
- 数据加密
- Secrets 管理
- 数据删除
- 审计日志
- 风控规则
```

---

## 14. 文档、证据留存与可追溯性

### 14.1 每次 AI 变更必须留下证据

```md
- 任务描述
- 任务计划
- 变更文件清单
- 关键设计决策
- 测试命令和结果
- 未覆盖风险
- 人工 Review 记录
- 是否更新文档
```

### 14.2 架构决策记录 ADR

对于重要决策，必须写 ADR：

```md
/docs/adr/0001-use-fastapi-service-repository-pattern.md
```

模板：

```md
# ADR-0001：决策标题

## 背景
为什么需要这个决策？

## 决策
我们决定采用什么方案？

## 替代方案
考虑过哪些方案？为什么不用？

## 影响
对架构、测试、性能、安全、团队有什么影响？

## 回滚或调整方式
如果未来不合适，怎么调整？
```

### 14.3 AI 生成代码的可追溯字段

PR 或任务记录中建议包含：

```md
- AI 工具：Codex / Claude Code / Copilot / Cursor / 其他
- 模型，若团队需要记录
- 使用的规范文件
- 任务 Prompt 摘要
- 是否由 AI 生成主要代码
- 人工 Review 人
- 合并人
```

---

## 15. 团队治理、角色分工与持续改进

### 15.1 角色分工

| 角色 | 职责 |
|---|---|
| Tech Lead | 维护架构层规范，批准架构变更 |
| Module Owner | 维护模块边界和模式规范，Review 模块变更 |
| AI Operator | 操作 AI Agent，提交任务计划和变更报告 |
| Reviewer | Review 代码、架构、测试和风险 |
| QA | 维护测试矩阵和自动化策略 |
| Security | 维护安全基线和高风险 Review 清单 |
| DevOps | 维护 CI、构建、发布、回滚和监控 |
| Product | 明确需求边界和不做范围 |

### 15.2 规范不是一次性写完

AGENTS.md 和规范文档应该持续迭代：

```md
当 AI 第二次犯同样错误时，把规则写入规范。
当 Code Review 发现 AI 应该知道的项目知识时，把规则写入规范。
当团队反复在聊天里解释同一件事时，把规则写入规范。
当新人需要同样上下文才能上手时，把规则写入规范。
```

### 15.3 规范更新流程

```md
发现问题 -> 归因到架构 / 抽象 / 实现 / 工具 / 测试 -> 更新对应规范 -> 加入自动化检查 -> 复盘是否降低重复错误
```

---

## 16. 通用 Release Gate

### 16.1 Blocker：存在一个就不能合并 / 发布

```md
- AI 未读项目规范即进行大范围修改。
- 未经确认改变系统架构或核心模块边界。
- 未经确认改变 API 契约。
- 未经确认修改数据库 schema / migration。
- 支付金额、权限、用户身份、订单状态依赖客户端可信输入。
- 用户 A 可以访问用户 B 数据。
- Token、secret、API key 明文存储或泄露。
- 测试环境、mock、debug 入口进入生产路径。
- AI 删除测试或降低断言来让代码通过。
- 生产构建失败。
- 关键流程没有可回滚 / 可关闭方案。
- 高风险代码没有人工 Review。
```

### 16.2 Critical：必须修复后才能全量

```md
- 架构文档与代码明显不一致。
- 模块职责混乱，存在跨层调用。
- API 错误结构不统一。
- 旧版本兼容失败。
- 依赖未登记或存在高危漏洞。
- 核心流程测试缺失。
- AI 变更没有说明测试命令和结果。
- 日志可能泄露敏感信息。
- 权限拒绝或异常分支无降级。
- 监控、告警、日志缺失导致无法定位问题。
```

### 16.3 Major / Minor

```md
Major：
- 部分组件命名不一致。
- 普通页面缺少某些边界状态。
- 部分测试覆盖不足但不影响核心路径。
- 文档更新不完整但关键事实清楚。

Minor：
- 文案、样式、注释、格式等低风险问题。
```

---

# 第二卷：React + Python 前后端分离项目示例

## 17. 示例项目边界

本示例假设：

```md
前端：React + TypeScript + Vite
后端：Python + FastAPI
数据库：PostgreSQL
缓存：Redis，可选
认证：JWT / Session，按项目选择
API：REST JSON
部署：Docker / CI/CD
```

目标不是规定所有项目必须这样选型，而是演示如何把“三层控制模型”落到具体技术栈。

---

## 18. 推荐仓库结构

```md
project-root/
  AGENTS.md
  CLAUDE.md                       # 可选：指向 AGENTS.md 或引用同一套规范
  .github/
    copilot-instructions.md        # 可选：引用 AGENTS.md
    workflows/
      ci.yml
    pull_request_template.md

  docs/
    ai-coding/
      00-project-context.md
      01-architecture.md
      02-api-contracts.md
      03-frontend-patterns.md
      04-backend-patterns.md
      05-data-model.md
      06-testing-strategy.md
      07-security-privacy.md
      08-review-release-gate.md
      09-task-templates.md
    adr/
      0001-example.md

  frontend/
    src/
      app/
      routes/
      features/
      components/
      hooks/
      services/
      types/
      lib/
      test/

  backend/
    app/
      main.py
      api/
        routers/
      core/
      services/
      repositories/
      models/
      schemas/
      db/
      workers/
      tests/

  scripts/
  deployment/
```

---

## 19. AGENTS.md 最小可用模板

```md
# AGENTS.md

本文件是本仓库所有 AI Coding Agent 的入口说明。任何编码任务开始前必须先阅读本文件。

## 1. 项目概览
- 项目名称：待填写
- 项目类型：React + Python 前后端分离
- 当前阶段：MVP / Beta / Production，待填写
- 核心业务：待填写

## 2. 必读文档
所有任务必须读取：
- docs/ai-coding/00-project-context.md
- docs/ai-coding/01-architecture.md
- docs/ai-coding/08-review-release-gate.md

前端任务额外读取：
- docs/ai-coding/03-frontend-patterns.md
- docs/ai-coding/02-api-contracts.md，若涉及 API

后端任务额外读取：
- docs/ai-coding/04-backend-patterns.md
- docs/ai-coding/05-data-model.md
- docs/ai-coding/02-api-contracts.md

安全、支付、认证、权限、隐私、生产配置任务额外读取：
- docs/ai-coding/07-security-privacy.md

## 3. 工作规则
- 不允许在没有计划的情况下进行跨模块修改。
- 不允许未经确认改变 API 契约。
- 不允许未经确认新增第三方依赖。
- 不允许未经确认修改数据库 migration。
- 不允许硬编码 secret、token、API key、支付参数。
- 不允许删除测试或降低断言来让代码通过。
- 修改完成必须输出变更报告和测试结果。

## 4. 任务计划要求
开始编码前必须说明：
- 任务目标
- 涉及模块
- 计划修改文件
- 是否影响 API / DB / 权限 / 安全 / 隐私
- 测试计划
- 需要人工确认的问题

## 5. 完成报告要求
完成后必须说明：
- 修改了哪些文件
- 为什么这样改
- 跑了哪些测试命令
- 测试结果
- 未覆盖风险
- 建议人工 Review 点

## 6. 高风险人工 Review
以下变更必须人工 Review：
- 支付
- 认证 / 授权
- 用户权限
- 数据库 migration
- 生产配置
- Secrets
- 第三方依赖
- 用户隐私数据
- 删除旧兼容逻辑
```

---

## 20. 架构规范模板

```md
# docs/ai-coding/01-architecture.md

## 1. 系统边界

前端负责：
- 页面渲染
- 用户交互
- 表单初步校验
- 客户端状态
- API 调用封装
- 错误 / Loading / Empty 展示

后端负责：
- 业务规则
- 鉴权和权限
- 数据持久化
- 事务
- 幂等
- 审计日志
- 支付 / 外部回调验证
- 服务端可信判断

前端不得负责：
- 判断支付是否成功
- 判断用户是否有服务端权限
- 生成可信金额
- 直接写入数据库

后端不得负责：
- 具体 UI 展示
- 页面状态样式

## 2. 核心模块
| 模块 | 职责 | 依赖 | 禁止事项 |
|---|---|---|---|
| auth | 登录、会话、权限 | user | 不允许返回敏感 token 到日志 |
| user | 用户资料 | auth | 不允许跨账号访问 |
| product，若有 | 商品展示 | inventory | 不允许直接处理支付 |
| order，若有 | 订单创建、状态 | payment / inventory | 不允许信任客户端金额 |
| payment，若有 | 支付创建、回调、对账 | order | 不允许客户端确认支付成功 |

## 3. 数据流
用户操作 -> React 页面 -> Service -> API -> Router -> Service -> Repository -> DB

## 4. 外部依赖
| 依赖 | 用途 | 降级方案 | Owner |
|---|---|---|---|

## 5. 架构禁止事项
- 不允许跨层调用。
- 不允许前端绕过后端调用需要服务端可信判断的第三方。
- 不允许新增未登记依赖。
- 不允许将业务规则分散到多个层。
```

---

## 21. API 契约规范模板

### 21.1 API 基本规则

```md
- API 使用 REST JSON。
- 所有 API 必须有 OpenAPI / Schema 定义。
- 所有错误必须使用统一错误结构。
- 创建 / 支付 / 提交类操作必须考虑幂等。
- 客户端不能作为可信来源。
- API 版本变更必须记录兼容策略。
```

### 21.2 统一响应结构示例

```json
{
  "data": {},
  "error": null,
  "requestId": "req_123"
}
```

错误示例：

```json
{
  "data": null,
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "订单不存在",
    "details": {}
  },
  "requestId": "req_123"
}
```

### 21.3 API 契约检查项

| 检查项 | 要求 | 阻断级别 |
|---|---|---|
| 请求参数 | Schema 明确，必填 / 可选清楚 | Critical |
| 响应字段 | 字段类型、空值、默认值明确 | Critical |
| 错误码 | 统一 code，不直接暴露内部异常 | Critical |
| 鉴权 | 每个接口声明是否需要登录和权限 | Blocker |
| 幂等 | 创建、支付、退款、提交类操作必须有策略 | Blocker / Critical |
| 版本兼容 | 字段废弃和新增有过渡期 | Critical |

---

## 22. React 前端模式与抽象规范

### 22.1 前端目录示例

```md
frontend/src/
  app/                 # 应用初始化、Provider、全局配置
  routes/              # 路由定义
  features/            # 业务功能域
    user/
      pages/
      components/
      hooks/
      services/
      types.ts
      tests/
  components/          # 跨业务通用组件
  hooks/               # 跨业务通用 hooks
  services/            # API client 和通用服务
  types/               # 全局类型
  lib/                 # 工具函数
```

### 22.2 组件分层

| 层级 | 职责 | 禁止事项 |
|---|---|---|
| Page | 路由级页面，组合业务组件 | 不直接写复杂 API 细节 |
| Feature Component | 业务组件，展示业务状态 | 不直接访问全局底层配置 |
| Shared Component | 通用 UI | 不包含业务规则 |
| Hook | 复用状态和行为 | 不直接承担服务端可信判断 |
| Service | 封装 API 调用 | 不处理 UI 展示 |

### 22.3 React 禁止事项

```md
- 不允许在组件中散落 fetch / axios 调用。
- 不允许在组件中拼接 API URL。
- 不允许在 UI 层判断服务端权限。
- 不允许将 token 打印到 console。
- 不允许每个页面各自实现错误结构。
- 不允许为了简单状态引入不必要全局状态。
- 不允许把业务规则写进通用组件。
```

### 22.4 状态、错误与 Loading

```md
每个远程数据页面必须有：
- loading
- success
- empty
- error
- retry
- permission denied，若涉及权限
```

### 22.5 前端测试要求

| 类型 | 内容 |
|---|---|
| 单元测试 | 工具函数、Hook、格式化、校验 |
| 组件测试 | 状态渲染、用户交互、错误态 |
| 集成测试 | 页面 + API mock + 路由 |
| E2E | 登录、核心业务流程、异常流程 |

---

## 23. Python 后端模式与抽象规范

### 23.1 后端目录示例

```md
backend/app/
  main.py
  api/
    routers/
      user_router.py
      order_router.py
  services/
    user_service.py
    order_service.py
  repositories/
    user_repository.py
    order_repository.py
  models/
    user.py
    order.py
  schemas/
    user_schema.py
    order_schema.py
  core/
    config.py
    security.py
    errors.py
    logging.py
  db/
    session.py
    migrations/
  tests/
```

### 23.2 分层职责

| 层 | 职责 | 禁止事项 |
|---|---|---|
| Router | 接收请求、参数校验、调用 Service、返回响应 | 不写复杂业务逻辑，不直接访问 DB |
| Service | 业务规则、事务、权限判断、调用 Repository | 不拼 UI 文案，不依赖具体 HTTP 实现 |
| Repository | 数据读写、查询封装 | 不写业务决策 |
| Model | 数据库实体 | 不写复杂业务流程 |
| Schema / DTO | 请求响应结构 | 不包含持久化逻辑 |
| Core | 配置、安全、错误、日志 | 不写具体业务 |

### 23.3 后端禁止事项

```md
- 不允许 Router 直接写数据库查询。
- 不允许 Service 返回未脱敏的敏感字段。
- 不允许 Repository 判断业务权限。
- 不允许信任客户端 user_id、role、price、order_status。
- 不允许在日志中打印 token、password、secret。
- 不允许直接吞掉异常而不记录 requestId。
- 不允许没有事务地执行多步骤关键写操作。
```

### 23.4 事务和幂等

```md
- 创建订单、支付、退款、发货、权益发放必须考虑幂等。
- 外部回调必须验证签名和重复回调。
- 多表写入必须使用事务。
- 失败后必须能重试或回滚。
```

### 23.5 后端测试要求

| 类型 | 内容 |
|---|---|
| Unit | Service 业务规则、Repository 查询逻辑 |
| Integration | Router + Service + DB |
| Contract | 请求响应 Schema、错误码 |
| Security | 鉴权、越权、输入校验、敏感日志 |
| Migration | 数据库迁移、回滚、中断恢复 |

---

## 24. 数据模型、状态与错误处理规范

### 24.1 数据所有权

```md
每个核心实体必须定义 Owner：
- User 由 user-service 管理。
- Order 由 order-service 管理。
- Payment 由 payment-service 管理。
- Product 由 product-service 管理。
```

不得多个模块同时维护同一份核心状态。

### 24.2 错误码规范

```md
错误码命名：DOMAIN_ACTION_REASON
示例：
- AUTH_TOKEN_EXPIRED
- USER_NOT_FOUND
- ORDER_ALREADY_PAID
- PAYMENT_SIGNATURE_INVALID
```

### 24.3 错误处理要求

```md
- 前端展示用户可理解文案。
- 后端记录可诊断日志。
- 外部错误不得原样暴露给用户。
- 每个错误必须关联 requestId。
- 支付、安全、隐私错误必须进入审计日志。
```

---

## 25. 测试策略模板

```md
# docs/ai-coding/06-testing-strategy.md

## 1. 测试目标
- 保证核心流程正确。
- 保证架构和接口契约不被 AI 破坏。
- 保证异常、弱网、安全、权限分支可验证。

## 2. 测试分层
| 层级 | 工具 | 覆盖内容 |
|---|---|---|
| Unit | pytest / vitest | 函数、Service、Hook |
| Integration | pytest + test DB / MSW | API、DB、Service |
| E2E | Playwright / Cypress | 核心流程 |
| Contract | OpenAPI / schema test | API 契约 |
| Security | secret scan / dependency scan | 安全和依赖 |

## 3. AI 任务最低测试要求
- 普通 UI：组件测试或 E2E smoke。
- API 变更：Contract + Integration。
- 业务规则：Service unit test。
- 支付 / 权限：单测 + 集成 + 人工 Review。
- 数据迁移：迁移测试 + 回滚策略。
```

---

## 26. 高风险人工 Review 清单

```md
## 必须人工 Review

### 支付
- 金额是否服务端计算
- 商品 ID / 订单 ID 是否服务端校验
- 回调签名是否验证
- 重复回调是否幂等
- 退款和权益回收是否一致

### 认证与权限
- Token 是否安全存储
- 过期和刷新是否正确
- 是否存在越权访问
- 角色和权限是否服务端判断

### 数据库迁移
- 老数据是否兼容
- migration 是否可重复执行
- 失败是否可回滚
- 中断后是否可恢复

### 安全与隐私
- 日志是否脱敏
- 是否硬编码 secret
- 是否新增数据采集
- 隐私政策是否需要更新

### 生产配置
- 是否连接生产环境
- 是否关闭 debug / mock
- 是否上传 source map / mapping / 日志配置正确
```

---

## 27. React + Python Release Gate

### 27.1 Blocker

```md
- 生产构建失败。
- TypeScript typecheck 失败。
- Python 测试失败。
- API 契约变更未更新文档。
- Router 直接访问数据库并写业务逻辑。
- React 组件直接信任客户端金额 / 权限。
- 支付 / 权限 / migration 未人工 Review。
- Secret 泄露。
- 新增依赖未登记。
- 测试环境配置进入生产构建。
```

### 27.2 Critical

```md
- 前端状态缺少 error / loading / empty 处理。
- 后端错误结构不统一。
- 旧接口兼容失败。
- 关键 Service 无单元测试。
- 核心流程无 E2E smoke。
- 日志缺少 requestId。
- 监控无法定位核心错误。
```

---

# 第三卷：模板、映射关系与落地清单

## 28. 三层控制模型映射表

| 能力 / 风险项 | 架构层 | 模式与抽象层 | 实现层 | 是否 MVP 必须 | 说明 |
|---|---|---|---|---|---|
| 系统边界 | 是 | 否 | 否 | 是 | 没有边界不应让 AI 大规模编码 |
| 核心模块 | 是 | 是 | 否 | 是 | 先定义模块，再生成实现 |
| API 契约 | 是 | 是 | 是 | 是 | 前后端分离项目 P0 |
| 前端组件规范 | 否 | 是 | 是 | 是 | 控制 AI 生成 UI 的结构 |
| 后端分层规范 | 否 | 是 | 是 | 是 | 避免 Router / Service / Repository 混乱 |
| 普通页面实现 | 否 | 否 | 是 | 视业务 | AI 可主要承担 |
| 支付逻辑 | 是 | 是 | 是 | 视业务 | 高风险，必须人工 Review |
| 权限逻辑 | 是 | 是 | 是 | 是 | 高风险，必须人工 Review |
| 数据迁移 | 是 | 是 | 是 | 视业务 | 必须可回滚 |
| 测试策略 | 是 | 是 | 是 | 是 | 没有测试，AI 完成不可验证 |
| 文档地图 | 是 | 是 | 否 | 是 | AGENTS.md 是入口 |
| Release Gate | 是 | 是 | 是 | 是 | 防止不可控代码合并 |

---

## 29. 不同项目阶段的最低文档集

### 29.1 个人 Demo

```md
必须：
- AGENTS.md
- 00-project-context.md
- 01-architecture.md 简版
- 03/04 patterns 简版
- 06-testing-strategy.md 简版
```

### 29.2 MVP 项目

```md
必须：
- AGENTS.md
- 00-project-context.md
- 01-architecture.md
- 02-api-contracts.md
- 03-frontend-patterns.md
- 04-backend-patterns.md
- 06-testing-strategy.md
- 08-review-release-gate.md
```

### 29.3 生产项目

```md
必须：
- MVP 全部文档
- 05-data-model.md
- 07-security-privacy.md
- ADR
- Dependency Inventory
- Build Manifest
- Runbook
- Release Gate 证据留存
```

### 29.4 高风险项目

涉及支付、金融、医疗、儿童、隐私、AI Agent 工具调用、生产自动化时，必须额外增加：

```md
- Threat Model
- Security Review Checklist
- Privacy Impact Assessment
- Data Retention Policy
- Incident Runbook
- Human Review Gate
- Red Team / Abuse Case 清单
```

---

## 30. 不同 AI 工具的指令文件映射

| 工具 | 仓库级入口 | 路径级 / 任务级规则 | 建议做法 |
|---|---|---|---|
| Codex | `AGENTS.md` | 可引用子文档、计划文件 | 主文件简洁，分文档加载 |
| Claude Code | `CLAUDE.md` | 子代理、技能、项目记忆 | `CLAUDE.md` 引用 `AGENTS.md` 或同源规范 |
| GitHub Copilot | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | 仓库级 + 路径级结合 |
| Cursor | `.cursor/rules` | 规则文件 | 引用同一套 docs |
| 通用 IDE Agent | README / AGENTS.md | 任务 Prompt | 不要每个工具写一套不同事实 |

---

## 31. AI Coding Prompt 模板

### 31.1 开发任务模板

```md
你是本项目的资深工程师。开始前必须先阅读 AGENTS.md，并根据任务类型读取相关 docs/ai-coding 文档。

任务：
- [写清楚要做什么]

范围：
- 允许修改：[目录 / 文件]
- 禁止修改：[目录 / 文件]

约束：
- 不允许改变 API 契约，除非先提出方案。
- 不允许新增依赖，除非说明原因并等待确认。
- 不允许修改数据库 migration。
- 必须遵守前端 / 后端分层规范。

输出要求：
1. 先给 Task Plan，不要立即改代码。
2. 标明是否涉及架构、API、DB、安全、隐私、支付、权限。
3. 经确认后再实现。
4. 实现后输出 Change Report、测试命令和结果。
```

### 31.2 代码审查模板

```md
请基于 AGENTS.md 和 docs/ai-coding 规范审查本次 diff。

重点检查：
- 是否破坏架构层边界
- 是否破坏前后端分层
- 是否改变 API 契约
- 是否涉及安全 / 隐私 / 支付 / 权限
- 是否新增依赖
- 是否有测试覆盖
- 是否有高风险点需要人工 Review

输出：
- Blocker
- Critical
- Major
- Minor
- 建议修改
- 必须人工确认项
```

### 31.3 重构任务模板

```md
请不要直接大范围重构。先输出重构计划：

1. 当前问题是什么
2. 涉及哪些模块
3. 哪些行为必须保持不变
4. 分几步改
5. 每步如何测试
6. 如何回滚
7. 哪些文件不能改
8. 是否影响 API / DB / 权限 / 安全
```

---

## 32. PR / Review 模板

```md
## 1. 变更目标

## 2. 变更范围
- 修改文件：
- 未修改但相关文件：

## 3. 是否由 AI 生成主要代码
- 是 / 否
- 使用工具：
- 使用的规范文件：

## 4. 架构影响
- 是否改变模块边界：是 / 否
- 是否改变 API 契约：是 / 否
- 是否改变 DB / migration：是 / 否

## 5. 风险检查
- 支付：是 / 否
- 权限：是 / 否
- 认证：是 / 否
- 隐私：是 / 否
- 安全：是 / 否
- 生产配置：是 / 否
- 新增依赖：是 / 否

## 6. 测试结果
- 命令：
- 结果：

## 7. 未覆盖风险

## 8. 人工 Review 点
```

---

## 33. 常见失控场景与处置方案

| 场景 | 表现 | 处置 |
|---|---|---|
| AI 写了一堆没人认识的代码 | 目录、函数、模块突然变多 | 暂停合并，要求 AI 生成架构差异报告 |
| AI 自己改了 API | 前端和后端字段对不上 | 回滚契约变更，先更新 `02-api-contracts.md` |
| AI 新增多个依赖 | package / requirements 膨胀 | 做依赖审查，不必要依赖移除 |
| AI 把业务写进 UI | 组件里出现权限 / 金额 / 订单状态判断 | 下沉到 Service / 后端 |
| AI 绕过测试 | 删除测试、skip 测试 | Blocker，恢复测试并复盘 |
| AI 过度重构 | 小任务改了大范围文件 | 拆分 PR，限定修改范围 |
| AI 重复造轮子 | 多个工具函数重复 | 抽象统一工具，更新规范 |
| AI 忽略高风险 | 支付 / 鉴权代码无人工 Review | 禁止合并 |

---

## 34. 与移动端生产可上线规范的衔接

前一份《移动端 App 全平台生产可上线规范》强调：上线不是只测功能，而要覆盖平台差异、设备矩阵、权限、支付、隐私、安全、发布、监控、长期维护。AI Coding 规范与它的关系是：

| 移动端生产规范中的能力 | AI Coding 中应如何前置 |
|---|---|
| iOS / Android 平台差异 | 写入架构层与平台专项规范，禁止 AI 自由处理 |
| 支付合规 | 写入高风险人工 Review Gate |
| 权限与隐私 | 写入安全隐私规范和 Release Gate |
| 设备适配 | 写入前端 / 移动端 UI 模式规范 |
| 构建产物审计 | 写入 CI / Build Manifest |
| SDK 供应链 | 写入依赖治理和 SDK Inventory |
| 可观测性 / Runbook | 写入生产发布 Gate |
| 宠物商城行业专项 | 写入行业业务边界和商品 / 订单 / 售后模型 |

结论：

```md
移动端生产可上线规范 = 产品能不能上线的生产标准。
AI Coding 可控规范 = AI 写代码时如何不破坏这些生产标准。
```

---

## 35. 补充风险

### 35.1 Context 漂移

AI 多轮对话后可能逐渐偏离原始架构和规范。应对方式：

```md
- 关键任务使用 AGENTS.md + 任务文档重新锚定。
- 长任务拆成多个小 PR。
- 每个阶段输出变更报告。
- 避免在同一对话里连续做多个无关大任务。
```

### 35.2 规范过大导致 Agent 忽略重点

应对方式：

```md
- AGENTS.md 保持简洁。
- 详细规范拆到 docs。
- 使用渐进式加载。
- 每个任务只加载相关规范。
```

### 35.3 AI Review 自我确认偏差

同一个 Agent 写代码又 Review 代码，容易漏掉自己的错误。应对方式：

```md
- 高风险代码由人审。
- 关键 PR 可用另一个 Agent 做独立 Review。
- Review Prompt 必须基于规范和风险等级，而不是泛泛检查。
```

### 35.4 自动化通过但架构失败

测试通过不代表架构合理。应对方式：

```md
- 大改动必须架构 Review。
- 关键模块必须维护 ADR。
- 每次新增目录 / 抽象 / 依赖都要说明理由。
```

---

## 36. 待确认问题

落地到具体项目时，需要确认：

```md
- 项目使用哪些 AI 工具：Codex、Claude Code、Copilot、Cursor、其他？
- 是否统一使用 AGENTS.md 作为主入口？
- CLAUDE.md 是否使用符号链接，还是单独维护？
- 前端是否使用 TypeScript？
- 后端是否使用 FastAPI、Django、Flask 或其他 Python 框架？
- API 是否使用 REST、GraphQL 或 RPC？
- 是否有支付、权限、隐私、AI、移动端、跨境数据等高风险业务？
- 哪些目录允许 AI 自动修改？
- 哪些目录必须人工审批？
- CI 是否具备 typecheck、unit test、integration test、secret scan、dependency scan？
- 团队是否要求记录 AI 工具、模型和 Prompt 摘要？
```

---

## 37. 建议下一步拆分的专项文档

```md
1. AGENTS.md 落地模板专项
2. React 项目前端 AI Coding 规范专项
3. Python / FastAPI 后端 AI Coding 规范专项
4. AI 代码 Review Checklist 专项
5. 支付 / 权限 / 安全高风险人工 Review 专项
6. CI 自动化门禁专项
7. 依赖与供应链治理专项
8. 移动端项目 AI Coding 专项
9. 电商项目 AI Coding 专项
10. AI Agent / LLM 应用安全专项
```

---

# 附录 A：官方资料索引

以下资料用于校准本规范中关于 Agent 指令文件、安全开发、AI / LLM 风险和供应链治理的表述。具体项目落地时，应以团队实际工具版本和官方文档为准。

| 主题 | 官方资料 |
|---|---|
| Codex AGENTS.md | [OpenAI Codex：Custom instructions with AGENTS.md](https://developers.openai.com/codex/guides/agents-md) |
| Codex Best Practices | [OpenAI Codex：Best practices](https://developers.openai.com/codex/learn/best-practices) |
| Codex PLANS.md / ExecPlan | [OpenAI Cookbook：Using PLANS.md for multi-hour problem solving](https://developers.openai.com/cookbook/articles/codex_exec_plans) |
| Claude Code CLAUDE.md | [Anthropic Claude Code：How Claude remembers your project](https://docs.anthropic.com/en/docs/claude-code/memory) |
| GitHub Copilot Custom Instructions | [GitHub Docs：Adding repository custom instructions for GitHub Copilot](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) |
| NIST SSDF | [NIST SP 800-218 Secure Software Development Framework](https://csrc.nist.gov/pubs/sp/800/218/final) |
| NIST SSDF for Generative AI | [NIST SP 800-218A Secure Software Development Practices for Generative AI and Dual-Use Foundation Models](https://csrc.nist.gov/pubs/sp/800/218/a/final) |
| OWASP LLM Top 10 | [OWASP Top 10 for Large Language Model Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) |
| OWASP Secure Coding | [OWASP Secure Coding Practices Quick Reference Guide](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/) |
| OWASP Software Supply Chain | [OWASP Software Component Verification Standard](https://scvs.owasp.org/) |

---

# 最终收敛

AI 写完的代码不失控，靠的不是人类逐行盯住所有实现，而是把控制点前移：

```md
第一层：架构层 —— 人必须控制系统边界、核心模块、数据流、外部依赖和非功能约束。
第二层：模式与抽象层 —— 人必须控制目录、分层、接口契约、组件模式、错误处理和测试规范。
第三层：实现层 —— AI 可以大幅放大函数、组件、页面、接口和测试的实现效率。
```

当项目越来越大时，团队的掌控感不是来自“我读过每一行代码”，而是来自：

```md
- 我知道系统边界在哪里。
- 我知道模块之间怎么交互。
- 我知道每层代码应该做什么、不应该做什么。
- 我知道接口契约是什么。
- 我知道哪些地方可以改，哪些地方不能随便改。
- 我知道 AI 每次变更是否经过测试和 Review。
- 我知道高风险代码有人类把关。
```

这才是 AI Coding 从“快速生成代码”走向“可生产、可维护、可上线”的关键。
