一份夠細(xì)的需求文檔就是代碼本身

OpenAI最近放出的Symphony項(xiàng)目，號(hào)稱"完全從需求文檔生成"。但當(dāng)你真正打開那份SPEC.md，會(huì)發(fā)現(xiàn)一個(gè)反直覺的事實(shí)：這哪是什么需求文檔，根本就是偽代碼穿上了Markdown的外衣。

智能體編程（agentic coding）的鼓吹者正在兜售一個(gè)危險(xiǎn)幻覺——工程師可以退化成"需求管理員"，把具體實(shí)現(xiàn)丟給AI代理完成。但這份被奉為標(biāo)桿的"需求文檔"，恰恰戳破了這層窗戶紙。

幻覺一：寫需求比寫代碼更簡(jiǎn)單

Symphony的SPEC.md里充斥著這樣的內(nèi)容：

「State tracked while a coding-agent subprocess is running」——這是數(shù)據(jù)庫(kù)Schema的散文式 dump。

「The runtime counts issues by their current tracked state in the running map」——這是業(yè)務(wù)邏輯的偽代碼描述。

更直白的是文檔里直接標(biāo)注的注釋：「This section is intentionally redundant so a coding agent can implement the config layer quickly」。作者明知這是冗余，但為了照顧AI的"理解能力"，不得不把代碼邏輯用自然語(yǔ)言重寫一遍。

這暴露了一個(gè)殘酷的算式：如果AI需要如此細(xì)粒度的描述才能正確生成代碼，那么撰寫這份"需求"所需的心智負(fù)擔(dān)，與直接寫代碼并無本質(zhì)區(qū)別。你并沒有跳過編碼，只是把Python換成了"人類可讀的Python"。

鼓吹者將智能體編程包裝成"下一代外包"——工程師升維成管理者，AI代理成為廉價(jià)勞動(dòng)力。但這個(gè)商業(yè)模式成立的前提是：規(guī)格說明的成本必須遠(yuǎn)低于執(zhí)行成本。而Symphony的文檔證明，當(dāng)規(guī)格需要精確到變量命名和狀態(tài)機(jī)轉(zhuǎn)換時(shí)，它本身就是另一種形式的代碼。

幻覺二：需求過濾能提升代碼質(zhì)量

面對(duì)"AI會(huì)生成不可維護(hù)的垃圾代碼"的質(zhì)疑，倡導(dǎo)者的回應(yīng)是：需求文檔作為中間層，能強(qiáng)制工程師深思熟慮，從而提升工程質(zhì)量。

但Symphony的SPEC.md里藏著相反的證據(jù)。文檔中大量段落不是為了表達(dá)"要什么"，而是為了約束"怎么實(shí)現(xiàn)"——start_service()函數(shù)的偽代碼被完整寫出，包括configure_logging()的調(diào)用順序、state字典的每個(gè)鍵值對(duì)、甚至codex_totals的四個(gè)統(tǒng)計(jì)字段。

這種"需求"的本質(zhì)，是作者對(duì)AI能力邊界的精確預(yù)判后的補(bǔ)償性設(shè)計(jì)。他知道AI會(huì)在哪里出錯(cuò)，所以提前把陷阱填平。這不是深思熟慮的架構(gòu)設(shè)計(jì)，而是針對(duì)特定工具缺陷的打補(bǔ)丁行為。

更隱蔽的問題是維護(hù)性。當(dāng)代碼和"需求"以兩種形式表達(dá)同一套邏輯時(shí)，變更成本翻倍。修改一個(gè)重試策略，既要改SPEC.md里的偽代碼，又要驗(yàn)證生成代碼的符合性。所謂的"單一真相源"，變成了雙重維護(hù)負(fù)擔(dān)。

那個(gè)漫畫的未盡之意

文章開頭引用的漫畫（程序員把需求文檔直接編譯成代碼）之所以有效，是因?yàn)樗鼡糁辛塑浖こ痰暮诵你Ｕ摚壕_性與可理解性的張力。

