AI 工作流最佳实践

AI 工作流最佳实践

0. 三层模型

1. 源文档（SoT: Source of Truth），别名：Structure、Constraint
2. 执行包（Execution Pack, EP），别名：Evolution、Operation、Transaction
3. 代码（Code），别名：State

• 分别代表“结构层/演化层/状态层”。系统通过 SoT 定义有效空间，通过 EP 在空间内进行有界演化，通过 Code 实例化当前状态，并以 Code 执行结果反哺 SoT。
• 也可以理解为“规则、行为、状态”
• 还可以理解为“人类工作区/AI 工作区/最终结果”。随着 AI 能力增强，SoT 会逐步压缩

整体模型抽象由 一天实现个人博客 而来。从“架构文档/cursor rules（规范文档类）/roadmap” 演化为 “源文档 → 编译产物 → 代码”，再到当前的三模型。

1. 模型详述

1.1 源文档（SoT: Source of Truth）

定义：当前项目的所有上下文，包含但不限于约束（如需求文档、架构文档等）、规范。

• 名字起源于源代码，只不过 AI 时代，人机交互从代码演变为了文档；
• 随着 AI 能力提升，此部分会逐步结构化（含文档版本管理）；
• SoT 并不代表永恒真理，该部分也不应该描述过程与实现细节；
• 源文档不仅包含需求文档，更要包含生成需求文档所需的素材（需求文档的生成也应作为一个 EP 去执行）；
• 典型内容：
  • 目标与计划：北极星、milestone/roadmap（含当前进度）
  • 需求与体验：产品需求文档（可从飞书单向同步到代码仓）、UI/UE 规范
  • 边界与约束：安全/隐私/合规/依赖/改动边界
  • 契约与规则：API/数据模型/错误模型/事件埋点/领域词典、代码/分支/commit 规范、rules
  • 架构与决策：业务架构、技术架构、ADR（关键取舍记录，需要固定模版）
  • 质量与验收：DoD/回归点/测试架构、验收标准与测试清单
  • 模版：模块目录模版、ADR 模版、EP 模版等
• 此部分会逐步变的巨大，所以后续需要分层，并做严格熵增治理；

1.2 执行包（Execution Pack, EP）

定义：AI 的上下文冻结快照 + 压缩（聚焦当前任务） + 任务拆分（粒度细化） + 协议执行，保证可落地与防漂移。

• 由 SoT 的“编译产物”抽象而来；
• 三层模型中 EP 并不强制绑定分支，但为了方便理解落地，可以简单理解为一个 Feature，对应一个分支，最终生成一个 PR；
• 如果执行失败，则总结经验并补充 SoT 后，重新生成新的 EP；
• 上下文权威仍留在源文档；执行包只做输入锁定（引用 + 版本号/commit/revision）并保存执行摘要，不复制源文档全文；
• 典型内容：
  • 步骤清单（ steps.md，细到每一步都可编码粒度）
  • 测试用例清单、验证计划与证据引用
  • 回滚方案
  • 依赖与风险（不含具体代码）
  • 该 EP 落地期间与 SoT 产生的冲突记录（用于最后回补 SoT）

1.3 代码（Code）

定义：传统意义上的代码层。

• 遵循项目架构与代码规范
• 执行包输出测试用例清单与验收口径；自动化测试代码属于代码层。
• 变更必须可验证（可运行/可测试/有证据）
• 典型内容：
  • 代码
  • 具体测试用例

2. 流转机制

在项目启动后（已有规范、模版等的前提下），执行流程如下：

2.1 需求生成

• 素材收集
• 需求分析、讨论、定稿
  • 定义 DoD（核心验收标准）：明确功能、性能、体验的通过标准（作为 SoT 契约的一部分）
• 由 AI 根据变更补充其他边界、约束、契约等
  • 边界：目标边界、范围边界、系统边界、风险边界、变更边界等，把“不可讨论/不可变更/不可触碰”的内容先固定，避免落地时漂移与返工
  • 契约：错误模型契约、接口与数据契约、事件埋点契约等，把“团队/AI 必须一致理解”的内容写成可评审的契约，减少返工与扯皮
• （可选）整个过程作为一个 EP 执行
• （可选）生成需求分支，上下文补充等都记录与需求分支

2.2 EP 生成

目标：把本功能的源文档输入锁定，结合 EP 模版、规范、规则等，把落地所需细节（步骤/用例/验证/回滚等）固化成可执行清单（不含代码），作为实现与验收的唯一执行依据。

