先找痛點再選工具：快、準、輕鬆選兩個

很多團隊一談文件，就先問：「要用哪個 wiki（Notion、Obsidian、Confluence），還是哪個 AI 外掛？」

我認為順序反了。先說出問題，再選工具。不要讓今天流行的工具，決定我們的問題是什麼。

快、準、輕鬆，只能選兩個

做法	得到	失去
從程式碼產生（FastAPI）	快又準	只說「是什麼」，不說「為什麼」
在 wiki 手寫	開始很輕鬆	更新很慢，每週都更不準
AI 為每個 pull request 寫	快，又貼近程式碼	要花錢，還要有人審

能錯多久，看損害多大

文件	錯了會怎樣	多久更新
Onboarding 頁	新人多問一次人	每幾週
架構總覽	設計從錯的圖開始	每次 release
Runbook	事故變得更嚴重	每次變更

一套規則套全部文件，對某些太嚴，對某些太鬆。

三種原因，三種解法，AI 只解一種

把文件怎麼過期的裡的循環拆開，原因有三種。

原因	問題類型	例子	誰能修
跟程式碼不一致	機器	Makefile 刪了，README 還寫 make ...	AI 或 pipeline
沒人要求更新、沒有 owner	流程	PRD 在 kickoff 寫完，範圍改了沒更新	指定 owner 和時程
沒有獎勵（不被重視）	人	在聊天室做了決定，從沒寫 ADR	團隊文化，工具修不了

這是 AI 時代最容易誤會的地方。AI 很會修第一種，所以我們以為文件問題解決了。但第二種和第三種，AI 碰不到。

流程那一種，可以交給固定的提醒，見讓文件活著：三個提醒，單向流動。

就算這樣，還是會有錯的文件漏網。所以要有補償機制。真正要問團隊的是：一份錯的文件，多快必須修好？

AI 能讓文件跟上程式碼，但讓人願意寫，還是要靠團隊。

參考來源

• FastAPI：從程式碼產生 API 文件
• Michael Nygard：Documenting Architecture Decisions（ADR）

---

延伸閱讀： 回頭讀文件怎麼過期的，看看三個提醒。或回到系列總覽：AI 時代，文件怎麼活下來