让 AI 稳定交付全栈项目：我的 Claude Code + OpenSpec + Superpowers 三件套实战

Tango2100
0 阅读9分钟

代码不再是壁垒，管住 AI 才是。

封面

开篇：AI 写代码爽的是第一个需求，崩的是后面每一个

用 AI 开发过项目的人都踩过这三个坑：

  • 改着改着 AI 就失忆了——上下文一长，前面聊过的约束全忘
  • 写着写着就跑偏了——当初要的是功能 A，返工三次后变成了 D
  • 合并的时候发现架构早已面目全非——每次变更看着都合理，合起来就是一锅粥

根因只有一个：AI 没有规格约束，只能凭直觉续写。人类工程师靠 code review 和设计文档对抗熵增，AI 开发同样需要一套「规格驱动」的流程。

过去一段时间我摸索出一套稳定跑通全栈项目的 SpecCoding 流程，核心是三个工具的协同分工，以及一套「先定全局，再拆任务，再逐个落地」的项目节奏。今天把它完整写出来。

一、三件套的角色分工：各司其职才不打架

很多人上手就是 Claude Code 单打独斗——能写代码，但没有规格、没有流程，本质上还是在"聊天式编程"。稳定的 AI 开发需要三种能力：

工具角色解决的问题
Claude Code执行者读文件、写代码、跑命令——实际的动手层
OpenSpec规格管家每个变更都有正式的 proposal / design / spec / tasks，版本化追踪
Superpowers工作流引擎brainstorming / writing-plans / executing-plans，把"思考-规划-执行"拆成独立阶段

为什么必须三者合体：

  • 只有 Claude Code：代码写得快，但没有规格约束，AI 一失忆就开始胡编
  • 只有 OpenSpec：规格齐全，但没有系统化的思考和规划流程
  • 只有 Superpowers：流程规范，但没有正式的规格沉淀，思考成果留不下来

合起来才形成闭环： Superpowers 定流程，OpenSpec 存规格，Claude Code 做执行。思考有方法、规格有文档、执行有工具——AI 就从"聊天伙伴"变成了"项目成员"。

二、最反直觉的一步：Spec 文档分两级

这是整套流程里最容易被忽略、但价值最大的设计。

很多人以为 spec 就是 OpenSpec 里的那些变更文档，其实那只是一半。 真正稳定的项目需要两级 spec：

项目级（spec/）—— 管整体、长期

文件作用维护原则
requirements.md项目整体需求仅在人工明确要求时 AI 才修改
design.md整体设计、架构决策、模块划分仅在人工明确要求时 AI 才修改
tasks.md里程碑级任务清单（每个 task 对应一个后续提案）内容人工维护；完成状态 AI 归档后自动勾选
devlog.md开发日志每次 PR 合并后 AI 追加一条
structure.md项目目录结构顶层目录变动时 AI 更新

需求级（openspec/changes/<name>/）—— 管单次变更、短期

文件作用
proposal.md是什么、为什么
design.md怎么做、架构决策、风险权衡
specs/<feature>/spec.md场景式需求规格
tasks.md本次变更的实现任务清单

为什么必须分开两级

项目级文档回答"我们为什么做这个产品"——稳定、长期、全局。

需求级文档回答"这次变更为什么做、怎么做"——聚焦、短期、局部。

混在一起会发生两种灾难：

  • 单次变更的实现细节污染整体架构文档，三个月后翻出来看全是噪音
  • 全局决策被埋在某个变更 PR 里，后来人根本找不到

核心原则是「谁写谁改」：

  • requirements.md / design.md 是人工思考的产物，AI 不能擅自动——否则你某次随口问句"这个功能怎么做"，AI 就把你项目的顶层设计给改了
  • devlog.md / tasks.md 的状态是AI 执行的记录，自动维护——否则你每次合并完都要手动写日志、勾任务，流程就跑不起来

这个边界划清楚了，项目的"记忆"才稳定。

三、完整项目节奏：先定全局，再拆任务，再逐个落地

很多人一上来就"我要做一个 XX"，然后就让 AI 开始写——这是跑偏的起点。真正靠谱的节奏是三段式：

第一段：全局设计（一次性完成，后续只微调）

在项目的最开始，花时间把 spec/ 下的项目级文档写清楚，顺序是：

  1. requirements.md —— 整体需求 我们要做什么产品？解决什么问题？有哪些核心功能？非功能需求（性能、合规、多端）有哪些？
  2. design.md —— 整体架构 & 模块设计 技术栈选什么？前后端怎么分？有哪些模块？模块之间的接口是什么？数据模型怎么设计？
  3. tasks.md —— 里程碑级任务清单 把整个项目拆成 10~30 个相对独立的任务，每个任务的粒度是"一个提案能做完的事情"。例如：
    • task-001-auth-module（用户认证模块）
    • task-002-h5-landing（H5 落地页）
    • task-003-admin-dashboard（管理后台）
    • ...

关键原则： 这三份文档是人工主导 + AI 辅助。你可以让 AI 帮你梳理、提问、写初稿，但最终的架构决策必须你自己拍板，写进 design.md。之后 AI 在任何时候都不能擅自修改。

