精煉重點 1：沒有沉澱的知識＝團隊的短期記憶，隔天就失憶。
精煉重點 2：把「問 AI 的成本」變成一次寫好、處處可用的「知識資產」。

⸻

貝老闆：「嘿嘿，今天我又用 AI 問了『 staging 跟 production 的環境變數差在哪』，它回答得超詳細！」

小可：「老闆，上週你也問過……而且 King 問過兩次。大家問法不同，答案也不同，文件裡找不到統一說法。」

King 工程師（皺眉）：「我上次把 OAUTH_REDIRECT_URI 口頭改了，結果 AI 實習生還照舊產檔。因為沒有決策紀錄， PR 也找不到依據。」

AI 實習生：「完美！我已經更新 OAUTH_REDIRECT_URI! 您說得太對 …… 昨天的討論在哪裡讓我找找看？」

貝老闆：「那就丟到 Notion？還是 Confluence？還是建一個 file？」

小可：「重點不是放哪，是有沒有『會被找到』。現在是大家重覆問同一題，還以為在做知識管理。」

（小可撥通電話）

好威：「你們缺三樣東西：ADR 決策紀錄、內部知識庫、還有能讓 AI 看懂脈絡的 Context Engineering。把『問過什麼、為何這樣決定、之後怎麼問 AI』一次寫清楚，嵌到 repo 的 README、/docs、claude.md，就不會每次重來。」

概念拆解

1）ADR 決策紀錄：把「當下討論」變「可追溯依據」

為什麼要做： ADR（Architecture/Decision Record）是把一次決策的背景、選項與取捨記下來，讓後人知道「為什麼不是別的選擇」。沒有 ADR，口頭共識會在下一次發版被推翻，AI 也無法根據歷史脈絡回答一致。
怎麼做： 每個重大變更或爭議點寫一份 docs/adr/2025-08-18-redirect-uri.md，內容包含 Context／Options／Decision／Consequences／Links。開 PR 時把 ADR 一起審，決策生效才合併。
與 AI 合作： 把會議逐字稿丟給 AI，請它先草擬 ADR，並要求列出 3 個替代方案與風險，最後由人類修訂與拍板。

小範例：

# ADR: OAuth Redirect URI 政策
- Context：不同環境值不一致導致登入錯誤。
- Options：A. 單一通用 URI；B. 依環境分離；C. 反向代理統一入口。
- Decision：採 B，統一定名規則並納入 .env.example。
- Consequences：部署文件需更新；測試新增 2 條驗證。
- Links：PR #214、Runbook Login-001。

2）內部知識庫：File vs Notion vs Confluence 的混搭術

為什麼： 工程貼身知識（變數、腳本、執行手冊）放 repo 才能跟版本一起變動；跨部門流程（採購、排程、客訴）適合放 Notion／Confluence 做協作與審批。
怎麼選： 小團隊先用 Git 內的 /docs 為主、雲端 Wiki 為輔。在 README 放「知識地圖」，列出入口與搜尋關鍵字；在 Wiki 建資料庫（DB）型頁面，欄位含 System、Tag、Owner、Last‑Updated。
與 AI 合作： 定期把 /docs 與 Wiki 的目錄、摘要交給 AI，請它比對缺漏並生成「本週文檔差異清單」。

3）Context Engineering：讓 AI 回答變「有記憶」

為什麼： 同一題不同上下文會得到不同答案。建立固定的系統提示（System Prompt）、 Style Guide、 JSON Schema、環境表（.env.example）等，讓 AI 每次都有同樣基準。
怎麼做： 在 repo 放 claude.md／gpt.md，內含：專案目標、技術堆疊、路由/資料模型、常見約束（時區、幣別、權限）、輸出格式與範例。把「關鍵 Prompt」沉澱成 Cookbook：如「產生 ADR」、「寫 PRD」、「寫 Test Plan」。
與 AI 合作： 要求 AI 回答前先列「假設」，回答後附「寫回哪些文件」的建議清單，減少遺漏。

