AI Native 实战开发流程：以“管理员后台”为例（通用模板）

本流程基于《AI Native 开发治理笔记》的治理理念，以 v3 管理后台 的一个典型功能“退款审核”为案例，展示如何用 AI 工程化方法交付一个安全、合规、可积累的生产级功能。该流程可复用到任何管理员后台的 CRUD、审批、报表、导出等场景。

一、总体开发阶段概览

二、前置条件：工程骨架已搭建

假设团队已经按治理笔记建立了以下目录和基础文件：

v3-system/
├── apps/                     # 现有管理后台代码
├── docs/                     # 已有数据库 DDL、API 文档
├── business/                 # 已有 order/wallet/refund 等业务规则
├── ai/
│   ├── tasks/current/
│   ├── workflows/
│   ├── reviews/
│   ├── engineering-knowledge/
│   └── development-logs/
├── AGENTS.md                 # 已编写全局 AI 规则
└── CLAUDE.md

如果还没有，必须先按笔记完成骨架搭建，否则后续流程会因为缺少约束而失控。

三、实战步骤详解（以退款审核为例）

阶段 1：知识准备——让 AI 有据可依

目标：确保 AI 看到的“真相”是完整且准确的。

人需要做的事情：

1. 检查 docs/

   • 是否存在 refund_order 表的 DDL？字段、索引、注释是否完整？
   • 是否有关联的 wallet、wallet_transaction 表结构？
   • 支付回调相关的第三方文档是否可访问？
   • 如果不全，立即用 mysqldump --no-data 导出最新结构放入 docs/db/。

2. 编写/更新 business/refund/rules.md
   按照笔记模板，补充退款专属规则，例如：

   # 退款规则
   1. 仅支付成功订单可退款
   2. 退款必须审核（状态机：PENDING_AUDIT → APPROVED / REJECTED）
   3. 退款执行时原子增加用户余额（UPDATE wallet SET balance = balance + ? WHERE user_id = ?）
   4. 幂等：退款单 APPROVED 后重复请求直接返回成功
   5. 记录 wallet_transaction 类型为 REFUND

3. 检查 business/wallet/invariants.md
   确认余额不变量（balance >= 0）等规则已存在。

产出物：更新后的 docs/ 和 business/，AI 的“知识底座”建立完毕。

阶段 2：任务规划——画好 AI 的“活动圈”

目标：精确控制 AI 本次能做什么、不能做什么。

人需要做的事情：

1. 创建任务文件 ai/tasks/current/TASK-REFUND-APPROVE.md
   按模板填写（关键字段见笔记第七章），示例要点：

   • Goal：开发退款审核通过接口
   • Allowed Modules：RefundController、RefundService、RefundDao，表 refund_order, wallet, wallet_transaction
   • Forbidden Modules：auth, distributor, goods，以及任何前端代码
   • Technical Requirements：JdbcTemplate、@Transactional、Redis 锁、幂等
   • Deliverables：修改的文件、SQL 变更、风险点
2. 选择或编写 workflow
   如果 ai/workflows/add-admin-api.md 已存在，则沿用；否则参考笔记第八章编写一个。workflow 定义了标准开发步骤：分析 → 方案 → 编码 → 自检。

产出物：TASK-REFUND-APPROVE.md 和确认使用的 workflow。

阶段 3：AI 分析对齐——让 AI 先“说出来”再动手

目标：AI 在不写代码的前提下，给出完整技术方案，由人确认，避免方向错误。

操作步骤：

1. 新建 AI 会话，使用分析 Prompt（复制以下内容）

   请按顺序读取以下文件：
   1. AGENTS.md
   2. business/refund/rules.md
   3. business/wallet/invariants.md
   4. ai/workflows/add-admin-api.md
   5. ai/tasks/current/TASK-REFUND-APPROVE.md
   
   目标：理解系统约束和本次任务边界。
   现在，仅进行分析设计，**禁止编写任何实现代码**。
   
   请输出：
   1. API 设计草案（POST /api/admin/refund/approve，请求体 refundOrderId，返回体通用Result）
   2. SQL 设计草案（查询退款单、更新状态、原子更新钱包余额、插入流水）
   3. 事务边界：退款单状态更新 + 余额更新 + 流水插入必须在同一事务
   4. 并发控制方案：Redis分布式锁，key = lock:refund:approve:{refundOrderId}，超时30s
   5. 风险点分级（如：余额并发更新 -> 已用原子SQL规避；锁未释放导致死锁 -> finally释放）
   6. 需要澄清的业务点（如：退款金额是否包含优惠券部分？我们假设仅退现金）

2. 审核 AI 输出的分析报告
   重点检查：

   • SQL 是否使用原子更新而非 select-then-update？
   • 事务是否覆盖了所有需要一致性的操作？
   • 幂等逻辑是否只是状态检查（可靠吗？）？结合 Redis 锁后的行为？
   • 权限校验是否遗漏（Controller 上要加 RBAC 注解）？
