小編精選 - 技術文章翻譯 · 06月22日

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

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

> 我們是[袋鼠雲數棧 UED 團隊](https://link.juejin.cn?target=https%3A%2F%2Flink.zhihu.com%2F%3Ftarget%3Dhttps%253A%2F%2Fwww.dtstack.com%2Fued)，致力於打造優秀的一站式資料中台產品。我們始終保持工匠精神，探索前端道路，為社群累積並傳播經驗價值。本文作者：霽明

前言

這半年，伴隨公司內 AI Coding 事項的推進，AI 編程工具（Cursor、Codex、Claude Code 等）在公司內部普及得很快，大家應該都有在使用 AI 輔助編程。我想大家應該有發現一件事：讓 AI「直接寫程式」和讓 AI「先寫方案再寫程式」，得到的結果會不一樣。

這篇文章主要是：我最近使用 AI 輔助編程的工作流是怎樣的。

先說個常見的情況

大家應該有遇到過這種情況：接到一個需求，圖省事，直接一句話丟給 AI ——「幫我實作 xxx」，然後它「啪」地給你寫了一大坨程式碼。

乍看之下挺像樣，但細看就會冒出一些問題：它可能順手改了幾個你沒讓它動的檔案、自己腦補了一些你沒交代過的邊界處理，或者明明專案裡已經有現成的工具函式，它非要自己再寫一個。最後你花在「讀它到底寫了什麼、再把多餘的改動挑出去」上的時間，未必比自己寫少多少。

這不是 AI 不行，而是它在資訊不全的時候只能靠猜。我們沒把「要做什麼、不要做什麼」講清楚，它就只好替我們做主。

Spec-First 工作流：先約定，再實作

2.1 一句話定義

做需求前，先讓 AI 輸出一份可被人工 review 的實作方案（spec），人工確認後再讓它按方案寫程式。

注意三個關鍵詞：

可被 review：方案是中文說明，不是直接的程式碼，其他同學也能看得懂
人工確認：spec 要通過確認後才能讓 AI 去執行，避免在錯誤前提上累積工作量
按方案寫：第二輪 prompt 把 spec 餵回去，讓 AI 按既定方案寫，約束自由發揮的空間

2.2 五步概覽

plain 代碼解讀複製代碼1. 餵上下文：提示詞、產品需求說明、設計稿、AGENTS.md、相關程式碼/文件、...
2. 出方案：讓 AI 輸出 spec
3. Review 改方案：重要的一步，人工主導，必須經人工確認後才可進行下一步
4. 按方案實作：讓 AI 嚴格依據 spec 編碼
5. 驗收 review：AI review + 人工 review

2.3 適用 / 不適用

場景是否適用備註新功能開發✅最佳場景舊模組重構✅spec 階段需要先對齊邊界技術方案調研✅spec 就是調研報告本身 Bug 修復⚠️修復 bug 主要在於問題排查，改動往往是小範圍的，效果有限純 Code Review❌程式碼審查是為了提前發現問題，沒有必要3. 完整案例

Step 1 · 給 AI 足夠的上下文

AI 出方案之前，先要讓它「看到」足夠的資訊。對於一個常規需求，我們的輸入主要有：

使用者提示詞（手動撰寫，需要包含基本的一些描述）
需求說明（形式可以為截圖或文字描述，需要注意去識別化）
figma 設計稿（形式可以是截圖或 MCP 讀取，推薦使用 MCP）
AGENTS.md（agent 自動讀取）

Step 2 · 讓 AI 出方案

上下文準備好之後，這一輪的目標不是寫程式碼，是寫方案。給 AI 的提示詞大致是這樣：

plain 代碼解讀複製代碼我要在選單下，新增一個模組：
- 需求原型見上傳的截圖（需要手動上傳）
- figma設計稿如下：
https://www.figma.com/xxx

請根據需求原型、figma設計稿和當前程式碼上下文輸出詳細實作的方案。

注意：
- 需求原型截圖和figma設計稿中的頂部導覽列和側邊選單欄是既有的，不需要實作
- 原型截圖中的紅色文案是業務邏輯相關描述，要重點關注
- 不清楚的地方需要和我進行確認，禁止隨意推測

可以指定編程工具當前為 plan 模式（這個 claude、codex、cursor 都支援），輸出實作方案。

AI 輸出方案示例：

image (7).png

Step 3 · 人工 Review 並修正方案

我們 review 方案的時候通常會改這幾類東西：

需求理解偏差：AI 複述的需求和我們想的不一樣，及時糾正，spec 階段發現成本最低
越界改動：AI 順手要改一些跟當前需求無關的檔案，要砍掉，保持最小範圍
重複造輪子順序錯：AI 想自己新寫一個工具函式，但目前專案裡已經有了
假設沒說明：AI 默默地假設了一些邊界條件，要讓它顯式寫出來或主動進行確認
遺漏邊緣情況：載入狀態、空狀態、權限、異常分支等

Review 完後讓 AI 重新生成 spec，再進行確認，直到 spec 雙方都認可，才進入 Step 4。

示例：

image (8).png

Step 4 · 讓 AI 按方案實作

第二輪的提示詞示例：

plain 代碼解讀複製代碼請嚴格按照上面確認的方案實作。
- 不引入方案之外的改動
- 實作完成後，請按方案的「實作步驟」逐條說明你做了什麼
- 如果實作過程中發現方案有問題，先停下來告訴我，不要自行調整

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

AI 生成程式碼示例：

``tsx 代碼解讀複製代碼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;


頁面效果：

![image (9).png](http://openwrite.cn/uploads/12244/63745/dac96a6d-da76-4ba8-aaac-e56aaf96be8b.png)

### Step 5 · 對照 Spec 做程式碼 Review

可以讓 AI 根據 spec 先 review 一遍，再人工進行 review，**強烈建議大家做好本地 AI + 自己人工 review 這一步**，可以大幅減少 MR review 者的工作量。

對於 MR review，我們主要都是在 gitlab 頁面上人工 review，可以使用 gitlab mcp 取得 MR 資訊，然後讓 AI 給出詳細 review 意見，本地 AI review 和 gitlab 上的 AI review 不太一樣，本地上下文會更全，也可以使用更強的 AI 模型，review 效果一般會比 gitlab 上的好。經過 AI review 後，**仍然需要人工仔細 review ** 一遍。

補充說明：

- 使用 gitlab mcp 可能會導致上下文比較大，可以使用內部的 gitlab-MR-code-review skill 替換
- 也可以使用 Superpowers 的 code review 功能

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下面是真實的一段摘錄，感受一下「硬規則」的寫法：

markdown 代碼解讀複製代碼### 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 先寫方案，再讓它按方案寫程式碼**，**review 環節要重視**
2. **用 AGENTS.md 把團隊規範沉澱成 AI 預設能看到的上下文**
3. **用 MCP 讓 AI 拿到你想拿到的東西**

最後一句話：

AI Coding 不是「AI 幫我們寫程式碼」，而是「我們用一種新的方式表達意圖，由 AI 把意圖翻譯成程式碼」。**意圖表達得越清楚，AI 的產出就越接近你想要的。** Spec-first 就是把意圖表達清晰化的一個具體實踐。

最後
--

歡迎關注【袋鼠雲數棧 UED 團隊】~ 袋鼠雲數棧 UED 團隊持續為廣大開發者分享技術成果，相繼參與開源了歡迎 star

- **[大數據分散式任務排程系統——Taier](https://link.juejin.cn?target=https%3A%2F%2Flink.zhihu.com%2F%3Ftarget%3Dhttps%253A%2F%2Fdtstack.github.io%2FTaier%2F)**
- **[輕量級的 Web IDE UI 框架——Molecule](https://link.juejin.cn?target=https%3A%2F%2Flink.zhihu.com%2F%3Ftarget%3Dhttps%253A%2F%2Fdtstack.github.io%2Fmolecule%2F)**
- **[針對大數據領域的 SQL Parser 專案——dt-sql-parser](https://link.juejin.cn?target=https%3A%2F%2Flink.zhihu.com%2F%3Ftarget%3Dhttps%253A%2F%2Fdtstack.github.io%2Fmonaco-sql-languages%2F)**
- **[袋鼠雲數棧前端團隊程式碼審查工程實踐文件——code-review-practices](https://link.juejin.cn?target=https%3A%2F%2Flink.zhihu.com%2F%3Ftarget%3Dhttps%253A%2F%2Fgithub.com%2FDTStack%2Fcode-review-practices)**
- **[一個速度更快、設定更靈活、使用更簡單的模組打包器——ko](https://link.juejin.cn?target=https%3A%2F%2Flink.zhihu.com%2F%3Ftarget%3Dhttps%253A%2F%2Fgithub.com%2FDTStack%2Fko)**
- **[一個針對 antd 的元件測試工具庫——ant-design-testing](https://link.juejin.cn?target=https%3A%2F%2Flink.zhihu.com%2F%3Ftarget%3Dhttps%253A%2F%2Fgithub.com%2FDTStack%2Fant-design-testing)**

---

原文出處：https://juejin.cn/post/7652581847889330202