2024年，GitHub Copilot用戶平均每月生成代碼量暴漲，但一個(gè)反直覺的數(shù)據(jù)正在浮現(xiàn)：配套文檔的創(chuàng)建頻率同步增長(zhǎng)了3倍。不是開發(fā)者突然變勤快了，是AI工具把"寫說明"變成了寫代碼的必要前置步驟。

文檔從"墓碑"變成"燃料"

技術(shù)文檔長(zhǎng)期活在尷尬的夾縫里。ADR（架構(gòu)決策記錄）、Design Doc、API規(guī)格書——嘴上都說重要，交付時(shí)最先被砍的總是它。寫文檔貴、審文檔貴、維護(hù)更貴，在Deadline面前，文檔成了奢侈品。

AI Agent的興起改寫了這筆賬。生成一份技術(shù)規(guī)格的成本趨近于零，文檔從"事后總結(jié)"滑向"實(shí)時(shí)上下文"。Guilherme Zarelli在跟蹤多個(gè)工程團(tuán)隊(duì)后發(fā)現(xiàn)：當(dāng)文檔能被Agent直接讀取并執(zhí)行時(shí)，它的價(jià)值公式變了——不再只是"留給后人看"，而是"讓機(jī)器現(xiàn)在就能用"。

一個(gè)具體場(chǎng)景：以前寫API文檔是"告訴別人怎么用"，現(xiàn)在寫Spec是"告訴Agent怎么生成客戶端代碼、測(cè)試用例、錯(cuò)誤處理邏輯"。

Spec-Driven Development的回歸

2010年代的TDD（測(cè)試驅(qū)動(dòng)開發(fā)）曾試圖用測(cè)試用例鎖定需求，但測(cè)試代碼本身也是代碼，維護(hù)成本不低。Spec-Driven Development換了個(gè)思路：用人類可讀的結(jié)構(gòu)化文檔驅(qū)動(dòng)全流程——代碼生成、評(píng)審、部署、監(jiān)控。

Zarelli觀察到三個(gè)正在發(fā)生的遷移：

第一，Prompt即文檔。工程師不再寫"請(qǐng)實(shí)現(xiàn)用戶登錄功能"，而是貼一段OpenAPI規(guī)格+業(yè)務(wù)規(guī)則+邊界條件。Agent的產(chǎn)出質(zhì)量直接掛鉤輸入文檔的完整度。

第二，文檔版本與代碼版本綁定。傳統(tǒng)Wiki式的"最新版"邏輯失效了，每個(gè)代碼提交需要攜帶對(duì)應(yīng)時(shí)刻的決策上下文。Git的提交信息正在變長(zhǎng)，有些團(tuán)隊(duì)開始強(qiáng)制要求ADR（架構(gòu)決策記錄）編號(hào)出現(xiàn)在Commit Message里。

第三，評(píng)審對(duì)象轉(zhuǎn)移。Pull Request的評(píng)論區(qū)里，關(guān)于"這段代碼是否符合原始設(shè)計(jì)意圖"的爭(zhēng)論在減少——因?yàn)橐鈭D被寫進(jìn)了可被機(jī)器校驗(yàn)的Spec里。人審代碼，機(jī)器審一致性。

新成本：上下文腐爛

文檔便宜了，但新問題浮現(xiàn)。AI能批量生成規(guī)格書，也能批量生成過時(shí)的規(guī)格書。當(dāng)一份Spec被10個(gè)Agent引用、派生出20份下游文檔后，源頭的一行修改可能引發(fā)連鎖崩塌。

Zarelli提到一個(gè)團(tuán)隊(duì)的教訓(xùn)：他們用AI自動(dòng)生成了微服務(wù)間的依賴圖譜，三個(gè)月后架構(gòu)調(diào)整，圖譜沒同步更新，新入職的Agent基于舊圖譜生成了錯(cuò)誤的調(diào)用代碼，線上故障排查花了6小時(shí)——根因是一份"看起來沒問題"的文檔。

文檔的維護(hù)成本沒有消失，只是轉(zhuǎn)移了：從"寫不出來"變成"改不干凈"。

工程師的新技能樹

當(dāng)文檔成為執(zhí)行上下文，工程師的核心能力也在偏移。代碼能力當(dāng)然重要，但"把模糊需求翻譯成機(jī)器可解析的規(guī)格"正在成為瓶頸技能。Prompt Engineering的爭(zhēng)議在于它是否值得專門學(xué)習(xí)，但"寫清楚一件事"的需求是真實(shí)的。

一個(gè)信號(hào)：Notion、Confluence都在加速集成AI Agent接口，文檔工具的競(jìng)爭(zhēng)對(duì)手從彼此變成了"直接嵌入IDE的上下文管理系統(tǒng)"。文檔和代碼的邊界在溶解，工程團(tuán)隊(duì)需要重新設(shè)計(jì)工作流——不是"先寫代碼再補(bǔ)文檔"，而是"文檔即代碼，代碼即執(zhí)行"。

Zarelli的觀察停在了一個(gè)開放場(chǎng)景：某團(tuán)隊(duì)把季度OKR拆解成了可被Agent執(zhí)行的Spec樹，每周自動(dòng)同步進(jìn)度偏差。這個(gè)實(shí)驗(yàn)?zāi)芘芡▎?？還是說，當(dāng)目標(biāo)本身在變化時(shí)，機(jī)器-readable的計(jì)劃反而成了束縛？