文件在 AI 時代的價值

最近又有好幾個場合討論到 Design Doc，把現在的看法整理一下。主要還是圍繞 AI 的場景。

以前文件 ROI 很差，所以大家討厭寫

工程師討厭寫文件其實很合理。寫 code 有具體可見的 output、test 跑過、merge 進去都會留下正向的回饋與紀錄；寫文件常常像是另一種行政成本。寫很久，沒人看；寫完，過兩週就過期；最後還被笑說只是拿來交差給 PM 用。

但 AI 出現後，這件事有點變了。以前文件可能真的沒人看，現在至少 AI 會看。

這不是說文件突然變神聖，是文件的 ROI 變了：寫文件的成本下降，文件能產生的價值上升。

寫下來，才知道哪裡還沒想清楚

文件不是把想好的東西打字出來而已。很多時候，是寫下來之後，才發現自己其實還沒想清楚。

腦中的設計通常很模糊。一旦要寫成文件，就會被迫說清楚：問題是什麼、goal / non-goal 在哪、有哪些方案、trade-off 是什麼、哪些事情還沒決定。設計討論完整再開始動工，整體效率反而比較高。

我自己常常是寫到一半，才發現設計裡哪些地方其實還沒想清楚。這層價值跟 AI 無關，但很容易被忽略。

文件是給 AI 看的 context

AI 對 context 很敏感。把 codebase 的規則和限制交代清楚，它才不需要一路猜下去。

AI 看得懂 code，不代表它看得懂 codebase。它知道語法、知道常見 pattern，但不知道：這個 module 的責任邊界、哪些 invariant 不能破壞、哪些地方是歷史包袱、哪些 command 才是正確跑法、哪些 corner case 以前踩過雷、哪些實作看起來醜，但其實是刻意保守。

叫 AI 寫出一段 code 不難，難的是讓它在既有 codebase 裡正確地跑起來、測起來、改起來。README、build 指令、test command 這些看似平凡的文件，會直接影響 AI 能不能有效率地了解 codebase 並正確做事。沒寫清楚，它就會開始猜。猜對很神，猜錯就很浪費時間。

Onboarding 不只給新人

文件最常被提到的價值是 onboarding。這件事在 AI 時代沒有消失，反而更重要。

幾個月後回來看一段 code，常常不是真的看不懂 code，而是忘了當初為什麼這樣做。當時的限制、討論、替代方案、踩過的坑，如果沒有留下來，就只能重新考古。

文件在這裡的價值是保存 context：給新人看，是 onboarding；給自己看，是恢復記憶；給 AI 看，是讓工具接上脈絡。文件不是只給別人看的；很多時候，它是寫給三個月後已經忘光的自己看的。

AI 加進來之後，這份 context 又多了一個使用者。以前文件可以幫人少問一次問題；現在文件也可以讓 AI 少猜一次答案。

Design Doc 也是 alignment 與 approval 的紀錄

在 level 層級比較明確、stakeholder 比較多的環境（Google 這類大公司就很典型），文件還有一個很現實的作用：它是 alignment 跟 approval 的載體。

麻煩的往往不是「不會做」，而是方向沒人明確 approve、proposal review 拖很久、上面沒正式否決也不給明確同意；下面已經被期待要推進、做到一半方向被翻案、最後變成做白工。

文件讓「我覺得應該這樣做」，變成「我們同意先這樣做」。

以前寫 proposal、整理討論、回 reviewer comment 都很花時間。AI 之後，這些成本下降很多。在複雜組織裡，先把方向寫清楚、拿到 review 跟 approve，做事比較有底氣。

AI 讓文件快速迭代，但別什麼都怪 AI

AI 寫文件很快，所以文件不再像以前那種一次性交付。可以先丟粗糙想法，讓 AI 幫忙整理成 draft，再來回修：補缺少章節、改語氣、整合 reviewer feedback、產生 PR description / test plan / decision log。

但 AI 也很容易天馬行空。AI 很擅長把東西寫得「像一份文件」，但不代表它真的理解你的決策。如果 prompt 裡沒說清楚哪些是已決定、哪些只是猜測、哪些不能亂補，它就會把假設寫得像結論。

所以 Superpowers 這類工具、或更廣義的 prompt template、context management 就變得有用。它們不是魔法，是讓常用的文件結構、語氣要求、review checklist、專案 context 可以被重用，降低 AI 亂跑的機率。

AI 寫歪的時候，幾乎都不是 AI 的問題，自己的 prompt 品質要負更大責任。Prompt 也是一種臨時文件，寫得模糊，輸出自然也會模糊。

同一套做法也能用在 code review

同樣的邏輯也可以放到 AI code review。只叫 AI「幫我 review code」通常不夠。比較好的方式是把人類 review 會看的點拆開：correctness、edge cases、performance、error handling、test coverage、maintainability，讓 AI 分別檢查，多跑幾輪，搭配不同工具。

這些 checklist 本身也是文件。把團隊在意的標準寫下來，AI 才知道要用什麼角度 review。

我會把這三件事分開：文件交代 context，review 找問題，測試守住最基本的 correctness。

AI review code 的流程其實可以另外寫一篇，會牽涉到 prompt、多工具、多輪檢查跟測試怎麼串起來。這篇先暫停在這裡。

我現在怎麼看文件

文件現在多了一個會直接讀它、照著它工作的使用者：AI。這讓 Design Doc、README 和 checklist 更常被實際用到，而不只是在 review 時交差。

我寫文件，一方面是把當下的思考留下來，另一方面也是讓之後接手的人或工具不用重新考古。

現在我比較在意的，不是文件寫得像不像正式規格，而是它能不能把問題、限制、決定和未決事項講清楚。這些寫清楚，人比較好接手，AI 也少猜。