3. 修改方案直到满意，若有业务不确定点，拉产品经理确认。

产出物：一份人工确认过的技术方案（可保存在 ai/reviews/ 下作为设计记录）。

阶段 4：AI 开发实现——戴着手铐跳舞

目标：AI 严格遵守约束，产出符合规范的代码。

操作步骤：

1. 在同一会话（或保留上下文的新会话）发送开发 Prompt

   基于我们已确认的方案，现在开始编码。
   请严格遵守以下约束：
   - 仅修改 task 中 Allowed Modules 内的文件
   - 遵守 AGENTS.md 所有规则（SQL规则、事务规则、架构分层等）
   - 使用 JdbcTemplate，保持与现有代码风格一致
   - 实现幂等、分布式锁、事务、原子更新
   - 任何新增文件需先说明用途
   
   请按顺序产出：
   1. DAO 层方法（JdbcTemplate实现）
   2. Service 层逻辑（含事务和锁）
   3. Controller 层（参数校验、调用Service）
   4. 针对每个 SQL 给出 EXPLAIN 输出
   5. 自认为的实现风险点

2. 监控 AI 产出
   人随时检查 AI 是否有越界行为（比如偷偷修改了 WalletController），一旦发现立即叫停并纠正。
   通常 AI 会直接给出代码块，将其复制到对应文件或通过工具应用。

产出物：修改的 Java 文件（及可能的 SQL 迁移脚本），AI 提供的 EXPLAIN 结果。

阶段 5：质量审查——AI 自首 + 人工终审

目标：系统性捕捉缺陷，防止带病上线。

操作步骤：

1. 发送 Review Prompt

   请对我们刚刚实现的退款审核接口进行完整 Review，严格遵守 AGENTS.md 的 Review 规则。
   逐一检查：
   - SQL 注入
   - EXPLAIN 分析（再次确认索引命中）
   - 事务是否覆盖正确
   - 空指针可能点
   - 业务不变量（balance >= 0, 状态机）
   - 幂等性
   - Redis 锁的使用（正确加锁、解锁、超时）
   - RBAC 权限注解是否添加
   - 缓存一致性（如果涉及缓存）
   请输出结构化 Review 报告，标注每项的通过/不通过/风险及建议。

2. 人复核 Review 报告

   • 对阻断性问题，让 AI 立即修复，然后重新走一遍轻量 review。
   • 存档报告到 ai/reviews/REVIEW-REFUND-APPROVE-20260527.md。

产出物：Review 报告，以及修复后的代码。

阶段 6：知识沉淀——把教训变成 AI 的长期记忆

目标：让这次开发的经验在未来项目中自动生效。

操作步骤：

1. 提炼 engineering-knowledge
   从 Review 报告和开发过程中的坑点提炼通用知识，例如：

   • refund-atomic-balance.md（退款余额原子更新）
   • redis-lock-finally-unlock.md（锁必须 finally 释放）

   人可手动编写或让 AI 生成：

   从本次 Review 和开发日志中提取可复用的工程知识，按 ai/engineering-knowledge/ 模板创建文件。

2. 生成 development-log

   请生成本次开发日志，包含已完成功能、遗留风险、关键决策、下一步计划，存入 ai/development-logs/LOG-20260527-REFUND-APPROVE.md。

产出物：新的 knowledge 文件和开发日志。

阶段 7：交付上线——完成闭环

目标：功能正式合入主分支。

1. 运行单元测试、集成测试。
2. 进行 Code Review（可能还有人工同事）。
3. 部署到测试环境验证。
4. 上线生产，监控日志和报警。

此时，TASK-REFUND-APPROVE.md 移入 ai/tasks/archive/。

四、对管理员后台的通用性说明

上述流程不限于退款审核，任何后台功能开发皆可套用：

• 新增列表查询：task 约束仅修改列表相关 DAO/Service，workflow 引用 add-admin-query.md，business 关注深分页、数据脱敏规则。
• 导出报表：约束文件生成、异步任务、限流规则。
• 权限/角色管理：重点关注 RBAC 规则、审计日志要求。
• 配置管理：关注缓存刷新、并发修改。

只需按照功能点创建对应的 business 规则和 task，选择或定制 workflow，其余审查、知识沉淀、开发日志步骤完全一致。

五、核心成功要素回顾

1. 约束先行：business、AGENTS、task 必须写清楚再让 AI 动手。
2. 分析分离：先出方案、对齐，再编码，避免返工。
3. 审查强制：SQL、事务、幂等、并发必须逐项过关。
4. 知识积累：每次开发结束必须产出 knowledge，形成复利。
5. 记忆外挂：development-log 让 AI 随时恢复上下文，支撑连续迭代。

坚持这套流程 2~3 个迭代后，团队会发现：新增后台功能的 AI 出错率大幅下降，开发速度稳步提升，而维护成本反而降低——因为所有规则都已编码在知识体系中，AI 越来越像一个懂业务的资深工程师。