这一步看似慢，但它决定了后面 80% 的稳定性。全局没定清楚之前，不要写任何一行代码。

第二段：任务到提案的映射

tasks.md 里的每一个 task，就是后续的一个 OpenSpec 提案。

spec/tasks.md (项目级)
├── task-001-auth-module       →  openspec/changes/auth-module/
├── task-002-h5-landing        →  openspec/changes/h5-landing/
├── task-003-admin-dashboard   →  openspec/changes/admin-dashboard/
└── ...

每开始一个新任务，就在 openspec/changes/ 下创建对应的变更目录，进入第三段。

第三段：单任务的七阶段开发循环

每个任务都严格走一遍七阶段工作流（下面详讲）。做完一个归档一个，spec/tasks.md 里对应的项。

为什么这种节奏能防跑偏

  • 全局锚定：AI 在写任何一个任务时，都可以参考 spec/requirements.md 和 spec/design.md 作为上位约束，不会越界
  • 任务边界清晰：每个 task 只负责一件事，提案里的改动不会污染其他模块
  • 进度可见：spec/tasks.md 是整个项目的进度条，一眼看得到做了什么、还剩什么
  • 抗失忆：即使某次开发 AI 的上下文全丢了，下次只要读 spec/ + 当前变更目录，就能无损接上

这套节奏的本质是：把"做一个项目"拆成"做 N 个小项目"，每个小项目都有完整的 spec + 完整的流程。既保留了大项目的整体性，又规避了大项目的失控风险。

四、七阶段工作流：单个任务的标准动作

上面说的"第三段：单任务的七阶段开发循环"具体长这样：

七阶段工作流

流程固化成七步，每步一条命令：

git branch → openspec scaffold → brainstorming → writing-plans → executing-plans → archive → git merge
#阶段命令产出
1创建分支git checkout -b feature/<name>独立分支，隔离这次变更
2脚手架openspec-cn new change "<name>"空变更目录，含 .openspec.yaml
3设计/superpowers:brainstormingproposal.md + design.md + specs/
4计划/superpowers:writing-plans变更目录下的 plan.md（必须落在 openspec/changes/<name>/ 内，不要散到其他位置）
5执行/superpowers:executing-plans严格按 plan.md 执行代码变更
6归档/opsx:archive变更移入 openspec/changes/archive/
7合并git merge feature/<name>合回主分支，删除特性分支

关键理解： 第 3、4、5 步是 Superpowers 的核心——把"思考→规划→执行"三件事物理上拆开。过去我们让 AI 一口气聊完需求就开始敲代码，中间过程没有物化产物；现在每一步都有产物可审查、可回滚。

这个顺序不是洁癖，是对抗 AI 失忆的物理防线： 即使某一步 AI 上下文全丢了，下一步也能从磁盘上的 spec 文档重新加载状态继续跑。

一个实战细节： 第 3 步 brainstorming 的时候，我会要求 AI 先读一遍 spec/requirements.md 和 spec/design.md，再开始讨论本次变更——这样全局约束天然就被带入了单次任务的设计里，不会出现"单个任务看似合理但违反整体架构"的情况。

五、三件套 + 项目节奏：一张全景图

把前面讲的全部串起来，整个项目从零到上线的全景是这样的：

项目全景图

这是一个可伸缩的节奏——小项目可能只有 5 个任务，大项目可能有 50 个任务，但每个任务走的流程是一样的、可预测的、可审计的。

六、写在最后：工具是形，原则是神

这套三件套的表层是工具协同，内核其实是三条原则：

  1. 把思考、规格、执行在物理上分开——别让 AI 一边想一边写
  2. 先定全局再做局部——全局 spec 是所有单次变更的上位约束
  3. 让 AI 在有边界的约束里工作——边界越清晰，AI 越靠谱

AI 的能力还在飞涨，但**"人如何管理 AI"** 这门功夫反而越来越稀缺。会写提示词的人遍地都是，能让 AI 跑通一个长期项目的人凤毛麟角——差的不是智商，是流程。

代码不再是壁垒，管住 AI 才是新的壁垒。

📦 配套模板开源

本文对应的完整 SpecCoding 模板已开源到 GitHub，可直接 Clone 或 Use this template 一键生成项目骨架：

🔗 github.com/beautifulSo…

模板内含：

  • ✅ 通用版 CLAUDE.md（含两级 Spec 体系 + 七阶段工作流的完整规则）
  • ✅ spec/ 五件套骨架（requirements / design / tasks / devlog / structure）
  • ✅ openspec 完整示例变更（proposal / design / specs / plan / tasks 五件套）
  • ✅ 七阶段工作流完整 checklist
  • ✅ .claude/ 与 .codebuddy/ 双份配置，兼容两种 IDE

如果这篇对你有启发：

  • 👍 点个赞，让更多同样被 AI "失忆"折磨的开发者看到
  • 🔖 收藏一下，七阶段工作流可以当 checklist 反复查阅
  • ⭐ GitHub 仓库 Star 一下，是对作者最大的支持，也方便你后续回来找
  • 💬 评论区聊聊——你用 AI 写代码踩过最大的坑是什么？你的解法是什么？
avatar
文章
阅读
粉丝