人類自然語(yǔ)言天生模糊，這正是它在需求溝通中的價(jià)值——允許歧義，保留協(xié)商空間。而代碼的精確性是其執(zhí)行的基礎(chǔ)。任何試圖用自然語(yǔ)言替代代碼的嘗試，要么犧牲精確性（導(dǎo)致AI生成錯(cuò)誤），要么逼近精確性（導(dǎo)致"需求"變成偽代碼）。

Symphony的SPEC.md選擇了后者。它不是需求文檔的勝利，而是偽代碼借尸還魂。作者用Markdown的語(yǔ)法糖，寫了整整一份可執(zhí)行的邏輯描述——只是恰好不能被Python解釋器直接運(yùn)行而已。

智能體編程的真正挑戰(zhàn)，不是如何讓AI"理解"需求，而是如何定義一個(gè)合適的抽象層級(jí)：足夠精確以指導(dǎo)實(shí)現(xiàn)，又足夠抽象以保留人類的價(jià)值判斷。Symphony的文檔在這個(gè)光譜上嚴(yán)重偏向精確端，以至于人類作者承擔(dān)了大部分本應(yīng)由AI完成的"翻譯"工作。

時(shí)間線：從外包幻想到工程現(xiàn)實(shí)

2023-2024年，GitHub Copilot等工具確立了"AI作為結(jié)對(duì)程序員"的定位——輔助而非替代，加速而非外包。

2024年末至2025年初，隨著Claude 3.5 Sonnet等模型的代碼能力躍升，"vibe coding"（氛圍編程）興起：開發(fā)者用自然語(yǔ)言描述意圖，AI直接生成可運(yùn)行代碼。這一階段的核心假設(shè)是：模糊需求可以被AI的"常識(shí)"填補(bǔ)。

2025年中，vibe coding的局限性暴露。AI在復(fù)雜狀態(tài)管理、并發(fā)控制、錯(cuò)誤恢復(fù)等場(chǎng)景下頻繁出錯(cuò)，生成的代碼難以調(diào)試和擴(kuò)展。社區(qū)開始反思：完全拋棄結(jié)構(gòu)化的代價(jià)。

2026年3月，OpenAI發(fā)布Symphony，試圖用"結(jié)構(gòu)化需求文檔"回應(yīng)上述問題。但其SPEC.md的詳細(xì)程度表明，這并非需求的回歸，而是偽代碼的復(fù)興——人類用更費(fèi)力的方式，做著與寫代碼同樣的事。

同一時(shí)期，Cursor、Windsurf等IDE的代理模式（agent mode）也在探索類似路徑：讓AI自主規(guī)劃、執(zhí)行、驗(yàn)證，但保留人類在關(guān)鍵決策點(diǎn)的介入權(quán)。這些工具的共同特征是模糊"需求"與"實(shí)現(xiàn)"的邊界——AI既讀代碼也讀文檔，人類既寫需求也改代碼。

被遮蔽的真實(shí)成本

Symphony文檔中一個(gè)容易被忽略的細(xì)節(jié)：作者明確標(biāo)注某些段落"故意冗余"，以幫助AI快速實(shí)現(xiàn)配置層。這是對(duì)當(dāng)前大模型能力的精準(zhǔn)診斷——它們需要重復(fù)、顯式、結(jié)構(gòu)化的提示，才能穩(wěn)定輸出正確結(jié)果。

這意味著什么？撰寫一份能被AI正確執(zhí)行的"需求"，需要作者具備雙重能力：既懂領(lǐng)域邏輯，又懂模型行為模式。你不是在寫給人看的需求，而是在設(shè)計(jì)針對(duì)特定AI的"提示工程系統(tǒng)"。

這種技能的稀缺性，遠(yuǎn)高于普通編程。當(dāng)市場(chǎng)上充斥著"用自然語(yǔ)言編程"的營(yíng)銷話術(shù)時(shí)，真正在Symphony項(xiàng)目中承擔(dān)核心工作的，是那些能把狀態(tài)機(jī)用散文精確描述、能預(yù)判AI在哪行會(huì)出錯(cuò)、懂得何時(shí)重復(fù)何時(shí)省略的工程師。

他們不是在遠(yuǎn)離代碼，而是在以一種更迂回、更費(fèi)力的方式與代碼搏斗。

商業(yè)邏輯的重新審視

