SOP：分層領域架構

當代理持續破壞邊界、在不同層重複邏輯，或幾輪工作階段後產出的程式碼變得難以審查時，就使用這份 SOP。

目標

把領域邊界寫得足夠明確，讓代理能快速推進，同時不會悄悄破壞結構。

目標模型

在單一業務領域內，優先採用這條單向流程：

Types -> Config -> Repo -> Service -> Runtime -> UI

橫切關注點應透過明確的 provider 或 adapter 進入。共用 utils 應留在領域之外，不要累積領域邏輯。

建置檢查清單

• 在 ARCHITECTURE.md 中定義目前的領域。
• 在 ARCHITECTURE.md 中寫出允許的相依方向。
• 記錄 auth、telemetry、外部 API 等橫切介面。
• 針對目前最難處理的邊界違規，補上一則簡短說明。
• 決定哪些規則要用 lint、測試或腳本做機械化約束。

執行 SOP

1. 在調整實作風格前，先把程式碼庫畫分成各個領域。
2. 針對每個領域，定義允許的層級順序。
3. 找出所有橫切關注點，並把它們導向 provider 或 adapter。
4. 把界線不明的共用邏輯移回負責的領域，或改成真正通用的 utils。
5. 把規則寫進 ARCHITECTURE.md。
6. 針對代價最高的違規類型，加入一條可執行的護欄。
7. 完成後更新品質評分。

完成定義

• 新接手的代理能判斷一個變更屬於哪一層。
• UI 程式碼不再直接觸及 repo 或外部副作用。
• 橫切關注點都有具名入口。
• 至少有一條重要邊界已透過機械方式強制執行。

需要更新的儲存庫工件

• ARCHITECTURE.md
• docs/QUALITY_SCORE.md
• 設計理由改變時更新 docs/design-docs/
• docs/PLANS.md 或目前啟用中的執行計畫