文件是 AI 時代的隱藏槓桿

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

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

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

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

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

文件是想法的具象化

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

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

文件不是想法的附屬品，而是想法成形的過程。這層價值跟 AI 無關，但常常被忽略。

文件是給 AI 看的 context

AI 很吃 context。給它越多正確 context，它越像 teammate；什麼都不給，它就只是一個很會猜的陌生人。

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

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

Onboarding：給新人、給未來的自己、也給 AI

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

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

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

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

文件作為 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 也是一種臨時文件，寫得模糊，輸出自然也會模糊。

AI review 跟測試：留個伏筆

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

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

文件提供 context，review 提供檢查，測試提供底線。

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

結語：隱藏槓桿

AI 時代不是讓文件變得不重要，而是讓文件的價值被放大。它不只是給 PM 看、給新人看、給未來的自己看；也開始變成給 AI 看的 context。

寫文件不是為了留下漂亮文字，而是為了留下可以被重用的思考。好文件讓人更快進入狀況，讓 AI 更少猜錯，也讓複雜組織裡的決策更有依據。

文件用得好、理解得好，現在能比過去發揮更大的槓桿，但也是大學問。寫得越清楚，人跟 AI 都越容易正確呼叫它。