AI 協作時代，怎麼把需求、決策與除錯過程留成組織知識？

AI 協作時代，值得留下的紀錄有四種：需求規格、決策理由、修改與測試紀錄，以及給 AI 的專案規則。原因很直接：AI 每次開新對話都不記得上一次發生什麼事，新加入的同事也一樣。沒有寫下來的需求與判斷，只存在某個人的腦中或某一次對話裡。這篇文章對照架構決策紀錄、亞馬遜的敘事備忘錄與 Claude Code 的專案規則檔，說明四種紀錄各自要寫什麼，也說明哪些做法有公開來源、哪些是我的建議。

為什麼 AI 協作更需要書面紀錄？

AI 不會自動記得過去的對話，人員也會流動；沒有寫下來的需求與判斷，下一個人與下一次對話的 AI 都無從得知。

Anthropic 在談 AI 代理的上下文工程時指出，模型能同時處理的資訊有限，因此需要策略性地管理放進去的內容，其中一種做法是結構化的筆記：把重要資訊寫到上下文視窗之外，需要時再讀回來（Anthropic，Effective context engineering for AI agents，2025 年 9 月）。

Claude Code 的官方文件也把專案規則檔 CLAUDE.md 與自動記憶都當成「上下文」，而不是強制執行的設定；內容越具體、越簡潔，AI 越可能照著做（Anthropic，Claude Code memory）。換句話說，寫下來是為了讓 AI 與人都有東西可以讀，並不保證 AI 一定遵守。

敏捷宣言的原則也提到，商業人員與開發者應該每天一起工作、歡迎需求的變動、經常交付可用的軟體（Agile Manifesto，Principles）。這些原則談的是持續溝通，並沒有說不用寫紀錄。AI 加快了開發節奏，需求變得更快，更需要用文字把當下的決定固定下來。

該留下哪四種紀錄？

四種紀錄各回答一個問題：需求規格回答做什麼，決策理由回答為什麼，修改與測試紀錄回答改了什麼，專案規則回答 AI 該遵守什麼。

下表是我的整理，不是業界標準。

紀錄類型	回答的問題	誰會用到
需求規格	要做什麼、給誰用、怎樣算完成	開發者、AI、驗收的人
決策理由	當初為什麼選這個做法、放棄了什麼	接手的人、未來要改架構的人
修改與測試紀錄	這次改了什麼、怎麼確認沒壞	除錯的人、審查的人
給 AI 的專案規則	這個專案的慣例、禁止事項、常用指令	每一次新對話的 AI

四種紀錄的對象不同，所以寫法也不同：前兩種給人讀，最後一種給 AI 讀，中間一種兩者都要用。

需求規格要寫到多細？

需求規格至少要寫清楚使用者是誰、要解決什麼問題、完成的判斷標準，以及不做什麼；完成標準要讓人與 AI 都能照著檢查。

Anthropic 的 Claude Code 官方文件建議，先請 AI 訪談你，再寫出完整規格檔，之後開新對話照規格實作（Anthropic，Best practices for Claude Code）。這個流程本身就產生一份書面紀錄。

我建議規格至少包含下列四項：

項目	範例問題
使用者與情境	誰會在什麼時候用？
問題與目標	現在怎麼做？做完後哪裡變好？
完成標準	怎樣算做完？有哪些情況必須通過？
不做的事	這一版刻意不處理什麼？

最後一項常被忽略。AI 讓功能變得容易做，沒有寫下不做的事，範圍就容易自己長大。本分類的MAXO 案例裡，受訪者的對策正是先寫需求說明書，再動手。

決策理由怎麼留下來？

決策理由可以用架構決策紀錄的格式留下：標題、狀態、背景、決定與後果，每項決定一份短文件，跟程式碼放在同一個儲存庫。

麥克・奈加德（Michael Nygard）在 2011 年提出架構決策紀錄（Architecture Decision Record, ADR）：每一個重要的架構決定寫成一份短文件，格式包含標題、狀態、背景、決定與後果，並且放在專案的原始碼儲存庫中，讓新加入的人能追溯當初為什麼這樣做（Michael Nygard，Documenting Architecture Decisions，Cognitect，2011 年 11 月）。

對使用 AI 的團隊來說，ADR 還有一個額外的用途：下次有人（或 AI）想把架構改回去時，可以先讀當初為什麼不那樣做。

亞馬遜則採用另一種做法。貝佐斯（Jeff Bezos）在 2017 年給股東的信中提到，亞馬遜的會議用六頁的敘事備忘錄取代簡報，開會時先安靜閱讀（Amazon，2017 Letter to Shareholders）。這是一家公司的做法，並沒有證據證明它適用於所有團隊；但它說明了一件事：把想法寫成完整的句子，比條列的簡報更難隱藏沒想清楚的地方。

修改與測試紀錄要留什麼？

