第十日：黃金守則出爐，挑選・壓縮・多專家大法

一、開場：從「文件山」到「黃金守則」

昨天還在講「Context Engineering 的三板斧」：挑選、壓縮、多專家模式。今天一睜眼，桌面上就多了一大堆檔案——需求文件、API YAML、ERD、架構圖、測試腳本…
看著這些檔案，我突然覺得自己像個在資訊考古現場的工程師，挖到一堆石碑，現在要刻在說明書裡，讓未來的工程師（或 AI 小幫手）能看得懂。

於是我召喚了 Codex，請它幫忙整理，導出一份「expose_doc」，目標是產出一份能讓其他 Agent 快速上手的說明集 。

這一整天的任務，就像是在文件工地裡打磨磚瓦，最後提煉出一套 「AI 協作的黃金守則」。

二、第一步：挑選（Selection）

光是 README、Requirement、API 規格、ERD、Architecture 幾個文件，就已經能把新手淹死。
挑選就是要從「文件山」裡，抓出最有價值的部分，其他的先收進倉庫。今天的挑選重點有三個：

1. 產品範圍與功能矩陣
   Requirement 文件清楚定義了核心功能：通知發送、目的地管理、Bot 管理、CRUD 基本資源，還有計費、排程、重試等未來功能。
   光這一張表，就能馬上告訴任何新加入的 AI 工程師：「什麼有、什麼沒、什麼還在畫餅。」

2. API 快速對照表
   OpenAPI 與 API_README 提供的「快速參考」表格，把 POST /companies、POST /projects、POST /destinations、POST /notifications 串起來，馬上可以走完 Happy Path。
   這比長篇大論更重要，因為新手只要能跑通一輪，就會覺得「啊，原來這系統是真的活著」。

3. 資料模型與 ERD
   ERD 裡面把 companies → users → projects → destinations → notifications 的關聯一口氣講清楚。
   雖然有些 FK 沒強制（像 created_by），但這對快速理解邏輯已經夠用了。

👉 這就是挑選：從 100 頁文件裡，先抓出那 3 張「最關鍵的地圖」。

三、第二步：壓縮（Compression）

光有挑選還不夠，因為文件還是太厚。這時就要壓縮，把長篇贅述濃縮成「一口氣看懂」的精華。

壓縮成果：

• 架構總覽
  架構文件其實寫得很完整：Entry point、HTTP server、Middleware、Handlers、Services、Repositories… 全部分層解釋。
  但我壓縮後的版本只有一句話：
  👉 「這是一個典型 Go 三層架構：Gin Handler → Service → Repository → Postgres，外加 Bot Webhook 和 Provisioning Beta。」

• 流程圖壓縮
  原本的通知流程有整頁的文字序列圖，我壓縮後的版本：
  👉 「POST /notifications → 驗證 → 寫 DB → BroadcastService → Teams → 回傳 202。」
  （一句話勝過一張 A4。）

• 測試腳本壓縮
  test_api.sh 本來有一堆顏色輸出、jq 判斷，我壓縮成三行：
  👉 「檢查健康 → 建立公司 → 建立目的地 → 發送通知 → 回傳結果。」
  （外加一個黃金提示：沒設定 PROJECT_ID 就別想測試。）

這樣一壓縮，新人只要三分鐘，就能把系統主軸摸清楚。

四、第三步：多專家模式（Multi-Agent）

挑選 + 壓縮之後，還剩一個關鍵：多專家模式。
因為文件不是只給人看的，也是要給 AI 協作者看的。

想像一下：未來我們有三個 AI Agent：

• Doc Agent：專門讀需求文件、API 規格。
• Test Agent：專門生成測試案例，跑 smoke script。
• Code Agent：專門幫忙補齊 handler、service、repository。

這三個 Agent 如果都看同一份大文件，保證會「Lost in the Middle」。
但如果我們把文件拆好：Doc Agent 看 Requirement、Test Agent 看 TEST_README、Code Agent 看 API YAML，那就能各司其職。

今天產出的 expose_doc，其實就是往這個方向走：一份濃縮、分門別類的文件集，正好適合多 Agent 協作。

五、黃金守則提煉

總結今天的過程，我整理出一份「AI 協作黃金守則」：

1. 挑選最小可行文件

   • 需求矩陣、API Cheat Sheet、ERD。
   • 其他文件可選擇性放入，避免淹死。

2. 壓縮成一口氣懂的摘要

   • 架構一句話版本。
   • 流程一句話版本。
   • 測試三行版本。

3. 多專家分工

   • Doc Agent：讀需求。
   • Test Agent：生測試。
   • Code Agent：補程式。
   • Lead（我）：做裁判，避免三個 AI 吵架。

4. 保持與程式同步

   • OpenAPI 要和 Handler 同步。
   • Requirement 要和實作一致。
   • ERD 要和 schema.sql 對齊。

5. 日誌與錯誤案例收斂

   • 把每天的 log 壓縮成「今天完成了 A → 結果是 B」。
   • 不要丟原始 5000 行對話給 AI，那只會燒錢。

六、今日心得：從「文件地獄」到「文件淨土」

今天最大的收穫，不是又多了一份 README，而是終於把文件整理成「AI 可以看、人也能懂」的格式。
以前的我看到一堆 md、yaml、sh 就頭痛，今天的我看到 expose_doc 反而有種安心感。

因為這代表：

• 明天如果有新的 AI Agent 加入，它不會亂跑。
• 明天如果我換個人來維護，他不會馬上辭職。
• 明天如果我再也不想看這專案… 至少文件能幫我撐場面。

一句話總結：
👉 文件不是累贅，而是 AI 協作的燃料。

七、展望明天

明天，我要把這套「黃金守則」拿去實測：

• 用 Test Agent 生成更聰明的 smoke test。
• 用 Code Agent 幫忙補幾個缺的功能（像是重試策略）。
• 用 Doc Agent 幫忙維護文件。

讓我們看看，這套 挑選・壓縮・多專家模式，能不能真的讓工程效率翻倍。

✍️ Day10 收工感言：
今天不是在寫程式，而是在煉文件。煉到最後，我煉出了一套「黃金守則」。
未來，AI 工程工地就靠它來打地基了。 🚀