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