智能體編程的鼓吹者描繪了一幅圖景：企業(yè)雇傭少量高級(jí)工程師撰寫規(guī)格，用AI代理替代大量初中級(jí)開發(fā)者。但Symphony的案例提示了另一種可能：

如果"規(guī)格"需要精確到偽代碼級(jí)別，那么撰寫者本身就是高級(jí)工程師——而他們的時(shí)間成本，通常高于讓初中級(jí)開發(fā)者直接實(shí)現(xiàn)。AI代理節(jié)省的，可能只是打字時(shí)間，而非思考時(shí)間。

更現(xiàn)實(shí)的場(chǎng)景或許是分層協(xié)作：AI處理明確的、局部的代碼生成（如函數(shù)實(shí)現(xiàn)、測(cè)試用例），人類專注于架構(gòu)決策、邊界情況識(shí)別、以及——諷刺地——撰寫那些AI無法正確理解的"規(guī)格說明"。

這不是外包關(guān)系的倒置，而是協(xié)作關(guān)系的重新定義。AI不是勞動(dòng)力的替代品，而是認(rèn)知?jiǎng)趧?dòng)的放大器。它放大的不是"把需求變成代碼"的翻譯過程，而是"在多個(gè)抽象層級(jí)間切換"的復(fù)雜工作。

工程實(shí)踐的分岔路口

Symphony項(xiàng)目本身是一個(gè)有價(jià)值的實(shí)驗(yàn)。它證明了在特定約束下，AI可以從高度結(jié)構(gòu)化的描述生成可運(yùn)行系統(tǒng)。但把它作為"需求驅(qū)動(dòng)開發(fā)"的通用范式，則是范疇錯(cuò)誤。

關(guān)鍵區(qū)分在于：Symphony的"需求"是針對(duì)一個(gè)已知領(lǐng)域的精確建模（agent orchestrator的狀態(tài)管理），而非面向未知領(lǐng)域的探索性定義。前者適合結(jié)構(gòu)化描述，后者需要迭代試錯(cuò)。

大多數(shù)軟件項(xiàng)目的核心挑戰(zhàn)，不是"如何實(shí)現(xiàn)已知需求"，而是"需求究竟是什么"。用戶研究、原型驗(yàn)證、領(lǐng)域建模——這些活動(dòng)的產(chǎn)出難以用SPEC.md的形式表達(dá)，卻決定了項(xiàng)目的成敗。

將Symphony模式泛化，會(huì)誤導(dǎo)團(tuán)隊(duì)把精力投入到"如何讓AI理解"的形式優(yōu)化，而忽視"要解決什么問題"的本質(zhì)思考。這是工具理性對(duì)價(jià)值理性的侵蝕。

當(dāng)"需求"變成另一種代碼

回到文章開頭的漫畫。它的幽默在于揭示了一個(gè)循環(huán)：程序員試圖用自然語(yǔ)言逃避代碼的精確性，最終發(fā)現(xiàn)自然語(yǔ)言被迫精確化，變成了另一種代碼。

Symphony的SPEC.md是這個(gè)循環(huán)的當(dāng)代版本。它不是需求的勝利，而是偽代碼的借尸還魂；不是工程師的升維，而是工作形態(tài)的平移。

真正的進(jìn)步，或許在于承認(rèn)這個(gè)循環(huán)的不可逃避性，并尋找更高效的旋轉(zhuǎn)方式——而不是假裝我們已經(jīng)找到了跳出循環(huán)的捷徑。

當(dāng)OpenAI把這份文檔作為"從需求生成代碼"的范例時(shí)，他們無意中證明了相反的觀點(diǎn)：一份足夠詳細(xì)的需求文檔，本身就是代碼。問題不在于AI能否理解它，而在于人類為何要用兩種語(yǔ)言維護(hù)同一套邏輯。

如果撰寫SPEC.md的心智負(fù)擔(dān)與寫Python相當(dāng)，如果調(diào)試"需求-代碼"不一致性的成本高于直接調(diào)試代碼，那么智能體編程的承諾——更便宜的開發(fā)、更少的工程師、更高的抽象——究竟在何處兌現(xiàn)？