4）可檢索化：找得到比寫得到更重要

為什麼： 寫了卻找不到＝沒寫。
怎麼做： 檔名標準化（{日期}-{主題}-{系統}.md）、在每份文首加 YAML Front‑Matter（owner、tags、last_updated）、 PR 模板加入「Docs Impact」、「ADR Link」。 Slack 用固定 emoji 代表「要寫回文件」，每週例會清空待補清單。
與 AI 合作： 讓 AI 先產生文件索引與 Tag 建議，再用它幫忙寫搜尋 Query（例如 ripgrep／ Notion Filter）提高命中率。

5）流程落地：把知識當成交付件

為什麼： 沒有節奏，一周就回到混亂。
怎麼做：
• 每日站會前 5 分鐘：看「昨日變更 ➜ 需要 ADR/Docs 嗎？」
• 每個 PR：勾選 Docs/ADR checklist；無則說明理由。
• 每週 Demo：除了功能，也 Demo 新增的手冊與 Cookbook。
• 每月輪值「知識管家」：審視過時文件、提醒歸檔。

Takeaways

A. 先把決策寫成 ADR，再寫程式。
給 AI 的問法：

「以下是我們在 Slack 的討論紀錄，請產生一份 ADR 草稿，欄位含 Context/Options/Decision/Consequences/Links；列出至少 3 個選項與各自風險，最後給我 5 行版摘要好放在 PR 描述。」

AI 先幫你把雜訊收斂成結構化文件，工程決策有依據，之後遇到爭議可以直接引用，降低來回溝通成本。

B. 讓知識「貼著程式走」，Wiki 做協作與審批。
給 AI 的問法：**

掃描我 repo 的 docs/、README 與 /.env.example，產出一份『知識地圖』與缺漏清單；再生成 Notion DB 欄位建議（含 Tag、Owner、Last‑Updated、System、Link）。

程式變了文件就變，不會出現 Wiki 與實作脫鉤；而 Wiki 裡保留跨部門流程與審批紀錄，權責清晰。

C. 用 Context Engineering 固定回答品質。
給 AI 的問法：

依下列專案說明與 Style Guide，為『產生 API 規格』建立一份 Prompt Cookbook，包含：輸入欄位、驗收規則、常見陷阱、輸出 JSON Schema 與範例。

讓 AI 每次在同一條軌道上輸出，團隊不再因措辭差異拿到不同品質的回覆。

D. 把『寫回文件』內建進工作流。
給 AI 的問法：

根據這次修復登入錯誤的 PR，幫我生成：
1) ADR 更新項目 
2) Runbook 變更段落 
3) 測試用例補充清單，並附相對應文件路徑。

讓修補動作自帶文件更新，避免『修好了，但沒人知道為什麼』的知識黑洞。

E. 以搜尋為先：命名、標籤與索引。
給 AI 的問法：

為這 30 份歷史文件推薦一致的檔名、Tag 與 YAML Front‑Matter；再產生 ripgrep 與 Notion 的搜尋語句，確保 3 秒內能定位。

統一命名與標籤，搭配可複製的搜尋語句，縮短『知道有東西但找不到』的時間損耗。

放進專案的最小落地包（SOP）
這可以根據你用的工具調整，這之後可以在別的章節討論

• docs/adr/：用模板記錄每次決策；PR 強制連結。
• docs/runbook/：常見操作與故障排除（含環境變數表）。
• claude.md／gpt.md：System Prompt、Style Guide、JSON Schema、Cookbook 範例。
• README：知識地圖 + 搜尋指引；連到 Notion/Confluence 的總入口。
• /.env.example：所有環境變數與說明，PR 改動需審。

今日提問

你們團隊最近一次「重覆問同一題」是什麼？那段對話的結論，能不能先用 ADR 寫下來，再回頭補文件與 Cookbook？