一套 Spec-First 的 AI 编程工作流

我们是袋鼠云数栈 UED 团队，致力于打造优秀的一站式数据中台产品。我们始终保持工匠精神，探索前端道路，为社区积累并传播经验价值。

本文作者：霁明

前言

这半年，伴随公司内 AI Coding 事项的推进，AI 编程工具（Cursor、Codex、Claude Code 等）在公司内部普及的较快，大家应该都有在使用 AI 辅助编程。我想大家应该有发现一件事：让 AI "直接写代码"和让 AI "先写方案再写代码"，得到的结果会不一样。

这篇文章主要是：我最近使用 AI 辅助编程的工作流是怎样的。

1. 先说个常见的情况

大家应该有遇到过这种情况：接到一个需求，图省事，直接一句话甩给 AI ------"帮我实现 xxx"，然后它"啪"地给你写了一大坨代码。

乍一看挺像样，但细看就会冒出一些问题：它可能顺手改了几个你没让它动的文件、自己脑补了一些你没交代过的边界处理、或者明明项目里已经有现成的工具函数，它非要自己再写一个。最后你花在"读它到底写了啥、再把多余的改动择出去"上的时间，未必比自己写少多少。

这不是 AI 不行，而是它在​信息不全的时候只能靠猜​。我们没把"要做什么、不要做什么"讲清楚，它就只好替我们做主。

2. Spec-First 工作流：先约定，再实现

2.1 一句话定义

做需求前，先让 AI 输出一份可被人工 review 的实现方案（spec），人工确认后再让它按方案写代码。

注意三个关键词：

• 可被 review：方案是中文说明，不是直接的代码，其他同学也能都看得懂
• 人工确认：spec 要通过确认后才能让 AI 去执行，避免在错误前提上累积工作量
• 按方案写：第二轮 prompt 把 spec 喂回去，让 AI 按既定方案写，约束自由发挥的空间

2.2 五步概览

1. 喂上下文：提示词、产品需求说明、设计稿、AGENTS.md、相关代码/文档、...
2. 出方案：让 AI 输出 spec
3. Review 改方案：重要的一步，人工主导，必须经人工确认后才可进行下一步
4. 按方案实现：让 AI 严格依据 spec 编码
5. 验收 reveiw：AI reveiw + 人工 reveiw

2.3 适用 / 不适用

场景	是否适用	备注
新功能开发	✅	最佳场景
旧模块重构	✅	spec 阶段需要先对齐边界
技术方案调研	✅	spec 就是调研报告本身
Bug 修复	⚠️	修复 bug 主要在于问题排查，改动往往是小范围的，效果有限
纯 Code Review	❌	代码审查是为了提前发现问题，没有必要

3. 完整案例

Step 1 · 给 AI 足够的上下文

AI 出方案之前，先要让它"看到"足够的信息。对于一个常规需求，我们的输入主要有：

• 用户提示词（手动书写，需要包含基本的一些描述）
• 需求说明（形式可以为截图或文本描述，需要注意脱敏）
• figma 设计稿（形式可以是截图或 MCP 读取，推荐使用 MCP）
• AGENTS.md（agent 自动读取）

Step 2 · 让 AI 出方案

上下文准备好之后，​这一轮的目标不是写代码，是写方案​。给 AI 的提示词大致是这样：

我要在菜单下，新增一个模块：
- 需求原型见上传的截图（需要手动上传）
- figma设计稿如下：
https://www.figma.com/xxx

请根据需求原型、figma设计稿和当前代码上下文输出详细实现的方案。

注意：
- 需求原型截图和figma设计稿中的顶部导航栏和侧边菜单栏是已有的，不需要实现
- 原型截图中的红色文案是业务逻辑相关描述，要重点关注
- 不清楚的地方需要和我进行确认，禁止随意推测

可以指定编程工具当前为 plan 模式（这个 claude、codex、cursor 都支持），输出实现方案。

