1. 從“先寫清楚”到“讓AI干活”Spec-Kit、SDD與OpenSpec的殊途同歸最近在跟幾個技術(shù)團(tuán)隊(duì)交流時發(fā)現(xiàn)一個挺有意思的現(xiàn)象大家聊到如何用AI來輔助開發(fā)尤其是生成代碼時總會提到幾個聽起來很相似但又不太一樣的詞——Spec-Kit、SDD、OpenSpec。乍一聽感覺都是些新潮的“AI編程”方法論或工具好像很高深。但當(dāng)你真正沉下心來去翻看它們的文檔、試用它們的工具甚至自己踩過幾個坑之后會發(fā)現(xiàn)一個非常樸素卻又無比核心的共同點(diǎn)它們都強(qiáng)調(diào)在讓AI動手之前你得先把自己的想法“寫清楚”。這聽起來像一句廢話對吧誰不知道需求要明確但恰恰是這句“廢話”在AI時代被賦予了全新的、極其關(guān)鍵的意義。在過去我們寫需求文檔、設(shè)計(jì)稿主要是給人看的是團(tuán)隊(duì)內(nèi)部溝通的橋梁。人是有理解力、有上下文、能腦補(bǔ)的。但AI沒有。你給AI一個模糊的指令比如“幫我寫個登錄功能”它可能給你生成一個最簡單的表單也可能給你一套包含OAuth2、JWT、雙因素認(rèn)證的復(fù)雜系統(tǒng)結(jié)果完全不可控。Spec-Kit、SDD、OpenSpec這三者本質(zhì)上都是在解決這個“如何對AI說清楚人話”的問題。它們不是要取代程序員而是試圖建立一套更高效、更精確的“人機(jī)協(xié)作協(xié)議”。今天我就結(jié)合自己這段時間的摸索和實(shí)踐來聊聊這三者到底有什么區(qū)別以及為什么說它們的核心思想其實(shí)一脈相承。你會發(fā)現(xiàn)理解了這一點(diǎn)無論是選擇工具還是制定團(tuán)隊(duì)流程都會清晰很多。2. Spec-Kit面向AI的“結(jié)構(gòu)化需求清單”我們先從Spec-Kit說起。這個概念相對更“民間”一些沒有特別官方的定義更像是一種在實(shí)踐中總結(jié)出來的模式。你可以把它理解為一份專門寫給AI看的、高度結(jié)構(gòu)化的“需求清單”或“規(guī)格說明書”。2.1 Spec-Kit的核心構(gòu)成不止于功能描述一個典型的Spec-Kit遠(yuǎn)不止是羅列“要做什么功能”。它會強(qiáng)制你思考并明確以下幾個維度這些恰恰是AI生成代碼時最需要的上下文輸入與輸出契約這是最基礎(chǔ)的部分。你需要明確函數(shù)、接口或模塊的輸入?yún)?shù)名稱、類型、格式、約束、是否可選和輸出結(jié)果數(shù)據(jù)結(jié)構(gòu)、成功/失敗狀態(tài)碼、可能的異常。例如不是簡單說“驗(yàn)證用戶”而是寫成“輸入username(字符串非空最大長度50)password(字符串非空最小長度8需包含大小寫字母和數(shù)字)輸出{“success”: boolean, “token”: string|null, “message”: string}”。業(yè)務(wù)規(guī)則與邊界條件這是最容易產(chǎn)生歧義的地方。你需要把那些“理所當(dāng)然”的業(yè)務(wù)邏輯顯式地寫出來。比如“用戶連續(xù)登錄失敗5次后賬戶鎖定30分鐘”、“商品庫存為0時前端顯示‘售罄’且按鈕置灰”、“只有訂單狀態(tài)為‘待支付’時才能取消”。這些規(guī)則如果不寫清楚AI生成的代碼很可能遺漏關(guān)鍵校驗(yàn)。非功能性要求性能、安全性、兼容性等。例如“API響應(yīng)時間P95需小于200ms”、“密碼需在傳輸和存儲時加密”、“生成的代碼需兼容Python 3.8”。這些要求會直接影響AI對庫的選擇和代碼的實(shí)現(xiàn)方式。示例與反例提供1-2個正確的輸入輸出示例以及1-2個典型的錯誤輸入示例。這對于AI理解你的意圖有奇效。這相當(dāng)于給AI做了“Few-shot Learning”小樣本學(xué)習(xí)。2.2 實(shí)踐中的Spec-Kit一個用戶注冊場景的拆解假設(shè)我們要用AI生成一個用戶注冊的后端接口。一個糟糕的指令是“寫一個用戶注冊的API”。而一個遵循Spec-Kit思想的指令應(yīng)該是這樣的# 用戶注冊接口 Spec-Kit 目標(biāo)生成一個Flask框架下的用戶注冊API端點(diǎn)。 輸入 - 方法POST - 路徑/api/v1/auth/register - 請求體 (JSON) * username: string, 必填長度3-20只允許字母、數(shù)字、下劃線。 * email: string, 必填需符合郵箱格式。 * password: string, 必填長度8-32必須包含大小寫字母和數(shù)字。 * confirm_password: string, 必填必須與password字段值相等。 輸出 - 成功 (HTTP 201){“code”: 201, “message”: “User registered successfully”, “data”: {“user_id”: 123}} - 失敗 (HTTP 400){“code”: 400, “message”: “Validation error”, “errors”: [{“field”: “username”, “error”: “Already taken”}]} 業(yè)務(wù)規(guī)則 1. 用戶名和郵箱必須在系統(tǒng)中唯一。 2. 密碼需使用bcrypt進(jìn)行哈希存儲明文密碼不得落庫或日志。 3. 注冊成功后應(yīng)自動生成一個激活令牌JWT格式有效期24小時并發(fā)送激活郵件郵件發(fā)送邏輯可留空用TODO注釋。 4. 所有輸入必須先進(jìn)行驗(yàn)證驗(yàn)證失敗立即返回不進(jìn)行后續(xù)數(shù)據(jù)庫操作。 非功能性要求 1. 需要基本的請求日志。 2. 數(shù)據(jù)庫操作需使用SQLAlchemy ORM假設(shè)已配置。 3. 代碼需包含適當(dāng)?shù)漠惓Ｌ幚怼?示例請求 - 正確{“username”: “john_doe”, “email”: “johnexample.com”, “password”: “Pass1234”, “confirm_password”: “Pass1234”} - 錯誤{“username”: “ab”, “email”: “not-an-email”, “password”: “123”, “confirm_password”: “456”}當(dāng)你把這樣一份詳細(xì)的Spec-Kit交給像Cursor、Claude或GitHub Copilot這樣的AI編程助手時它生成代碼的準(zhǔn)確性和可用性會呈指數(shù)級提升。你得到的將不再是一個需要大量修改的“毛坯房”而是一個幾乎可以直接運(yùn)行的“精裝修”代碼片段。3. SDD從“測試驅(qū)動”到“規(guī)格驅(qū)動”的范式演進(jìn)SDD全稱是Specification-Driven Development即“規(guī)格驅(qū)動開發(fā)”。這個名字很容易讓人聯(lián)想到我們熟悉的TDDTest-Driven Development測試驅(qū)動開發(fā)。事實(shí)上SDD可以看作是TDD在AI時代的一種演進(jìn)和升華。3.1 TDD的局限與SDD的契機(jī)TDD的核心循環(huán)是“紅-綠-重構(gòu)”先寫一個失敗的測試紅然后寫最簡單的代碼讓測試通過綠最后重構(gòu)代碼優(yōu)化結(jié)構(gòu)。TDD很棒它保證了代碼的可測試性和設(shè)計(jì)質(zhì)量。但它有一個前提開發(fā)者自己很清楚代碼最終應(yīng)該實(shí)現(xiàn)成什么樣。在AI輔助編程的語境下這個前提發(fā)生了變化。很多時候我們可能對一個模塊的功能只有模糊的想法或者我們希望AI能幫我們探索不同的實(shí)現(xiàn)方案。這時先寫測試就變得有些困難——你連代碼長什么樣都不知道怎么寫斷言SDD巧妙地解決了這個問題。它把TDD中的“測試”前置條件替換成了更抽象、更偏重描述的“規(guī)格”。SDD的循環(huán)可以概括為“規(guī)格 - AI生成 - 驗(yàn)證 - 迭代”。規(guī)格首先用自然語言或結(jié)構(gòu)化的方式比如我們上面提到的Spec-Kit詳細(xì)描述你想要的功能、行為、接口和約束。這個規(guī)格是給人看的也是給AI看的“需求文檔”。AI生成將這個規(guī)格輸入給AI代碼生成工具讓它產(chǎn)出初步的代碼實(shí)現(xiàn)。驗(yàn)證對生成的代碼進(jìn)行驗(yàn)證。這不僅僅是運(yùn)行單元測試當(dāng)然如果規(guī)格足夠細(xì)可以自動生成測試用例還包括代碼審查、靜態(tài)分析、集成測試等確保其符合規(guī)格要求。迭代如果驗(yàn)證不通過或者有新的想法就回過頭來修改和細(xì)化規(guī)格然后再次讓AI生成。這個過程比手動修改代碼更快因?yàn)樗窃诟叩某橄髮蛹壱?guī)格上進(jìn)行迭代。3.2 SDD在團(tuán)隊(duì)流程中的落地以阿里Qoder為例一些前沿的團(tuán)隊(duì)和工具已經(jīng)在實(shí)踐SDD。例如阿里內(nèi)部孵化的Qoder項(xiàng)目其理念就非常接近SDD。它鼓勵開發(fā)者先在一個協(xié)作空間中用Markdown等形式共同撰寫功能規(guī)格明確接口定義、數(shù)據(jù)模型、業(yè)務(wù)流程和驗(yàn)收條件。這份活的文檔不僅是溝通依據(jù)更可以直接作為提示詞Prompt輸入給集成的AI編碼助手一鍵生成符合團(tuán)隊(duì)規(guī)范和業(yè)務(wù)場景的腳手架代碼。SDD帶來的最大改變是將開發(fā)的重心從“編寫代碼”轉(zhuǎn)移到了“定義規(guī)格”。程序員的核心能力不再是記憶API或手寫算法而是精準(zhǔn)地分析、拆解和表述復(fù)雜需求。這要求開發(fā)者具備更強(qiáng)的抽象思維、領(lǐng)域建模和溝通能力。同時它也促進(jìn)了文檔的實(shí)時性和準(zhǔn)確性因?yàn)槲臋n規(guī)格直接關(guān)聯(lián)著可執(zhí)行的產(chǎn)出代碼文檔過時意味著生成物失效這倒逼團(tuán)隊(duì)維護(hù)好這份最重要的資產(chǎn)。4. OpenSpec開源社區(qū)的“人機(jī)協(xié)作協(xié)議”嘗試如果說Spec-Kit是一種模式SDD是一種方法論那么OpenSpec則更像一個具體的、正在發(fā)展的開源項(xiàng)目或標(biāo)準(zhǔn)倡議。它的目標(biāo)是創(chuàng)建一種通用的、機(jī)器可讀的“規(guī)格描述語言”或協(xié)議讓不同的AI編程工具都能理解同一份需求說明。4.1 OpenSpec的愿景打破工具壁壘目前不同的AI編程助手如Cursor、Claude Code、GitHub Copilot對提示詞的理解和響應(yīng)方式各有不同。你為Copilot優(yōu)化的提示詞直接扔給Cursor可能效果不佳。這就導(dǎo)致了學(xué)習(xí)和切換成本。OpenSpec試圖定義一個中間層。你可以用OpenSpec格式來編寫你的功能規(guī)格然后這個OpenSpec文件可以被各種支持該標(biāo)準(zhǔn)的工具消費(fèi)。工具負(fù)責(zé)將OpenSpec解析成自己擅長的提示詞或者直接基于OpenSpec的結(jié)構(gòu)化信息來生成代碼、測試甚至部署配置。一個理想的OpenSpec文件可能包含以下層次元信息項(xiàng)目、模塊、版本、作者。組件定義類、函數(shù)、API端點(diǎn)等。接口描述輸入、輸出、錯誤類型可能使用JSON Schema或類似格式。行為描述用自然語言或某種領(lǐng)域特定語言描述關(guān)鍵邏輯。約束與要求性能、安全、依賴等。示例輸入輸出對。4.2 OpenSpec的現(xiàn)狀與挑戰(zhàn)從Proposal到實(shí)踐目前OpenSpec還處于比較早期的階段。你在網(wǎng)上搜到的openspec proposal、openspec官方文檔可能更多是一些討論、草案或某個原型的文檔。它的安裝openspec install和使用教程openspec使用教程可能還不像成熟軟件那樣完善。它的挑戰(zhàn)在于標(biāo)準(zhǔn)化之難讓整個社區(qū)接受并采用一套新標(biāo)準(zhǔn)非常困難。需要平衡表達(dá)能力、簡潔性和工具實(shí)現(xiàn)的復(fù)雜性。與現(xiàn)有生態(tài)集成如何與現(xiàn)有的Swagger/OpenAPI用于API描述、JSDoc/TypeScript定義等共存和互補(bǔ)AI的理解能力即使有了結(jié)構(gòu)化描述AI模型是否真的能更好地利用這些信息還是說一份優(yōu)秀的自然語言描述加上幾個示例即好的Spec-Kit已經(jīng)足夠盡管有挑戰(zhàn)但OpenSpec的方向是值得關(guān)注的。它代表了社區(qū)對建立更優(yōu)“人機(jī)協(xié)作界面”的集體探索。即使它最終沒有成為唯一標(biāo)準(zhǔn)其探索過程中產(chǎn)生的思想和最佳實(shí)踐也會被其他工具和模式所吸收。5. 核心貫通點(diǎn)為什么“寫清楚”如此重要分析了三者的不同側(cè)重點(diǎn)后我們可以清晰地看到那條貫穿始終的主線“先寫清楚再讓AI干活”。這個“寫清楚”在AI編程的語境下具有前所未有的重要性原因有三5.1 彌補(bǔ)AI的“上下文缺失”與“邏輯跳躍”人類程序員擁有豐富的隱性知識行業(yè)慣例、團(tuán)隊(duì)規(guī)范、系統(tǒng)架構(gòu)、過往的坑。AI沒有。如果你只說“創(chuàng)建一個商品服務(wù)”AI不知道你的“商品”是否有SKU、是否有庫存概念、價格是整數(shù)還是浮點(diǎn)數(shù)、是否需要支持多貨幣。你必須通過詳細(xì)的規(guī)格將這些隱性知識顯式化為AI補(bǔ)全上下文防止它基于公共訓(xùn)練數(shù)據(jù)做出不合理的默認(rèn)假設(shè)。5.2 提升生成結(jié)果的確定性與質(zhì)量模糊的需求導(dǎo)致隨機(jī)的輸出。你讓AI“寫一個排序函數(shù)”它可能給你快速排序、歸并排序或冒泡排序。但如果你寫明“需要一個穩(wěn)定的、原地排序的、針對小型整數(shù)數(shù)組優(yōu)化的函數(shù)”AI就更可能給出插入排序或計(jì)數(shù)排序的變種。確定性是工程化的基礎(chǔ)。詳細(xì)的規(guī)格能將AI的創(chuàng)造力引導(dǎo)到解決具體問題上而不是在無限的可能性中隨機(jī)漫步從而顯著提升生成代碼的可用性和質(zhì)量。5.3 將開發(fā)過程轉(zhuǎn)化為可迭代、可驗(yàn)證的流程當(dāng)“規(guī)格”成為開發(fā)過程的核心工件時整個工作流就變得清晰且可管理。評審的重點(diǎn)從代碼細(xì)節(jié)語法、風(fēng)格前移到規(guī)格設(shè)計(jì)邏輯、邊界是否正確。測試用例可以部分從規(guī)格中自動推導(dǎo)。更重要的是當(dāng)需求變更時你首先修改的是規(guī)格文檔然后重新生成代碼這比直接修改代碼更不容易引入隱性錯誤也更容易評估變更范圍。6. 如何上手從今天開始實(shí)踐“先寫清楚”理論說了這么多具體該怎么開始呢你不必等待某個工具成熟現(xiàn)在就可以將這種思想融入你的工作。6.1 個人實(shí)踐改造你的AI編程提示詞下次使用任何AI編程助手時嘗試按照下面的結(jié)構(gòu)來組織你的提示詞你會發(fā)現(xiàn)效果立竿見影角色與上下文設(shè)定“你是一個經(jīng)驗(yàn)豐富的Python后端開發(fā)工程師正在開發(fā)一個電商系統(tǒng)。”任務(wù)目標(biāo)“請為我生成一個Flask藍(lán)本用于處理用戶購物車。”詳細(xì)規(guī)格Spec-Kit風(fēng)格數(shù)據(jù)結(jié)構(gòu)購物車項(xiàng)應(yīng)包含product_id整數(shù)、quantity整數(shù)大于0、added_at時間戳。API端點(diǎn)GET /cart獲取當(dāng)前用戶購物車列表需關(guān)聯(lián)查詢商品名稱和單價。POST /cart/items添加商品需驗(yàn)證商品是否存在及庫存是否充足。PUT /cart/items/item_id更新商品數(shù)量。DELETE /cart/items/item_id刪除商品。業(yè)務(wù)規(guī)則用戶必須登錄購物車數(shù)據(jù)應(yīng)持久化到數(shù)據(jù)庫使用SQLAlchemy模型Cart和CartItem添加商品時若已存在相同product_id則增加數(shù)量而非新建條目。非功能性要求需要請求參數(shù)驗(yàn)證使用JSON響應(yīng)包含基本的錯誤處理。示例“例如對于POST /cart/items請求體為{product_id: 123, quantity: 2}成功應(yīng)返回201和新增的購物車項(xiàng)信息?！?.2 團(tuán)隊(duì)協(xié)作引入輕量級規(guī)格評審在團(tuán)隊(duì)任務(wù)拆解或技術(shù)方案設(shè)計(jì)階段增加一個“規(guī)格定義”環(huán)節(jié)。要求負(fù)責(zé)人在寫代碼前先提交一份簡明的規(guī)格說明可以是一個Markdown文件描述清楚新功能的輸入、輸出、主要邏輯、邊界情況和對外影響。團(tuán)隊(duì)其他成員對此進(jìn)行評審。評審?fù)ㄟ^后開發(fā)者可以基于這份規(guī)格利用AI高效生成代碼主干自己則專注于核心邏輯和集成測試。這不僅能減少返工還能讓新人更快理解系統(tǒng)。6.3 工具選擇關(guān)注能力而非標(biāo)簽?zāi)壳安]有一個工具叫“Spec-Kit”SDD是一種模式OpenSpec尚在萌芽。因此我們的重點(diǎn)不應(yīng)是尋找貼有這些標(biāo)簽的工具而是評估現(xiàn)有工具是否支持這種工作流。Cursor / Cline / 各類AI編程助手關(guān)注它們對多文件上下文的理解能力、自定義指令Custom Instructions的靈活性以及是否支持從注釋或文檔字符串生成代碼。這些能力是實(shí)踐“先寫清楚”的基礎(chǔ)設(shè)施。Qoder / Superpowers等集成平臺關(guān)注它們是否提供了結(jié)構(gòu)化的需求錄入界面、團(tuán)隊(duì)知識庫集成以及能否將需求一鍵轉(zhuǎn)化為開發(fā)任務(wù)和代碼草稿。文檔與代碼同步工具關(guān)注像Swagger Codegen這類能從API描述生成代碼的工具其思想是相通的。未來可能會有更通用的“規(guī)格即代碼”工具出現(xiàn)。7. 避坑指南實(shí)踐中的常見問題與應(yīng)對策略在將“先寫清楚”付諸實(shí)踐的過程中我遇到并總結(jié)了一些典型的坑這里分享給你希望能幫你少走彎路。7.1 坑一規(guī)格寫得過于冗長或過于簡略這是一個平衡的藝術(shù)。過于簡略AI無法理解過于冗長AI可能抓不住重點(diǎn)而且編寫成本太高。應(yīng)對策略遵循“金字塔原則”。先寫一句話總結(jié)核心功能目標(biāo)然后列出3-5個關(guān)鍵特性或子任務(wù)再針對每個子任務(wù)展開輸入輸出和關(guān)鍵規(guī)則。避免在規(guī)格中描述具體的算法實(shí)現(xiàn)細(xì)節(jié)那是AI或開發(fā)者該去思考的。用列表和表格來組織信息比大段文字更清晰。7.2 坑二忽略了邊界條件和異常流這是AI生成代碼最薄弱的環(huán)節(jié)。AI傾向于生成“快樂路徑”的代碼對于各種異常情況網(wǎng)絡(luò)超時、數(shù)據(jù)為空、并發(fā)沖突考慮不足。應(yīng)對策略在規(guī)格中必須單獨(dú)設(shè)立“邊界條件與異常處理”章節(jié)。主動思考并列出輸入為空或非法怎么辦依賴的服務(wù)不可用怎么辦數(shù)據(jù)庫操作失敗怎么辦并發(fā)操作導(dǎo)致數(shù)據(jù)不一致怎么辦明確指定重試策略、回滾機(jī)制和給用戶的錯誤信息。7.3 坑三生成代碼后不做審查和測試盲目信任AI生成的代碼是危險(xiǎn)的。生成的代碼可能存在安全漏洞如SQL注入、性能問題、或者與現(xiàn)有系統(tǒng)架構(gòu)不兼容。應(yīng)對策略建立鐵律——AI生成的代碼必須經(jīng)過人工審查和測試。審查重點(diǎn)包括安全漏洞、依賴引入、代碼風(fēng)格一致性、是否符合團(tuán)隊(duì)架構(gòu)規(guī)范。然后必須編寫或運(yùn)行針對性的單元測試和集成測試驗(yàn)證其行為完全符合規(guī)格?？梢詫I視為一個強(qiáng)大的“初級程序員”而你則是負(fù)責(zé)審核和定稿的資深工程師。7.4 坑四規(guī)格與代碼脫節(jié)不再維護(hù)一旦代碼生成并運(yùn)行起來那份辛苦寫好的規(guī)格文檔很容易被拋在腦后。后續(xù)的需求變更直接修改代碼導(dǎo)致規(guī)格文檔迅速過時。應(yīng)對策略將規(guī)格文檔視為“源代碼”的一部分。將其放在項(xiàng)目倉庫中如/specs/目錄與代碼文件一起進(jìn)行版本管理。任何功能修改必須先更新規(guī)格文檔提交一個“規(guī)格變更”的Commit然后再基于新規(guī)格去調(diào)整代碼。利用CI/CD流程可以嘗試探索將規(guī)格文檔作為生成測試用例或API文檔的源頭增加其“活性”。8. 未來展望規(guī)格驅(qū)動下的開發(fā)者角色進(jìn)化“先寫清楚再讓AI干活”這一模式的普及正在悄然改變軟件開發(fā)者的角色定義。未來的開發(fā)者或許可以稱為“規(guī)格工程師”或“AI協(xié)作工程師”。核心能力遷移從“熟練敲擊鍵盤實(shí)現(xiàn)邏輯”向“精準(zhǔn)定義問題與邊界”遷移。領(lǐng)域建模、系統(tǒng)分析、溝通協(xié)調(diào)能力變得比以往任何時候都重要。工作重心變化更多時間花在前期與產(chǎn)品、業(yè)務(wù)方澄清需求并將其轉(zhuǎn)化為精密、無歧義的規(guī)格說明。編碼本身將更多地變?yōu)閷I生成結(jié)果的審查、調(diào)整、集成和測試。工具鏈演進(jìn)我們將會看到更多專注于“規(guī)格”階段的工具出現(xiàn)比如可視化的規(guī)格設(shè)計(jì)器、能從規(guī)格自動生成測試用例的插件、能檢查規(guī)格一致性和完整性的Linter以及連接規(guī)格與多種AI代碼生成服務(wù)的中間平臺。Spec-Kit、SDD、OpenSpec無論它們叫什么都指向同一個未來人機(jī)協(xié)作的界面將變得更加清晰和高效。人類負(fù)責(zé)戰(zhàn)略、創(chuàng)意和定義“做什么”以及“做到什么標(biāo)準(zhǔn)”AI負(fù)責(zé)戰(zhàn)術(shù)、執(zhí)行和探索“如何做”的多種可能。這場變革已經(jīng)開始而起點(diǎn)就是學(xué)會如何“寫清楚”。這不僅是給AI下指令的技巧更是對自己思維的徹底梳理和錘煉。當(dāng)你能夠把一個復(fù)雜需求清晰地拆解并表述出來時問題往往已經(jīng)解決了一半。剩下的就讓你和AI一起高效地完成吧。