夜雨聆风
AI编码工程化实践(1):搭建AI开发工作流
用 AI 写代码的人越来越多，但真把它放进生产级项目里，三个老问题反复出现：
-
需求理解偏差。你让 AI 加个功能，它写出来后发现跟你想的不是一回事，返工。
-
执行过程黑盒。AI 写了什么、怎么写的、测了没有，你很难把控。
-
没有真实环境验证。代码看起来对了，但页面渲染、接口连通、部署后表现，AI 自己验证不了。
说到底，Vibe Coding 是”提示即祈祷”（prompt-and-pray），你把需求扔给 AI，然后祈祷它别出错，显然这样是无法保证产出质量的。最近行业里形成了一个更成熟的概念：Agentic Engineering（智能体工程），核心思路是——人负责定义目标、约束条件和质量标准，AI 作为自主智能体在结构化流程中执行规划、编码、测试和迭代，每个关键节点都有人工审核。它不是让 AI 随意发挥，而是把 AI 的能力嵌入到一套有纪律的工程体系里。
最近一周，我用 Claude Code + 自定义 Skill/Command/MCP 体系 做了一次实践：把从需求到发布的所有环节串到一个终端会话里。AI 全程保持对当前任务的理解，在预设的流程框架内自主执行；我只需要在关键节点做决策——审批计划、确认部署、审查代码。回过头看，这套东西就是 Agentic Engineering 在开发场景的一个落地样本。
AI落地到生产环境中时工程体系才是核心资产，而不是某个模型或 prompt。Skill 每天在更新，大模型每天在进化，但工程体系的价值是需要持续积累的。
2. 实践方案
对比了市面上主流的工具后，我选用了Claude Code + OpenSpec + Superpowers + gstack的方案。OpenSpec 管需求，Superpowers 管写代码，gstack 管验证和交付。
| 工具 | 定位 | 解决什么问题 |
|---|---|---|
| OpenSpec | 规范驱动开发（需求层） | 让 AI 和人在文字层面先达成共识，减少返工 |
| Superpowers | AI 编码代理方法论（执行层） | 把 AI 写代码的过程标准化、可观测、可审查 |
| gstack | 执行工具封装（验证层） | 浏览器、QA、发布、监控，一键调用 |
2.1 为什么选择这3个工具
-
OpenSpec：轻量规范层，锁定意图，管理变更
OpenSpec 是做一层轻量的规范管理——通过 /opsx:propose（创建提案）→ /opsx:apply（执行）→ /opsx:archive（归档）的流程，让规范成为活文档。
核心是变更驱动的工作流。每个功能变更是独立目录，包含提案、设计、任务和规范增量（Spec Delta）。
跟Spec-Kit比，没有严格的阶段门，Spec-Kit 太”重”，落地成本高，而OpenSpec 可以随时调整提案，灵活性更高，更适用于快速迭代的场景。
-
Superpowers：不是规范驱动，而是通过一组可组合的”技能”来约束代理行为。是技能驱动的工作流，Agent 检测到适用场景就通过 Hook 自动激活相关技能，内嵌代码工程方法论（TDD、调试、审查等），是”怎么写好代码”的纪律框架。
核心技能包括：test-driven-development（强制 TDD）、systematic-debugging（系统化调试）、brainstorming（苏格拉底式设计细化）、subagent-driven-development（子代理并发执行）等。
-
gstack：是一套 Claude Code 技能包（23+ 个角色化技能），将单个 AI 助手转变为一个虚拟工程团队。通过角色化和阶段化组织，提供从产品思考到部署监控的全栈工具链。它的核心价值在于：
-
a. 覆盖 Superpowers 完全没有的领域（浏览器测试、安全审计、部署运维） -
b. 角色化审查提供多维度视角 -
c. 自动化交付链大幅减少手动操作
有个细节值得说：gstack 的/plan-ceo-review和 Superpowers 的brainstorming看起来都做”需求分析”，但视角完全不同。
从源码看，Superpowers 的 brainstorming（来源：skills/brainstorming/SKILL.md）是一个结构化的需求精炼流程：先探索项目上下文 → 一次问一个问题 → 提出 2-3 种方案 → 分段展示设计让用户审批 → 写设计文档 → 转入 writing-plans。它关注的是这个功能怎么实现。
gstack 的 /office-hours（来源：docs/skills.md的 office-hours 章节）是一个产品方向诊断：六个强制问题重构产品认知、挑战你的前提假设、生成实施替代方案。它关注的是这个产品值不值得做。
一个是工程视角的怎么做，一个是商业视角的做不做。视角不同，不冲突，反而互补。
2.2 这三个工具分别做什么
OpenSpec：把需求写成机器可理解的规范
OpenSpec 的核心是双文件夹模型：
openspec/ specs/ # 当前系统的事实来源（规范文件） changes/ # 每次变更的完整提案
每份变更包含三个文件：
-
proposal.md—— 为什么要做（背景、目标、成功标准） -
design.md—— 技术方案（架构决策、接口设计、数据流） -
tasks.md—— 实施清单（可执行的具体任务）
这三个文件本身就是 AI 和人之间的”契约”。AI 在动手写代码之前，先在这三份文档里和你对齐。据实测对比，使用 OpenSpec 后相同需求下的 Token 消耗降低 30%-50%，返工率下降 60% 以上。
Superpowers：强制流程约束 AI 的执行过程
Superpowers 不只是一个插件，而是一套不可跳过的 7 步工作流：
| 步骤 | 做什么 | 为什么重要 |
|---|---|---|
| 1. brainstorming | 苏格拉底式提问，澄清任务细节 | 在写代码前暴露隐藏假设 |
| 2. git worktree | 创建隔离分支，保护主分支 | 避免污染主干 |
| 3. writing-plans | 拆解为 2-5 分钟可执行小任务 | 把大需求拆到 AI 能稳定完成的粒度 |
| 4. subagent 执行 | 每个任务派独立子代理 | 隔离上下文，减少干扰 |
| 5. TDD 循环 | RED → GREEN → REFACTOR | 每段代码都有测试覆盖 |
| 6. 代码审查 | 两阶段：规范合规 + 代码质量 | 人在关键环节把关 |
| 7. 分支收尾 | 验证测试、合并决策 | 干净收尾，不留债务 |
关键是每一步都不可跳过。这不是官僚主义，而是生产环境的底线。
gstack：把开发者每天用的工具封装成一键命令
gstack 不做决策，只帮你干活：
-
/browse—— 浏览器截图、元素检查、用户流验证 -
/qa—— 端到端 QA 测试 -
/ship—— 发版流程（检测 base、跑测试、review diff、写 CHANGELOG） -
/land-and-deploy—— 合并 PR、等 CI、验证生产环境 -
/canary—— 上线后监控错误和性能回归 -
/careful—— 危险命令拦截（rm -rf、DROP TABLE、force-push 等）
没有 gstack，Superpowers 写完了代码没法验证”页面渲染对不对”。这是绝大多数”我以为修好了”的根源。
2.3 三者如何配合：数据流与分工边界
需求输入│▼┌──────────────┐ proposal.md│ OpenSpec │ ──→ design.md│ (需求对齐) │ tasks.md└──────────────┘│▼ tasks.md┌──────────────┐ brainstorming → worktree → 小任务│ Superpowers │ ──→ subagent 执行 → TDD → 代码审查│ (规范执行) │ 分支收尾└──────────────┘│▼ 代码产出┌──────────────┐ /browse 截图验证│ gstack │ ──→ /qa 端到端测试│ (验证交付) │ /ship + /land-and-deploy + /canary└──────────────┘│▼生产上线
分工边界：
-
OpenSpec 只产出规范文档，不写代码。
-
Superpowers 只按规范执行编码流程，不直接操作浏览器或部署。
-
gstack 只做验证和交付动作，不参与需求分析或架构决策。
三者之间通过文件和命令传递信息，不是通过共享内存或隐式状态。
3. 完整工作流：从需求到上线
阶段 1：需求对齐（OpenSpec）
-
在
openspec/changes/下新建变更目录 -
写
proposal.md：为什么要做、不做会怎样、成功标准是什么 -
写
design.md：技术方案、接口契约、数据模型 -
写
tasks.md：拆成具体可执行的任务列表
阶段 2：编码执行（Superpowers）
-
以
tasks.md为输入，启动 brainstorming -
AI 用苏格拉底式提问澄清模糊点（你确认要改这个接口吗？影响范围想清楚了吗？）
-
创建 git worktree 隔离分支
-
拆解为 2-5 分钟粒度的小任务
-
子代理并行/串行执行（按依赖关系判断）
-
每个任务走 TDD：先写测试，再写实现，最后重构
-
两阶段代码审查：先过规范合规检查，再过代码质量审查
阶段 3：验证交付（gstack）
-
/browse—— 打开页面，截图验证渲染效果 -
/qa—— 跑端到端测试，确认核心链路正常 -
/ship—— 发版：合并 base、跑测试、review diff、写 CHANGELOG -
/land-and-deploy—— 合并 PR、等 CI、验证生产 -
/canary—— 监控上线后的错误率和性能指标
关键原则：没有测试/截图/QA 报告，不算完成。
4. 安装与初始化
4.1 OpenSpec安装
# 全局安装 OpenSpecnpm install -g @fission-ai/openspec@latest#验证安装openspec --version# 查看可用命令openspec --help
gstack 不在插件市场，直接从仓库安装：# 克隆 gstack 到 Claude Code skills 目录并运行安装脚本git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git \~/.claude/skills/gstackgstack 支持无前缀模式（/qa）和前缀模式（/gstack-qa）。如果你同时装了其他也有/review 命令的插件，建议用前缀模式，彻底避免命名冲突。：cd .claude/skills/gstack/ && ./setup --prefixsetup 脚本会把 28 个 skill 符号链接到 `~/.claude/skills/` 顶层。之后你在对话里用 `/gstack-browse`、`/gstack-qa`、`/gstack-ship` 就能触发。setup 依赖 bun，没装的话先装：curl -fsSL https://bun.sh/install | bash安装完 bun 必须重启终端，否则系统识别不到新安装的命令。验证安装是否成功在 Claude Code 中输入/gstack**注意**：macOS 上 bun 编译的单文件二进制可能因代码签名问题被系统 kill。如果遇到这种情况，将 `browse/dist/browse` 替换为 wrapper 脚本，改为通过 `bun run browse/src/cli.ts` 执行即可。
/plugin install superpowers@claude-plugins-official 要让这套工作流真正跑起来，需要在 ~/.claude/CLAUDE.md 中写明裁决规则，告诉 Claude 遇到什么情况该走哪个 skill。
## 1. Claude Code 配置：OpenSpec + superpowers + gstack主干由三个插件组成：- **OpenSpec** —— 规范与需求层（proposal / design / tasks）- **superpowers** —— 思考与流程层（plan / brainstorm / debug / TDD / review / verify）- **gstack** —— 执行与外部世界层（browser / QA / ship / deploy / canary / 护栏）类比：OpenSpec 是蓝图，superpowers 是大脑，gstack 是手脚。### 核心原则1. **规范先行**：任何需求变更必须先过 OpenSpec，调用/opsx:propose，产出 proposal.md + design.md + tasks.md，再动手写代码。2. **流程归 superpowers**：brainstorm、plan、debug、TDD、verify、code review。默认走 superpowers，不走 OMC / feature-dev 等同名第三方 skill。3. **执行归 gstack**：浏览器、QA、ship、deploy、canary、retro 走 gstack。4. **独立 reviewer 通道**：verification 和 code-review 分两个 pass，不能在同一上下文里合并。5. **证据优先**：没有测试/截图/QA 报告不算完成。6. **歧义先 brainstorm**：任何创造性工作前先调用 brainstorming。7. **最短路径优先**：能用一个 skill 解决的，不升级为完整闭环。### OpenSpec 规范工作流#### 双文件夹模型```openspec/specs/ # 当前系统的事实来源（规范文件）changes/ # 每次变更的完整提案```#### 每份变更必须包含三个文件`proposal.md` —— 为什么要做（背景、目标、成功标准、不做会怎样）`design.md` —— 技术方案（架构决策、接口设计、数据流、依赖关系）`tasks.md` —— 实施清单（可执行的具体任务，作为 Superpowers 的输入）#### 职责边界OpenSpec **只产出规范文档，不写代码**。Superpowers **只按 tasks.md 执行编码流程**，不修改 OpenSpec 规范。gstack **只做验证和交付动作**，不参与需求分析或架构决策。三者之间通过**文件和命令**传递信息，不通过共享内存或隐式状态。#### 规范与执行的衔接1. 需求输入 → OpenSpec 输出 `tasks.md`2. `tasks.md` 作为 Superpowers 的输入启动 brainstorming3. 编码执行过程中如发现规范遗漏或错误，**回退到 OpenSpec 更新 design.md / tasks.md**，再继续执行### 任务分流#### 只读任务分析、解释、架构说明、代码阅读 —— 直接处理。真实 bug 排查但尚未修改 —— 用 systematic-debugging。#### 轻量任务单文件或小范围修改、明确 bug 修复、配置/文案调整、小测试补充。跳过完整 brainstorming / writing-plans / worktrees / 重 review 链。直接实现 + 定向验证 + 必要时 /browse 看效果。#### 中任务多文件但边界清晰，新功能或明确的重构。OpenSpec /opsx:propose（必须首先调用）→ 简短 brainstorming + 短 writing-plans + 实现 + /browse 或 /qa + verification。#### 大任务跨模块、共享逻辑、新架构、公共 API 变更。完整闭环：OpenSpec /opsx:propose（必须首先调用）→ brainstorming → writing-plans → /plan-*-review→ executing-plans + worktrees + TDD → /qa → verification→ code-review → finishing-branch → /ship → /land-and-deploy → /canary### 浏览器规则/browse 是唯一的浏览器入口。禁止使用 mcp__claude-in-chrome__*和 mcp__computer-use__* 来操作浏览器。### Subagent 策略一定派子代理：1. 用户明说 "并行 / parallel / dispatch"2. 2-4 个边界清晰、独立验证、无共享状态的子任务3. 纯只读的多目标研究一定不派：1. 任务有顺序依赖2. 多个子任务改同一文件 / contract / shared types3. package.json / lockfile / 根配置 / CI / schema / 总入口 默认串行4. 单一目标的 bug 修复5. 根因未明的调试### 安全护栏1. rm -rf / DROP TABLE / force-push / git reset --hard / kubectl delete必须先过 /careful 或 /guard2. 调试敏感模块时用 /freeze 限定可改范围3. /ship 和 /land-and-deploy 必须用户明确确认4. 密钥/凭证/API Key 不得硬编码5. 数据库访问用参数化查询6. 不用不可信输入拼接 shell 命令或 SQL### Change Delivery Gate声明完成、准备 commit / push / PR 之前必须满足：1. 已完成相关验证，并如实报告结果2. 已过对应质量门禁（review / verification）3. 关键验证无法执行时必须明确说明原因4. 禁止虚构命令输出5. 没有验证证据，不得声称"通过" / "完成"### 不要重复造轮子1. 需求分析先用/opsx:propose、proposal / design / tasks 文档编写2. 规范评审、技术方案确认3. tasks.md 作为 Superpowers 的唯一输入只走 superpowers：1. plan / brainstorming / writing-plans / executing-plans2. TDD / debugging / verification3. code review / subagent / worktrees / 分支收尾只走 gstack：1. 浏览器、QA、ship、deploy、canary、retro、document-release2. 多视角 plan review (CEO / Eng / Design)3. 危险命令护栏 / freeze 沙箱4. 安全审计 / design-consultation / investigate
6. 实战案例
|
|
|
|
|
|
|
|
|