AI 输出方案示例：

Step 3 · 人工 Review 并修正方案

我们 review 方案的时候通常会改这几类东西：

1. 需求理解偏差：AI 复述的需求和我们想的不一样，及时纠正，spec 阶段发现成本最低
2. 越界改动：AI 顺手要改一些跟当前需求无关的文件，要砍掉，保持最小范围
3. 复用顺序错：AI 想自己新写一个工具函数，但目前项目里已经有了
4. 假设没说明：AI 默默地假设了一些边界条件，要让它显式写出来或主动进行确认
5. 遗漏边缘情况：加载状态、空状态、权限、异常分支等

Review 完后让 AI 重新生成 spec，再进行确认，直到 spec 双方都认可，才进入 Step 4。

示例：

Step 4 · 让 AI 按方案实现

第二轮的提示词示例：

请严格按照上面确认的方案实现。
- 不引入方案之外的改动
- 实现完成后，请按方案的"实现步骤"逐条说明你做了什么
- 如果实现过程中发现方案有问题，先停下来告诉我，不要自行调整

或者有的 AI 工具直接提供了 spec 的 build 按钮，可以不需要额外提示词。

AI 生成代码示例：

import React, { useCallback, useEffect, useState } from 'react';

import OverviewPanel from './components/overviewPanel';
import RecordTable from './components/recordTable';
// ...省略

const ApiMonitor: React.FC = () => {
  const [overviewData, setOverviewData] = useState<IApiMonitorOverview>();
  const [overviewLoading, setOverviewLoading] = useState(false);

  // ...省略

  return (
    <div className="api-monitor">
      <OverviewPanel data={overviewData} loading={overviewLoading} />
      <RecordTable
        data={recordData}
        loading={recordLoading}
        total={total}
        current={listParams.current ?? 1}
        pageSize={listParams.size ?? DEFAULT_PAGE_SIZE}
        sortField={sortField}
        sortOrder={sortOrder}
        searchForm={
          <SearchForm
            callerOptions={callerOptions}
            onSearch={handleSearch}
            onReset={handleReset}
            />
        }
        onPageChange={handlePageChange}
        onTableChange={handleTableChange}
        />
    </div>
  );
};

export default ApiMonitor;

页面效果：

Step 5 · 对照 Spec 做代码 Review

可以让 AI 根据 spec 先 reveiw 一遍，再人工进行 reveiw，​强烈建议大家做好本地 AI + 自己人工 review 这一步​，可以大幅减少 MR reveiw 者的工作量。

对于 MR reveiw，我们主要都是在 gitlab 页面上人工 reveiw，可以使用 gitlab mcp 获取 MR 信息，然后让 AI 给出详细 reveiw 意见，本地 AI reveiw 和 gilab 上的 AI review 不太一样，本地上下文会更全，也可以使用更强的 AI 模型，reveiw 效果一般会比 gilab 上的好。经过 AI reveiw 后，仍然需要人工仔细 review ​ 一遍。

补充说明：

• 使用 gitlab mcp 可能会导致上下文比较大，可以使用内部的 gitlab-MR-code-review skill 替换
• 也可以使用 Superpowers 的 code reveiw 功能

5. 让 Spec-First 跑顺的"基础设施"

工作流要跑顺，靠的不是某次 prompt 写得好，而是底下基础设施在持续起作用。

5.1 AGENTS.md：始终在线的"团队 spec"

AGENTS.md 是仓库根的一份 Markdown 文件，被 Cursor、Codex 等工具识别后​每次会话自动加载​。它解决了一个核心问题：团队约定不需要每次都靠人工敲进 prompt，AI 默认就遵守。

我们的 AGENTS.md 分四层（按优先级从高到低）：