修改紀錄要寫清楚改了什麼與為什麼改，測試紀錄則要能重複執行；有測試，下次改動時才知道有沒有改壞。

Martin Fowler 把測試驅動開發（TDD）說明為三步：先寫一個會失敗的測試、寫剛好能通過的程式碼、再整理程式碼（Martin Fowler，Test Driven Development）。這個循環的副產品是：測試本身就是一份可以執行的需求紀錄。

紀錄	建議寫法	目的
修改說明	說明改了什麼、為什麼改	日後除錯時能追溯
錯誤的重現步驟	一個失敗的測試或明確步驟	確認修好、避免再發生
測試結果	可重複執行的指令與預期結果	審查與交接時不用重新猜測

除錯過程也值得留下。本分類的需求分析師用 AI 做網站案例裡，開發途中遇到修不好、跑版與改壞功能的情況，這些處理經驗都屬於可重複利用的知識。

給 AI 的專案規則怎麼寫？

專案規則檔應該簡短具體，寫下常用指令、程式碼慣例與禁止事項，並定期檢視；它是給 AI 的上下文，不是強制執行的規則。

Claude Code 官方文件說明，CLAUDE.md 與自動記憶都會在對話開始時載入，作為上下文；它們不是強制設定，內容越具體、越簡潔，AI 越可能遵守（Anthropic，Claude Code memory）。

適合寫進去的內容	不適合的內容
建置、測試與部署的指令	很長的背景故事
專案慣例與命名規則	容易過期的暫時狀態
明確的禁止事項與原因	相互矛盾的指示
重要文件的位置	需要強制執行卻只寫在文字裡的規則

需要強制執行的規則，例如禁止提交金鑰，仍然要用工具或審查機制確保，不能只靠文字提醒。

什麼情況不必寫這麼多？

一次性的小工具、不會再修改的原型，或只有一個人且短期使用的專案，不必完整寫齊四種紀錄，保留需求與重要決定就夠。

紀錄也有成本：寫了沒人讀、內容過期，反而造成誤導。我的原則是依照預期壽命決定：會被別人接手、會長期維護、牽涉資料與權限的專案，才需要完整的紀錄；用完即丟的小工具，只要留下它做什麼與怎麼用即可。

常見問題

Q寫這麼多文件，不是違反敏捷嗎？

不違反。敏捷宣言強調的是可用的軟體與持續的溝通，並沒有禁止文件；重點是寫有人會用到的文件，而不是為了合規而寫。

Q讓 AI 自己整理紀錄可以嗎？

可以，但需要人審閱。AI 能整理對話、草擬修改說明，但「為什麼這樣決定」的判斷，只有做決定的人最清楚。

QCLAUDE.md 寫了，AI 就一定會遵守嗎？

不一定。官方文件把它定位為上下文而不是強制設定，需要強制的規則要用其他機制確保。

Q敘事備忘錄適合小團隊嗎？

亞馬遜的做法是一家大公司的選擇，沒有證據顯示適用於所有團隊。小團隊可以借用它的精神：重要決定先寫成完整的段落，再開會討論。

Q該從哪一種紀錄開始？

先從需求規格開始，因為它同時是 AI 的輸入，也是驗收的依據。有餘力再補決策理由與專案規則。

資料來源與說明

架構決策紀錄引自 Michael Nygard 的原文，敘事備忘錄引自亞馬遜 2017 年股東信，上下文工程與專案規則檔引自 Anthropic 官方公開文件，測試驅動開發引自 Martin Fowler 的說明，敏捷原則引自敏捷宣言官方網站，查閱日期為 2026 年 10 月 19 日。四種紀錄的分類、寫法建議與不適用情況，是我的整理，沒有經過大規模驗證。

參考資料

Michael Nygard，〈Documenting Architecture Decisions〉，Cognitect，2011 年 11 月 15 日，存取日期：2026 年 10 月 19 日。
Amazon，〈2017 Letter to Shareholders〉，2018 年發布，存取日期：2026 年 10 月 19 日。
Anthropic，〈Effective context engineering for AI agents〉，2025 年 9 月 29 日，存取日期：2026 年 10 月 19 日。
Anthropic，〈How Claude remembers your project〉，現行文件，存取日期：2026 年 10 月 19 日。
Anthropic，〈Best practices for Claude Code〉，現行文件，存取日期：2026 年 10 月 19 日。
Martin Fowler，〈Test Driven Development〉，現行頁面，存取日期：2026 年 10 月 19 日。
Agile Manifesto，〈Principles behind the Agile Manifesto〉，現行頁面，存取日期：2026 年 10 月 19 日。

關於作者

Claire Chang ｜企業 AI 導入與流程轉型顧問。專注於 AI Agent 架構設計、ERP 系統整合與企業 AI 治理。

首次發布：2026-10-19