我的 AI 编程工作流：SPEC、任务拆分、验证和交接

我现在更愿意把 AI 编程理解成一种协作流程，而不是一个“让模型直接帮我把功能做完”的按钮。

AI 很适合读代码、铺开重复改动、补测试、跑构建、整理 diff。人更适合决定目标、边界、取舍和验收标准。问题是，如果没有一个稳定流程，这两部分很容易混在一起：模型越改越多，人越看越累，最后只能靠感觉判断“应该差不多了”。

所以我会给 AI 辅助开发加一个很轻的闭环：

接管上下文 -> 写清 SPEC -> 拆小任务 -> 实现 -> 验证 -> 提交 -> 交接

这不是为了显得正式，而是为了让每次改动都能继续、能回看、能停下来。

第一步：先接管上下文

已有项目里，我不会让 Agent 上来就改代码。先让它读项目状态。

最小接管清单通常是：

README.md：项目是什么，怎么运行。
SPEC.md：当前目标、功能边界、验收标准。
AGENTS.md / 项目规则：代码风格、验证方式、安全红线。
HANDOFF.md：上一轮做到哪里，下一步是什么。
git status：工作区有没有别人或上一轮留下的改动。
最近几条提交：当前分支最近发生了什么。

这个步骤看起来慢，但能避免很多低级事故。尤其是工作区已经有未提交改动时，Agent 必须先知道哪些是已有改动，哪些是这轮任务要碰的文件。

我希望接管后能回答这几个问题：

当前目标是什么？
当前阶段是什么？
已经完成什么？
还没完成什么？
工作区有没有未提交改动？
下一步只做什么？

只要这几句说清楚，后面改代码就不容易漂。

第二步：把需求写成 SPEC

很多 AI 失控不是因为模型差，而是因为需求还没变成可执行边界。

比如一句“帮我做一个工具页”，听起来清楚，实际里面有很多没说完的东西：目标用户是谁，首屏放什么，哪些功能必须有，哪些不做，移动端怎么验收，是否需要后端，是否要保存数据，是否会碰隐私。

SPEC 不需要写得很长，但至少要包含这些内容：

目标：这次到底要解决什么问题。
用户：谁会用，什么时候用。
范围：这次做什么，不做什么。
数据：需要哪些输入、输出和状态。
接口：有没有 API、路由、文件格式或外部依赖。
验收：怎样才算做完。
风险：哪些文件或逻辑不能随便碰。

对新功能，我会先写 SPEC；对小 bug，我可以不写完整 SPEC，但至少会写清楚复现、预期和修复范围。

SPEC 的价值不在文档本身，而在它迫使人先做判断。AI 可以帮忙补问题，但最后哪些要做、哪些不要做，仍然要人决定。

第三步：任务拆到 15-30 分钟

AI 很擅长连续执行，但长任务越长，越容易上下文膨胀、目标漂移、验证遗漏。

我更喜欢把任务拆成小块：

有明确输入。
有明确输出。
有明确验收。
改动文件范围可预期。
做完可以单独验证或提交。

一个好任务长这样：

任务：把博客文章列表里的草稿过滤掉。
输入：现有 content collection 和博客列表页。
输出：公开页面不展示 draft: true 的文章。
验收：pnpm build 通过；/blog 不出现草稿；草稿详情页不生成公开路由。

一个不好的任务长这样：

任务：优化博客。

后者太宽，模型会自然地补很多自己的理解：改 UI、改文案、改路由、加组件、顺手重构。不是它坏，是任务边界给得太松。

第四步：一次只执行一个阶段

执行阶段我通常让 Agent 按这个顺序走：

读相关文件 -> 说明改动范围 -> 编辑 -> 自查 diff -> 运行验证 -> 汇报结果

这里最重要的是“改之前说明范围”。如果它准备动的文件比预期多，或者想引入新依赖、改构建配置、碰数据库迁移、碰权限逻辑，就应该先停下来确认。

我对 AI 写代码的期待不是一次完美，而是每一步都能收住：

不顺手重构无关文件。
不把多个无关目标塞进一个提交。
不为了通过类型检查改掉业务含义。
不把本地密钥、截图、临时文件误提交。
不在不确定时假装确定。