层级	关注点	例子
安全边界	哪些事不能做	不读 .env、不自动 git push、不主动 pnpm install
仓库边界	改动作用域	monorepo 多产品隔离、跨产品改动须确认
工程约束	技术栈 / 复用顺序	React、复用顺序 公共包 → antd → 新增
行为约定	沟通 / 验证	默认中文沟通、交付前必须跑 lint + check-types

下面是真实的一段摘录，感受一下"硬规则"的写法：

### 3.3 安全边界

- 不自动提交代码、不自动推送分支、不改写 git 历史；
  commit / push / reset / rebase / git add . 等写类操作
  仅在用户显式要求时执行。
- 不读取 .env*、应用运行期配置以及密钥/凭证类文件；
  不修改 node_modules/、构建产物、工具缓存目录。
- 不主动执行 curl / wget / ssh / scp 以及带 deploy /
  release / publish 关键字的命令。
- 非必要不新增依赖、不执行 pnpm install / add / update。
- 不主动启动 pnpm dev / pnpm start 等长驻服务。

5.2 MCP：Spec 的输入端

MCP 让 AI 能像调工具一样直接读外部系统，它们为什么重要：

以前给 AI 喂上下文，靠的是"人肉中转"------自己看 Figma、整理成一段文字再粘给它，光这一步就能耗掉小半天。MCP 把这层中转去掉了，让 AI 直接拿到你能拿到的东西。

MCP 的本质就是​让 AI 拿到你拿到的东西​。Spec-first 之所以能跑顺，很大程度上靠 MCP 把"上下文喂入"这一步的人力成本降了下来。

6. 还没解决的问题

诚实讲，这套工作流还有几个我们没解决的事，列出来一起想：

6.1 怎么知道这套真的有效？

目前我们对"AI 帮我们提了多少效率"基本靠感觉。为了让这件事可量化，我们最近在做一个 ai-coding-stats 的 skill，基于 git-ai 在 commit 上记录的元数据，能统计出 AI 代码有效采纳率、AI 代码提交留存率、AI 代码占比等指标。

个人维度已经能跑，团队维度（跨仓库聚合、可视化看板）还在跟进中。

6.2 Spec-Driven Development 的正式形态是怎样的

我目前的做法本质上是"轻量版 Spec-Driven Development（SDD）"。SDD 作为一个更系统的方法论，把 spec 的形态、版本管理、自动化测试生成都做了更完整的设计。这块我也还在学，欢迎讨论。

6.3 跨岗位的延伸

这套工作流不只前端能用，但不同岗位用起来的角度可能不一样：

• 后端：spec 阶段是不是天然适合做接口设计？
• 测试：能不能拿 spec 直接当测试用例的输入？
• 产品：spec 是不是可以为 PRD 查缺补漏？需求文档的颗粒度需不需要为"AI 友好"做调整？
• 运维：基础设施变更能不能也跑 spec-first？

7. 总结

整篇重点：

1. 让 AI 先写方案，再让它按方案写代码 ，reveiw 环节要重视
2. 用 AGENTS.md 把团队规范沉淀成 AI 默认能看到的上下文
3. 用 MCP 让 AI 拿到你想拿到的东西

最后一句话：

AI Coding 不是"AI 替我们写代码"，而是"我们用一种新的方式表达意图，由 AI 把意图翻译成代码"。

意图表达得越清楚，AI 的产出就越接近你想要的。 Spec-first 就是把意图表达清晰化的一个具体实践。

最后

欢迎关注【袋鼠云数栈 UED 团队】~

袋鼠云数栈 UED 团队持续为广大开发者分享技术成果，相继参与开源了欢迎 star

• 大数据分布式任务调度系统------Taier
• 轻量级的 Web IDE UI 框架------Molecule
• 针对大数据领域的 SQL Parser 项目------dt-sql-parser
• 袋鼠云数栈前端团队代码评审工程实践文档------code-review-practices
• 一个速度更快、配置更灵活、使用更简单的模块打包器------ko
• 一个针对 antd 的组件测试工具库------ant-design-testing