ploop/docs/guides/ai-development-workflow.md
2026-08-31 15:27:34 +08:00

3.2 KiB
Raw Permalink Blame History

AI 驱动开发工作流

本流程让 AI 以小而可验证的工作包推进 PLoop。核心链路是:

需求 R:为什么做、验收什么
  → 架构 / 决策 D:采用什么机制、接受什么取舍
  → 计划 M / 工作项 W:本次只改什么、如何验证
  → 代码与测试:产生可复现证据
  → TODO / 追踪矩阵:记录状态并回链

1. AI 每次开始时做什么

  1. 读取根 AGENTS.md、需求索引、决策记录、TODO 和关联设计文档。
  2. 判断请求属于哪一类:新需求、需求澄清、架构选择、计划拆分、已批准实施、缺陷修复或验证/复盘。
  3. 找到或补充关联 ID:R-*、D-*、M*/W-*。若请求会改变用户结果但没有 R-*,先建立/澄清需求;若实现机制会影响边界而没有设计或决定,先写设计并请求确认。
  4. 对非平凡代码任务创建或更新一个 工作项,并将 TODO 中唯一进行中的叶子任务指向它。

2. 哪些关口由人拍板

AI 可自主完成已确认范围内的读取、文档整理、局部实现、测试、修复和证据记录。以下情况必须给出选项、影响和推荐,再等待项目负责人决定:

  • 新增/收缩用户可见能力、验收标准或 benchmark 口径;
  • DDD 边界、前后端公开 API、数据格式、数据库 migration 策略;
  • gold/private artifact 的访问规则、外部 RAG 调用方式、secret/权限;
  • 新依赖、长期任务的并发/成本、真实 full run、外部服务、部署或不可逆操作;
  • 跨包/跨页面提取共享模块,但尚无第二个真实消费者。

对已有决定的实现细节,AI 应作最小合理假设并在工作项中记录;不要用反复澄清阻塞低风险的局部推进。

3. 实施时的作用域控制

  • 后端改动限于 backend/;前端改动限于 frontend/。根目录只接收跨包编排、文档和部署配置。
  • 先按 前端架构 将页面专属代码放到页面目录;仅有两个真实消费者时才提升到业务域 _shared/ 或 shared/。
  • 领域规则写入 backend/src/ploop/domain 的充血模型;application 只编排,infra 只实现技术 adapter。不得为“方便”绕过 gold、artifact 或状态机边界。
  • 文档只在事实所有者处更新:需求不写实现细节,设计不记实时状态,TODO 不复制设计,外部参考不伪装成已采纳方案。

4. 完成与报告

每个完成声明都要包括:实际改动、运行的验证命令及结果、未验证内容和下一步。然后:

  1. 在工作项写入完成证据;
  2. 更新 plan/TODO.md 的状态、证据与下一步;
  3. 若影响需求或架构,更新需求、设计、决策和 追踪矩阵;
  4. 确认文档链接有效,且不把 gold、secret、私有路径放入日志、fixture 或浏览器可见文本。

“代码已写”不是完成;只有满足工作项验收并有可复现证据才能标为 DONE。测试不具备、环境缺失或需要人工判断时,如实标记 BLOCKED 或保留为 IN PROGRESS。