这几条听起来像常识，但对 Agent 很关键。Agent 的默认倾向是“继续解决问题”，而工程上有时更需要“知道什么时候停”。

第五步：验证不是可选项

AI 辅助开发里，验证要尽量变成习惯动作。

不同任务验证方式不一样：

任务类型	优先验证
文档 / 文章	检查 frontmatter、链接、路径、格式
前端页面	build、关键页面预览、移动端文字溢出
逻辑函数	单元测试、边界用例
API / 数据处理	集成测试、错误输入、空数据
重构	现有测试、typecheck、构建、关键路径手动检查
高风险功能	回归测试、代码审查、分支隔离

如果项目有 lint、test、typecheck、build，改完就尽量跑。如果缺依赖、命令太慢或环境跑不起来，也要明确写出来，不能假装验证过。

验证的目标不是证明 AI 很可靠，而是让每轮改动有一个可检查的落点。

第六步：提交要小而完整

我更喜欢一个任务一个提交。提交前先看 git status，确认只包含这轮相关文件。

AI 很容易误用“全量暂存”。这在干净仓库里没事，但真实项目经常有截图、临时日志、实验文件、别人改了一半的代码。最稳的方式是只暂存目标文件：

只提交本任务相关文件。
未跟踪截图、临时目录、本地配置不要碰。
提交信息写清楚类型和结果。

提交粒度不需要机械，但要能回答一个问题：如果这次改动出问题，我能不能单独回看或回滚？

第七步：长任务必须交接

AI 工具之间不共享聊天记忆。Claude、Codex、IDE、终端窗口，真正共享的是文件系统和 git 状态。

所以长任务结束时，我会更新 HANDOFF.md 或任务文档，至少记录：

当前目标：
已完成：
正在做：
下一步：
已修改文件：
已验证：
未验证：
风险和注意事项：

交接不是给别人看的形式主义，也是给未来的自己看的缓存。尤其是连续做几天之后，最危险的不是不会写代码，而是忘了前面为什么这么取舍。

哪些地方可以简化

这套流程不是每次都要完整跑一遍。

这些情况可以直接做：

明确错别字。
一行链接修复。
小范围样式问题。
已经有复现路径的简单 bug。

这些情况要把流程拉起来：

新功能。
多文件重构。
不熟悉的旧项目。
需求有争议或容易漂移。
涉及权限、支付、数据、生产配置。
用户已经连续纠正方向。

我的判断标准是：改动越不可逆、影响面越大，越需要 SPEC、任务拆分、验证和交接。

一套可复制的最小模板

如果只想先落地，不需要复杂系统，可以从这四个文件开始：

README.md   项目介绍和运行方式
SPEC.md     当前目标、范围、不做什么、验收标准
AGENTS.md   AI 工作规则、命令、安全红线
HANDOFF.md  当前状态、下一步、验证记录

每次让 AI 接手时，开场可以很简单：

先读 README.md、SPEC.md、AGENTS.md、HANDOFF.md、git status 和最近 5 条 git log。
然后输出当前目标、阶段、已完成、未完成、工作区状态和下一步。
这轮只做某一个任务，改完跑验证并提交。

这段话不神奇，但它把 AI 从“聊天助手”拉回了“项目协作者”的位置。

最后

AI 编程真正有用的地方，不是把工程判断交出去，而是把执行速度提上来。

人负责方向、边界、品味和验收；AI 负责阅读、生成、修改、验证和整理。中间靠 SPEC、任务拆分、测试、提交和交接把状态固定住。

这套流程可能没有“一句话生成应用”听起来刺激，但它更适合长期项目。项目不是一次性生成出来的，而是一轮一轮被维护出来的。AI 要真正融进开发流程，也得经得起这种日常节奏。

Brief

AI-assisted development works best when the human keeps ownership of scope, taste and acceptance criteria, while the agent handles reading, editing and verification loops.

My default workflow is simple: read the project, write or update a SPEC, split work into small tasks, execute one task at a time, verify, commit and leave a handoff note.

The goal is not ceremony. The goal is to make AI work recoverable, reviewable and easy to continue across windows or tools.