AI Agent Workflow Notes：从“让 AI 写代码”到“让系统持续生长”
agent 项目中真正要沉淀的不是多写代码，而是设计理由、影响分析、阶段收口和系统状态复述。
Cover
AI Agent Workflow Notes：个人 agent 工作流记录 writing cover.
Why this matters
过去几个月，我用 agent 完成了大量任务：部署网站、整理项目、生成报告、验证链接。但回头看，最有价值的产出不是"任务完成了"，而是任务完成过程中产生的设计理由、影响分析和系统状态记录。
这个观察让我意识到：agent 工作流的核心价值不在于"自动化"，而在于"可沉淀"。一个好的工作流应该像一个好的实验记录——不仅记录结果，还记录假设、方法、限制和后续方向。
这些笔记是我对 agent 工作流的持续反思，目标是建立一套可复用、可验证、可迭代的个人工作流系统。
Core idea
agent 工作流的几个核心原则：
- 阶段化：每个任务拆分为明确的阶段，每个阶段有输入、输出和验证标准。这让执行过程可观测、可回滚。
- 报告驱动：每个阶段完成后生成结构化报告，记录做了什么、结果如何、下一步建议。这让项目状态始终可见。
- 设计理由优先：不是记录"做了什么"，而是记录"为什么这样做"。这让未来的自己能理解当时的决策。
- 系统状态复述：每次任务完成后，用"人能理解的语言"复述当前系统状态。这强迫我真正理解系统，而不是机械执行。
这些原则的来源：软件工程的最佳实践（版本控制、测试驱动开发）、科学研究的方法论（实验记录、可重复性）、以及个人知识管理的经验（Zettelkasten、Commonplace Book）。
Notes
从"让 AI 写代码"到"让系统持续生长"
最初使用 agent 时，我的目标很简单：让 AI 帮我写代码、改配置、生成内容。但很快发现，这种方式的问题在于——每次任务都是孤立的，agent 做完就忘了，下次遇到类似问题还要重新解释。
真正的转变发生在意识到：agent 不应该只是"执行者"，而应该是"系统的一部分"。这意味着：
- 每次执行都要留下可追溯的记录
- 设计理由要足够清晰，让未来的 agent（或人）能理解
- 系统状态要定期复述，确保所有人对当前状态有共识
- 修改要有影响分析，知道改了什么、为什么改、可能影响哪里
这个转变让 agent 工作从"临时修补"变成了"系统增长"。
阶段报告为什么重要
阶段报告不是形式主义，而是强制思考的工具。当我要求 agent 在每个阶段结束后生成报告时，实际上是在强迫它（和我）回答几个问题：
- 这个阶段的目标是什么？
- 实际做了什么？
- 结果是否符合预期？
- 发现了什么问题？
- 下一步应该做什么？
这些问题看起来简单，但在快速执行中很容易被忽略。阶段报告确保了即使执行速度很快，思考也不会被跳过。
在 conanxin.com 的 HP-1 到 HP-13 中，每个阶段都有完整的报告。这些报告不仅记录了做了什么，更重要的是记录了当时的假设和限制。当几个月后回看时，我能清楚理解为什么当时做了某些决定。
设计理由比实现细节更值得保留
代码会过时，配置会变更，但设计理由——"为什么这样做"——往往比"做了什么"更有长期价值。
一个具体例子：conanxin.com 选择静态 HTML/CSS/JS 而不是 Astro 或 Next.js。这个决定的设计理由是：
- 当前阶段内容量不大，不需要构建工具
- 直接编辑文件比配置构建流程更快
- 未来内容增多后再升级，避免过早优化
- 保持简单，让 agent 也能直接理解和修改
这些理由在 HP-1 时被记录，到了 HP-10 内容增多时，正是这些理由帮助判断是否该升级。如果没有记录，可能会因为"别人都用 Astro"而盲目升级。
修改影响分析是给未来的自己看的
每次修改前，agent 会分析"这个修改可能影响哪里"。这看起来是额外工作，但实际上是防止隐性破坏的关键。
在 HP-11 添加 Case Studies 系统时，影响分析指出：
- 需要新增 build-case-studies.mjs 脚本
- 需要更新 build-discovery.mjs 纳入 case studies
- 需要更新 build-home.mjs 在首页展示
- 需要更新 styles.css 增加 case study 样式
- 需要更新 package.json 增加 build 步骤
如果没有这个分析，很容易遗漏某个步骤，导致构建失败或页面样式异常。影响分析让修改的"涟漪效应"可见。
阶段收口：用人话复述系统状态
阶段收口是 HP 系列的核心仪式。每个阶段结束时，agent 会用"人能理解的语言"复述系统当前状态。这不是技术总结，而是"如果向一个不了解项目的人介绍，你会怎么说"。
这种复述的价值在于：
- 强迫从用户视角理解系统，而不是从实现视角
- 发现实现中的不一致或遗漏
- 为下一阶段建立清晰的起点
- 形成可公开的项目描述（如 case study）
HP-10 的收口报告中有这样一句话："conanxin.com 当前是一个结构化的个人知识工作台，包含 Projects、Writing、Lab、Map、Search、Tags 六个模块。"这句话后来直接成为了 About 页面的描述。
我如何在 conanxin.com 中使用这套方法
conanxin.com 本身就是这套方法论的实践场：
- HP-1 到 HP-13：每个阶段都有明确目标、范围、验证标准和报告
- build 脚本链：writing → lab → case-studies → about → links → relations → media → discovery → home，每个步骤可独立运行和验证
- 数据驱动：所有内容通过 data/*.json 管理，页面从数据生成，保证一致性
- 关系网络：Projects、Writing、Lab、Case Studies 之间通过 relations.json 建立关联，形成知识网络
- 公开档案：所有阶段报告保存在 docs/ 目录，成为可检索的项目历史
这套方法不是一次性设计出来的，而是从 HP-1 开始逐步迭代。每个阶段的报告记录了当时的假设，这些假设在后续阶段被验证或修正。
How I use it
这些工作流笔记的应用场景：
- 项目执行：任何新项目都使用标准化的阶段模板，减少决策疲劳
- 知识沉淀：工作流中的设计理由和系统状态记录，成为后续项目的参考
- 错误复盘：当工作流失败时，报告中的记录帮助快速定位问题
- 能力扩展：验证成功的工作流模板可以应用于新的任务类型
Related
相关项目：Hermes、OpenClaw、conanxin-homepage 相关文章：Notebook / Commonplace Book 后续可补充：工作流模板库、常见错误模式清单、agent 能力边界地图、与其他自动化工具（如 n8n、Make）的对比Next
- 建立标准化的工作流模板库
- 设计工作流质量评估指标
- 探索多 agent 协作模式
- 将阶段报告自动生成机制化
Related Projects
AI Agent Workflow Notes 总结了 Hermes / OpenClaw 项目中的阶段化执行方法。
OpenClaw 的长期价值来自 agent 工作流、设计理由和阶段报告沉淀。
conanxin.com 的每个阶段都是 agent 工作流沉淀的实例。
Cloud Mail 是个人邮件入口与 agent 协作系统的一部分。
小径小程序体现了阶段化开发、feature flags、云端/本地协作和状态复述方法。