在 AI 編程浪潮里不少團隊已經(jīng)從“編輯器加插件”的輕度輔助階段進入到了“AI Agent 自動寫代碼”的深度協(xié)作階段。最近我把 Codex 和 Spec Coding 結(jié)合起來跑完整的前后端迭代時發(fā)現(xiàn)用“規(guī)格先行、AI 落碼、人工把關(guān)”的方式來推進單人維護一套企業(yè)級全棧項目是完全可行的。本文會完整拆解這套流程從 Codex 環(huán)境配置、Spec 文檔怎么寫到全棧項目實戰(zhàn)、常見報錯排查最后給出一套能復(fù)制到團隊協(xié)作中的工程規(guī)范。1. 為什么 Codex Spec Coding 值得關(guān)注1.1 從“自動補全”到“AI Agent”的轉(zhuǎn)變過去兩年AI 編程工具的形態(tài)發(fā)生了明顯變化。早期的輔助工具以“自動補全”為主模型根據(jù)上下文預(yù)測下一段代碼適合快速寫樣板代碼但面對跨文件、多模塊的系統(tǒng)級任務(wù)往往力不從心。而 Codex 這類 AI Agent 的工作方式不再是“補全一行代碼”而是理解你給出的需求、瀏覽項目結(jié)構(gòu)、多次調(diào)用工具讀寫文件最終生成一組可運行的改動。這種轉(zhuǎn)變讓“一個人借助 AI 完成從前端到后端的整套開發(fā)”成為可能。不過工具能力變強不等于使用者就能坐享其成。我觀察到一個常見現(xiàn)象很多人拿到 Codex 之后直接對它說“幫我做一個任務(wù)管理系統(tǒng)”“幫我寫一個商城”。Codex 確實能生成代碼但生成出來的東西往往非常“通用”字段命名、接口設(shè)計、組件拆分都和你心里的預(yù)期對不上。這個時候Spec Coding 的價值就體現(xiàn)出來了。1.2 Spec Coding 是解決 AI 寫碼不確定性的關(guān)鍵可以這樣理解直接讓 AI“做一個系統(tǒng)”相當于讓一個外包開發(fā)者在沒有需求文檔的情況下開始敲代碼他當然會自由發(fā)揮。Spec Coding 的思路則是先把需求翻譯成一份結(jié)構(gòu)化的規(guī)格說明Specification包括功能列表、輸入輸出約束、異常流程、技術(shù)選型等。AI 根據(jù)這份 Spec 去實現(xiàn)相當于“拿著圖紙施工”而不是“聽口頭描述自由發(fā)揮”。Spec 的價值體現(xiàn)在三個層面第一對 AI 來說Spec 減少了猜測空間生成的代碼更穩(wěn)定。同樣一個“創(chuàng)建任務(wù)”的功能有了字段長度限制和錯誤響應(yīng)定義AI 會主動生成校驗邏輯而不是把空字符串也存進數(shù)據(jù)庫。第二對人來說Spec 可以評審、可以討論。需求變更時先改 Spec 再改代碼責任邊界清晰。你甚至可以拿著 Spec 去和產(chǎn)品經(jīng)理確認而不是等代碼寫完再返工。第三對團隊來說Spec 本身是文檔資產(chǎn)。后來人接手項目時不需要逐行讀代碼才能理解業(yè)務(wù)先看 Spec 就能快速建立全局認知。1.3 這篇文章適合誰讀如果你是正在做前端或者全棧開發(fā)的工程師已經(jīng)接觸過 AI 編程工具但覺得“AI 生成的東西不靠譜”或者想完整了解 Codex 到底怎么用、Spec Coding 到底是什么這篇文章會比較合適。讀完你會有能力自己搭一套“規(guī)格驅(qū)動 AI 輔助”的輕量開發(fā)流程在個人項目或小團隊里直接落地。文章涉及到的基礎(chǔ)環(huán)境以 Node.js 和常見前端技術(shù)棧為主即使你之前主要寫 Vue把示例中的 React 部分替換成 Vue 也同樣適用核心方法論是不變的。2. 環(huán)境準備把 Codex 跑起來2.1 安裝前置條件在安裝 Codex 之前需要先確認本機具備幾個基礎(chǔ)環(huán)境。Codex CLI 本身需要 Node.js 運行環(huán)境建議使用 Node.js 18 及以上版本因為較新的 CLI 工具通常依賴較新的 API 特性。包管理器可以使用 npm 或 pnpm看個人習慣即可。除了 Node.js 環(huán)境還需要一個 Codex 賬號用于調(diào)用模型服務(wù)。安裝和登錄的具體方式可能會隨著版本迭代發(fā)生變化所以下面示例的重點是操作思路而不是一份長期不變的命令清單。如果你在操作時發(fā)現(xiàn)命令與官方文檔不一致請始終以官方最新文檔為準。2.2 Codex CLI 安裝與登錄目前 Codex CLI 比較常見的安裝方式是通過 npm 全局安裝。打開終端執(zhí)行npm install -g openai/codex安裝完成后執(zhí)行下面的命令確認版本號codex --version如果能打印出版本號說明安裝成功。接下來需要登錄賬號。Codex CLI 支持兩種認證方式一種是直接在命令行中完成登錄授權(quán)另一種是配置 API Key 環(huán)境變量。以登錄授權(quán)為例codex login如果你的項目環(huán)境不允許交互式登錄也可以使用 API Key。在終端中設(shè)置環(huán)境變量export OPENAI_API_KEY你的 API Key這里要特別提醒登錄態(tài)和 API Key 都屬于敏感信息。不要把自己的 API Key 直接提交到 Git 倉庫也不要在公開的聊天平臺、博客帖子里粘貼密鑰。建議通過系統(tǒng)的密鑰管理工具或者本地的.env文件保存并且把.env加入.gitignore。2.3 驗證環(huán)境是否可用安裝完成之后可以在一個空目錄里快速跑一個冒煙測試。新建目錄并進入mkdir codex-smoke-test cd codex-smoke-test然后啟動 Codex給它一個簡單的指令codex 創(chuàng)建一個 hello.js輸出 Hello Codex如果一切正常Codex 會生成hello.js。用 Node 運行node hello.js # 輸出Hello Codex這一步的關(guān)鍵是確認 CLI 能正常調(diào)用模型接口。如果這里出現(xiàn)網(wǎng)絡(luò)連接、認證等問題后續(xù)所有操作都會受到影響所以建議先把冒煙測試跑通再進入正式項目。2.4 IDE 插件與 CLI 路徑配置很多開發(fā)者在日常工作流中不會直接用命令行而是希望在 VS Code 等 IDE 中通過插件來使用 Codex。這一類 IDE 插件通常需要定位到 Codex CLI 的可執(zhí)行文件。如果插件提示unable to locate the codex cli binary意思就是它沒有在系統(tǒng) PATH 中找到 Codex 命令。解決思路是先在終端確認 Codex 的安裝位置。在 macOS/Linux 中執(zhí)行which codex在 Windows 中可以執(zhí)行where codex將輸出結(jié)果的路徑填寫到 IDE 插件的設(shè)置項里。如果沒有手動設(shè)置項還可以檢查系統(tǒng) PATH 是否包含 npm 全局安裝目錄。這個報錯出現(xiàn)頻率比較高第 5 節(jié)會單獨展開講解排查清單。3. Spec Coding 核心方法論Spec 怎么寫3.1 Spec 是什么一句話說清楚SpecSpecification本質(zhì)上是一份“給 AI 看的結(jié)構(gòu)化需求文檔”。它和傳統(tǒng) PRD 的區(qū)別在于PRD 通常是給人閱讀的語言可以模糊語境可以共享而 Spec 要盡量精確到讓 AI 不需要再次向你確認。你可以把 Spec 理解成一份“機器可理解程度更高”的需求規(guī)格里面包含了功能定義、數(shù)據(jù)結(jié)構(gòu)、接口約束、邊界條件等內(nèi)容。3.2 一份合格 Spec 的四個要素結(jié)合我近期的使用經(jīng)驗一份能當“施工圖”的 Spec 通常包含四個要素。第一個是功能描述。每個功能要說明它是做什么的用一句話寫清楚。比如“創(chuàng)建任務(wù)接收任務(wù)標題生成一條完整的任務(wù)記錄”。功能描述不需要太長但必須沒有歧義。第二個是輸入輸出約束。如果功能涉及接口或者方法需要明確輸入?yún)?shù)的類型、是否必填、字段長度范圍以及輸出結(jié)果的格式。AI 天生擅長編程但如果你不告訴它字段長度是 1 到 100它可能不會主動加校驗。第三個是邊界與異常。包括輸入為空、長度超限、數(shù)據(jù)不存在、重復(fù)提交等情況應(yīng)該怎么處理。實際開發(fā)中這些邊界往往決定代碼質(zhì)量。Spec 里提前寫出了異常分支AI 就能自動生成對應(yīng)的容錯邏輯。第四個是技術(shù)約束。比如項目使用 React 還是 Vue、后端使用 Express 還是 Fastify、數(shù)據(jù)存儲用 JSON 文件還是 SQLite、是否要求 TypeScript。這些約束不寫清楚AI 會按自己的偏好選擇技術(shù)棧最后生成的代碼會跟項目現(xiàn)有可能完全不匹配。寫 Spec 時不要求長篇大論而是要像寫用例一樣一條一條列清楚。AI 上下文窗口有限Spec 越精煉模型對重點內(nèi)容的注意力越集中。3.3 一份任務(wù)管理模塊的 Spec 示例下面用一份“任務(wù)管理系統(tǒng)”的 Spec 來演示具體長什么樣。這個項目也是第 4 節(jié)實戰(zhàn)部分的基礎(chǔ)。# 任務(wù)管理系統(tǒng) Spec ## 1. 功能列表 - 創(chuàng)建任務(wù)用戶輸入標題系統(tǒng)創(chuàng)建任務(wù)并返回任務(wù)對象。 - 查看任務(wù)列表系統(tǒng)返回全部任務(wù)按創(chuàng)建時間倒序排列。 - 完成任務(wù)用戶指定任務(wù) ID系統(tǒng)將任務(wù)狀態(tài)改為 completed。 - 刪除任務(wù)用戶指定任務(wù) ID系統(tǒng)刪除任務(wù)并返回 204。 ## 2. 數(shù)據(jù)模型 Task 對象字段 - id: string, 必填, 唯一 - title: string, 必填, 長度 1-100 - status: string, 枚舉 pending | completed, 默認 pending - createdAt: string, ISO 時間字符串, 服務(wù)端生成 ## 3. API 接口 ### POST /api/tasks 參數(shù){ title: string } 返回201 { id, title, status, createdAt } 異常 - title 為空400 { error: title is required } - title 長度超過 100400 { error: title too long } ### GET /api/tasks 返回200 Task[] ### PATCH /api/tasks/:id/complete 返回200 Task 異常 - 任務(wù)不存在404 { error: task not found } ### DELETE /api/tasks/:id 返回204 異常 - 任務(wù)不存在404 { error: task not found } ## 4. 技術(shù)約束 - 后端Node.js Express - 前端React Vite - 數(shù)據(jù)持久化使用本地 JSON 文件服務(wù)啟動時讀取寫操作后同步寫入 - 不使用數(shù)據(jù)庫不引入 TypeScript這份 Spec 不長但已經(jīng)覆蓋了 AI 生成代碼時最容易出分歧的“接口契約”和“字段約束”。后面實戰(zhàn)中你會看到把這份 Spec 喂給 Codex 之后它能比較準確地生成對應(yīng)的前后端代碼。4. 全棧實戰(zhàn)用 Codex 跑通“任務(wù)管理系統(tǒng)”4.1 項目需求與整體結(jié)構(gòu)現(xiàn)在我們把第 3 節(jié)那份 Spec 變成一個真實可運行的項目。項目名稱暫定為codex-task-app整體分為server和client兩個目錄server是 Express 后端服務(wù)負責提供任務(wù)管理 APIclient是 React 前端應(yīng)用負責頁面展示和用戶交互。這樣的結(jié)構(gòu)在企業(yè)項目里很常見前后端通過 HTTP 接口聯(lián)調(diào)。最終目錄結(jié)構(gòu)如下codex-task-app/ ├── server/ │ ├── data/ │ │ └── tasks.json │ ├── app.js │ └── package.json └── client/ ├── src/ │ ├── App.jsx │ ├── api.js │ └── main.jsx ├── index.html ├── package.json └── vite.config.js4.2 用 Codex 生成后端接口把 Spec 中關(guān)于后端和 API 的部分直接作為提示詞交給 Codex。我在實際使用時會給 Codex 這樣一段指令請按照下面的 Spec 實現(xiàn)一個 Express 后端代碼放在 server 目錄下。要求使用 CommonJS 模塊規(guī)范不使用數(shù)據(jù)庫數(shù)據(jù)寫入 server/data/tasks.json。需要允許來自 http://localhost:5173 的跨域請求。Spec 內(nèi)容如下 [這里粘貼第 3.3 節(jié) Spec 的全部內(nèi)容]Codex 生成的核心代碼思路如下。首先是server/app.js// 文件路徑server/app.js const express require(express); const fs require(fs); const path require(path); const crypto require(crypto); const app express(); const PORT 3001; const DATA_FILE path.join(__dirname, data, tasks.json); app.use(express.json()); // 簡單的 CORS 中間件方便前端開發(fā)服務(wù)器跨域訪問 app.use((req, res, next) { res.setHeader(Access-Control-Allow-Origin, *); res.setHeader(Access-Control-Allow-Methods, GET,POST,PATCH,DELETE,OPTIONS); res.setHeader(Access-Control-Allow-Headers, Content-Type); if (req.method OPTIONS) { return res.status(204).end(); } next(); }); function readTasks() { if (!fs.existsSync(DATA_FILE)) { return []; } const content fs.readFileSync(DATA_FILE, utf-8); return JSON.parse(content || []); } function writeTasks(tasks) { fs.mkdirSync(path.dirname(DATA_FILE), { recursive: true }); fs.writeFileSync(DATA_FILE, JSON.stringify(tasks, null, 2), utf-8); } function validateTitle(title) { if (!title) { return title is required; } if (title.length 100) { return title too long; } return null; } // 創(chuàng)建任務(wù) app.post(/api/tasks, (req, res) { const { title } req.body || {}; const error validateTitle(title); if (error) { return res.status(400).json({ error }); } const tasks readTasks(); const task { id: crypto.randomUUID(), title, status: pending, createdAt: new Date().toISOString(), }; tasks.push(task); writeTasks(tasks); res.status(201).json(task); }); // 獲取任務(wù)列表 app.get(/api/tasks, (req, res) { const tasks readTasks(); tasks.sort((a, b) new Date(b.createdAt) - new Date(a.createdAt)); res.json(tasks); }); // 完成任務(wù) app.patch(/api/tasks/:id/complete, (req, res) { const tasks readTasks();