• （可选）生成 EP 分支（如有需求分支，则根据需求分支 fork EP 分支）
• 根据“引用 + 版本号/commit/revision”等锁定输入，生成摘要并验证上下文完整性
• 生成步骤清单（核心为 steps.md，细到可编码粒度），优先垂直切片（Vertical Slice）（选一条最短可验收路径，避免“写完所有代码再测试”的情况，尽早验证初步结果，避免漂移）
• 将需求阶段的 DoD 转化为具体的测试用例清单 + 验证脚本（测试代码在代码层）
• 执行过程如与 SoT 上下文冲突，将解决方案记录暂时记录到 EP 中，执行期间优先此部分，待执行验证完成后反哺 SoT

2.3 EP 执行（Code 生成）

目标：生成代码和对应测试用例；验证完成定义（DoD）等；验收最终结果（让“完成”可被客观判断，而不是“感觉差不多”）

2.4 反哺与熵增治理

归属：源文档更新，由 AI 主导收敛与清理；执行包按需更新。

目标：沉淀实现问题，防止上下文膨胀和语义漂移，保持文档长期可控。

• 流程：
  1. 证据收集：垂直切片与测试产出。
  2. 结论生成：AI 分析证据，输出文档更新或调整建议。
  3. 文档更新与收敛：
     • 写回源文档：术语、契约、边界、ADR 等。
     • 自动治理：去重、清理过期条目、统一命名与版本。
     • 高认知成本操作由人工审批，其余由 AI 执行。
• 原则：证据 → 结论 → 文档更新与收敛，不写未验证信息，保证结构清晰、可持续。

3. 备注

• 此文中的需求（Business Requirement, BR）包含但不限于：业务需求、运营需求、技术需求，所有可以明确目标化的 action 都可以被定义为需求（甚至明确需求本身都可以是一个需求）
• 去除原有 PM/RD/QA/UI 等角色分类与原工作流，统一为 agent 工程师
• 将 PRD/UI/Case 等上下文纳入统一仓库，并 git 管理，人只负责管理上下文，具体执行交由 AI
• 进度规划与管理统一进 git 管理（并实时展示）
• 原则上人类主要重心为“源文档”部分；尽量少介入“执行包”部分；原则上不直接介入“代码”部分
• 架构逐步朝着可实验方向演化（避免人类主观成为唯一决策源）
• EP 执行过程中，原则上不直接修改 SoT，而是通过反哺机制，在执行完后统一反哺

4. TODO

• AI Native Context Operating System，上下文 Index 系统（可参考 map 设计？）
• 熵增治理：SoT 会成为权力中心，而权力中心会产生瓶颈，SoT 的熵增会造成此流程不可持续（是否可以建模？）
• GC 策略（SoT 生命周期设计）：删除行为本身是极高认知成本行为（人类非常不擅长删除文档），删除意味着承担风险，因此必须制度化（不能依赖个人勇气）
• 文档的版本管理：SoT/EP 和部分文件的版本管理
• 规范/模版补充
• 结合多种模型，验证逻辑正确性、闭环、可扩展性
• SoT 的上游（各种信息）的收集即治理工作
• 最小稳定单元（MSU），定义在多 EP 并行与频繁反哺条件下，能够提前锁定语义冲突的最小结构单元
• 进度展示

5. 待思考问题

1. 所有东西都是可以落实到纸上的
2. 目录结构就体现了方法论（就像基因结构）
3. SoT 的熵增治理类似 GC，强软弱虚
4. 再进一步，可以把文件和其内容 Object 化，还可以添加版本
5. 可以标记为 deprecated
6. 是否可以写代码的方式写文档？
7. 文档域（业务意图）和代码域（工程事实）的双向实时同步验证系统（Digital Twin）
8. 测试是行为证据，不是决策证据。
9. 人与 AI 的边界到底（应该）在哪里？
10. 怎么看待“自然语言（源文档）天生是有损、模糊、非结构化的”
11. 这让我想起了之前看到的设计模式的核心就是“寻找变化点，然后通过应用设计模式隔离稳定部分与变化部分”
12. 目前的 SoT 仍然是中心化的，权利集中，后续是否要去中心化？
13. EP 目前仍然是任务驱动，而不是实验驱动，后续改如何做？
14. 多 agent 执行冲突问题