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

我最近把这个博客从“给以前项目背书”转向“一个关注新技术、持续学习的开发者笔记”，这套工作流用得特别频繁。AI 编程不是只有一种用法，问方案、IDE 局部补全、让 Agent 改仓库、生成原型、做代码审查，每种都有合适场景。落到我自己维护的项目里，我基本分成新项目启动和旧项目维护两类来处理。

我常用到的几种方式

问方案和解释代码

最轻的用法。把报错、代码片段或技术选型丢给模型，让它解释、列步骤或给方案。比如我问过“Redis Lua 扣库存有哪些并发风险”，或者“这个博客的 frontmatter schema 该怎么设计”。适合把问题想清楚，但不适合直接让它改完整项目。

IDE 里的局部补全

Cursor、Copilot 这类工具适合快速小改。比如“给这个表单补 Zod 校验”或“按现有风格补单元测试”。反馈快，但容易只看当前文件，忽略项目整体约定。

CLI Agent 直接改仓库

Claude Code、Aider、Cline 这类是我用得最多的。它能读文件、看 git status、跑命令、跨文件修改。在改这个博客时，我经常这样提示：“只改 title、description、tags，不要碰正文。改完跑 pnpm build 和 git diff –check。”

威力大，但边界不清时它也很容易顺手改无关内容。所以我现在几乎每次都先喂 SPEC、HANDOFF 和明确约束。

Prompt-to-App 原型

适合快速验证想法。我会让它先生成能跑的原型，但不会直接当最终代码，后续还是得自己接手结构和验证。

AI Code Review

我现在越来越依赖第二视角。常让它“只看这个 diff 有没有回归风险”或者“从构建和移动端角度 review”。它不负责批准，只负责挑问题，让我改得更安心。

工作流型 Agent

把 AI 放进固定循环：读现状 → 写 SPEC → 拆任务 → 修改 → 验证 → 更新 HANDOFF。这主要用在长期项目，因为最难的不是写代码，而是控制范围和保持连续性。

我的开发场景一般有两种

• 新项目：从零开始，重点是把“到底要做什么”想清楚，并逐步建立文档。
• 旧项目维护：像现在改这个博客，重点是先搞清楚当前状态、保护已有改动、不让 Agent 乱扩展。

新项目流程

第一步不是搭框架，而是把需求问清楚：目标用户、第一版解决的具体问题、必须有的功能、明确不做的部分、验收标准。

确认完我就主动写 SPEC.md。这是整个工作流的起点，把“这次不做什么”白纸黑字写下来。比如这个博客的 SPEC 里明确写了“不自动 commit/push”“不要碰 .playwright-mcp 文件夹和根目录截图”。

同时我会更新 README.md。在第一次大规模使用 CLI Agent 时，我会让它帮忙生成 AGENTS.md，记录项目特定规则（必须用 pnpm、改完必须验证等）。当任务需要多轮对话时，我开始写 HANDOFF.md。

这些文档不是第一天就全写好，而是随着项目推进自然积累的。SPEC 最先，AGENTS 和 HANDOFF 在实际用 Agent 的过程中逐步完善。

SPEC 写完，我不会让 AI 一次做完整项目，而是先跑通最小闭环（能 build、主流程可走通）。看到真实结果后再拆小任务、每步验证。

旧项目维护流程

这些文档（README、SPEC、AGENTS、HANDOFF）大多是在项目还“新”的时候逐步建立起来的。这个博客就是如此，所以现在维护时可以直接读取和更新。如果遇到一个完全没有这些文档的老项目，我会先让 AI 从代码和 git history 里梳理出一个轻量版的 SPEC 和初始 HANDOFF，再继续往下走。

旧项目第一步是读现状。我会让 Agent 先看 README、SPEC、AGENTS、HANDOFF（尤其是顶部交接那段）、package.json、git status、最近 git log 和当前任务相关文件。

读完让它先输出“当前目标、已完成、这轮只做什么、不做什么、工作区状态”，把双方都钉死。

改之前必须说清楚范围和约束，尤其是这个博客当前任务，我会反复强调“只动当前任务相关文件，不顺手清理或格式化无关文件”。我还会明确要求不回滚已有改动、不用 git reset --hard、不碰截图和临时目录。

验证严格按项目已有方式走。这个博客就是 pnpm build + git diff --check。

HANDOFF.md 的作用

长任务我一定会维护 HANDOFF.md。因为对话上下文会压缩，而且我经常在 Claude、IDE、终端之间切换，只有文件系统和 git 是共享的。

Handoff 里我主要记录当前精确目标、已完成事项、验证结果、风险和注意事项（比如“不要自动 commit”“只改任务相关文件”）。它最关键的作用是防跑偏——我会把“下一步只做 XXX，不要做 YYY”等得很窄。新窗口接手时，Agent 第一眼就能看到边界。

我现在改这个博客的很多轮，都是靠 HANDOFF 把方向一次次拉回来的。

我的完整流程

新项目：问清需求 → 主动写 SPEC 并逐步建立文档 → 最小闭环 → 拆小任务 → 每步验证 → 长任务维护 HANDOFF

旧项目维护（这个博客目前主要用的）：读已有文档和 git 状态 → 确认这轮只做什么 → 说明范围和约束 → 小步修改 → 跑项目验证 → 更新 HANDOFF

核心区别是：新项目重点定义目标并建立文档，旧项目重点保护现状、维持连续性。

哪些情况可以简化

不是所有改动都要走完整流程。错别字、改标题、修明确的小 bug，我会直接让 Agent 改。

但遇到新功能、多文件改动、需求还在变化、涉及构建配置、对话已经很长开始反复纠正方向时，我基本会拉满流程。

判断标准很简单：影响越大、越容易跑偏，越需要这些文档和流程。

最后

这套做法没什么特别炫的地方，但它让我能长期、稳定地用 AI，而不是用几次就失控。

把这个博客从项目展示转向开发者学习笔记的过程中，我最深的体会是：真正有用的不是某个万能 prompt，而是“先定边界、建立文档、小步验证、长任务写交接”这个习惯。改完不是“看起来差不多”，而是 pnpm build 通过、git diff --check 没问题、方向还在 HANDOFF 划定的范围内。

这样虽然慢一点，但活儿干得更踏实，也更可持续。

Brief

AI coding has several common modes: asking for ideas, local IDE assistance, repo-level agents, prompt-to-app prototypes and AI code review.

For my own work, especially while shifting this blog from project showcase to developer learning notes, I split into new projects and existing project maintenance.

SPEC, task slicing, verification and HANDOFF are practical tools that grew with the project. They keep scope clear, make changes reviewable and stop long agent sessions from drifting.