@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/external-knowledge/common/AI_Coding_Production_Control_Framework_AI/345/206/231/345/256/214/347/232/204/344/273/243/347/240/201/345/246/202/344/275/225/344/270/215/345/244/261/346/216/247.md

@@ -1,2055 +1,2055 @@
-# 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 从“快速生成代码”走向“可生产、可维护、可上线”的关键。
+# 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 从“快速生成代码”走向“可生产、可维护、可上线”的关键。