情境背景

你的電商平台跑了三年，原本的單體（monolith）已經長到 50 萬行，每次改動都會牽動三個以上不相關的模組。團隊決定把「訂單」「庫存」「使用者」拆成三個獨立服務，但這個工作超過單一 agent session 能安全容納的規模，且前進路徑上還有多個架構決策待解。

/wayfinder 是設計來處理這類大型工作的工具。它不會直接動手寫程式，它會把工作拆成 issue tracker 上的共享決策 tickets，團隊逐一解決，直到實作路徑清楚。

第 1 步：定義目標並識別決策點

目標：把模糊的「拆服務」收斂成可識別的決策點

/wayfinder 第一個動作是確認最終目標，然後找出需要做出決策的關鍵點。每個決策點會對應一張 ticket。

AI 對話：

• You:

  /wayfinder
  我們要從單體電商拆出訂單、庫存、使用者三個獨立服務，目標是各服務可獨立部署、獨立擴縮。

• AI:

  收到。這是個大型工作，超過單一 session 容納。我識別到的決策點：

  1. 拆分策略：是大爆炸重構，還是漸進式 strangler fig？
  2. 服務邊界：訂單服務的職責到哪？付款邏輯算訂單還是獨立服務？
  3. 資料庫策略：共享資料庫、每服務獨立 schema、或每服務獨立 DB instance？
  4. 服務通訊：同步 REST、非同步 message queue、或混合？
  5. 資料一致性：跨服務交易用 saga、outbox pattern、或最終一致？

  我會把每個決策點建成一張 ticket，標好阻塞邊。

第 2 步：建立共享決策 tickets

目標：理解 ticket 之間的依賴關係

/wayfinder 建立的 tickets 會在 issue tracker 上建立，並標明阻塞邊。阻塞邊的呈現方式取決於你的 tracker（在 setup 時決定），可能是 GitHub issue 的 linked issue，或本機檔案裡的文字。

AI 對話：

• AI:

  共享決策 tickets 已建立：

  Ticket #101：決定拆分策略

  • 阻塞邊：無
  • 描述：選擇大爆炸重構或漸進式 strangler fig

  Ticket #102：劃分服務邊界

  • 阻塞邊：#101
  • 描述：定義訂單、庫存、使用者各服務的職責與邊界

  Ticket #103：選擇資料庫策略

  • 阻塞邊：#102
  • 描述：決定共享、獨立 schema、或獨立 DB instance

  Ticket #104：決定服務通訊模式

  • 阻塞邊：#102
  • 描述：REST、message queue、或混合

  Ticket #105：選擇資料一致性方案

  • 阻塞邊：#103, #104
  • 描述：saga、outbox pattern、或最終一致

  Ticket #106：研究既有 schema 的外鍵依賴

  • 阻塞邊：#102
  • 描述：AFK 共享阻塞項，會啟動 /research 子代理

  檔案位置：docs/wayfinder/2026-08-monolith-to-services/

第 3 步：理解「研究 ticket」的角色

目標：知道為什麼有些 ticket 是 AFK 共享阻塞項

Ticket #106 是特殊類型：research ticket。charting session 會為這類 ticket 啟動 /research 子代理，平行燒掉所有調查工作，把發現捕獲在 research/<name> 拋棄式分支上。

意思是調查不需要你親自做，agent 會在背景跑，跑完把附引用的 Markdown 放在約定位置。你的角色是讀研究結果，用結果驅動 #103 與 #104 的決策。

第 4 步：逐一解決 ticket

目標：理解 ticket 的狀態機

每張 ticket 走過同樣的狀態機：New → Triage → In Progress →（需要資訊則追問後回到 In Progress，否則 Review）→ Approved / Needs Revision → Closed。

AI 對話（解決 Ticket #101）:

• You:

  開始解決 #101。

• AI:

  Ticket #101：拆分策略

  選項：

  • 大爆炸重構：凍結功能開發 3 個月，一次拆完。風險高、回不去。
  • 漸進式 strangler fig：保留單體運作，新功能寫到新服務，舊功能逐步遷移。風險低、可隨時停止。

  團隊規模與部署頻率是什麼？

• You:

  團隊 8 人，每週部署。不能停止功能開發超過 1 週。

• AI:

  那大爆炸不適用。決策：漸進式 strangler fig。

  已記錄到 docs/wayfinder/2026-08-monolith-to-services/ticket-101.md，狀態 closed。下一步可解 #102。

第 5 步：理解阻塞邊的意義

目標：知道為什麼 ticket 不能亂順序解

阻塞邊是 /wayfinder 強制的順序。#103（資料庫策略）阻塞於 #102（服務邊界），因為你不知道服務邊界就無法決定每個服務要什麼資料。#105（一致性方案）同時阻塞於 #103 與 #104，因為一致性方案同時依賴資料庫與通訊模式。

如果你想跳過 #102 直接解 #103，agent 會提醒你這違反阻塞邊。這是設計，避免你解了後來被推翻的決策。

第 6 步：把 ticket 拆成交給 /to-tickets 與 /implement

目標：理解 wayfinder 與下游 skill 的分工

當所有決策 ticket 都 closed，路徑就清楚了。這時可以進入下一階段：

1. /to-tickets：把每個服務的實作拆成 tracer-bullet tickets，標好阻塞邊。
2. /implement：依序實作，每張 ticket 內部驅動 /tdd，最後以 /code-review 收尾。
3. /domain-modeling：在拆服務過程中，新詞（例如「訂單事件」「庫存預留」）要寫進各服務自己的 CONTEXT.md。

/wayfinder 不會自己跑這些下游 skill。它的責任只到「決策路徑清楚」為止。

何時不應該用 /wayfinder

• 小型任務：能在單一 session 內完成的工作直接用 /implement。
• 已經有明確執行路徑：路徑清楚就不必規劃，直接做。
• 不需要做出重要決策：執行性而非決策性的工作用 /to-tickets 拆 tickets 就好。

工具使用摘要

結果

• 拿到 6 張共享決策 tickets，標好阻塞邊，存於 docs/wayfinder/
• Ticket #101 已 closed，記錄選擇 strangler fig 的理由
• 知道 #106 是 research ticket，會自動觸發 /research 子代理在背景調查

關鍵學習點

• /wayfinder 把大型工作拆成共享決策 tickets，逐一解決直到路徑清楚。它不實作程式碼。
• 阻塞邊是強制的順序，違反會被 agent 提醒。這是設計，避免解了後來被推翻的決策。
• research ticket 是 AFK 共享阻塞項，會自動觸發 /research 子代理在背景平行調查。
• 路徑清楚後交給 /to-tickets 與 /implement，wayfinder 的責任只到決策路徑清楚為止。