RoyalMilkteaMaster Milktea Skills Grill Architecture
確認「如何在現有專案中完成需求」。需求未核准時停止。
流程
- 讀取
docs/planning/requirements.md、專案指令、程式庫、CONTEXT.md與相關 ADR。 - 必讀
references/project-structure-style.md；確認 Code、Data、Runtime 根目錄與框架例外。 - 先依已確認需求與專案資訊判斷是否符合下列正式 Log 啟用條件；判斷明確時直接記錄結論與簡短理由，不再詢問。使用者已有明確決定時遵循該決定。資訊不足時才訊問一次以下問題，不得拆成三題:「這個專案會不會有以下任一情況：① 背景 Worker 或排程；② 長時間無人看守的程式；③ Web API 或多人使用系統？如果有，我們才建立正式 Log 系統；如果都沒有，就不建立，以維持系統精簡。」全部為否時，不讀 Logging 參考文件，記錄「正式 Log：不需要」，使用 Console 與
milktea-skills-debug的臨時 Debug Log；任一為是時，才讀取references/logging-architecture-style.md並確認正式 Logging 方案。 - 查清現有資料結構、資料流、模組責任、公開介面與測試模式。
- 列出已知架構限制、使用者的實作偏好與未決技術決策。
- 依相依順序一次確認一個決策，附推薦、理由與主要代價。
- 發現需求衝突時退回需求階段，不自行修改需求。
- 摘要架構並取得使用者核准；把完整核准內容寫入
docs/planning/architecture.md。新術語、關係或歧義才更新CONTEXT.md；重大決策依規則寫入 ADR。
既有 architecture.md 只更新本次核准範圍，保留未受影響內容。
架構面向
- 資料是什麼、由誰擁有、如何流動與修改。
- Code、Data、Runtime 根目錄及其邊界。
- 新檔案的唯一位置、命名與目錄責任。
- 受影響模組及其責任。
- 公開介面、Schema、API contract 與系統整合。
- 錯誤處理、安全、效能與資源限制。
- 是否需要長期保存正式 Log；只有符合啟用條件時才設計 Logger、檔案、輪替與清理。
- 遷移方式、向後相容與回復策略。
- 最高且既有的測試接縫；必要時才新增接縫。
- 可獨立驗證的交付邊界。
推薦標準
- 符合核准需求與專案既有規則。
- 不破壞既有使用方式，且可實際驗證。
- 優先沿用既有資料結構、模組與測試接縫。
- 以最小方案完整解決問題。
- 架構清楚、可讀、簡潔、可維護。
- 不為假想需求增加抽象、依賴或擴充點。
- 新專案預設採用結構偏好；既有專案的差異必須說明，不擅自大搬家。
資訊不足時說明缺口，不假裝有最佳答案。
ADR
同時符合下列條件時，建議建立 ADR，由使用者決定是否寫入：
- 日後難以逆轉或更換成本高。
- 只看程式碼無法理解原因。
- 曾在多個合理方案間取捨。
寫入 docs/adr/NNNN-名稱.md。寫入時才建立目錄，只寫背景、決策、理由與主要後果。
摘要格式
# 核准架構與資料流
- Code Root：
- Data Root：
- Runtime Root：
- 正式 Log：不需要／需要（理由與方案）
- 目錄與命名：
- 資料與所有權：
- 資料流：
- 模組責任：
- 介面與 Schema：
- 整合與依賴：
- 相容與遷移：
- 測試接縫：
- 驗證邊界：
- ADR：無／條列
- 未決事項：無／條列
完成條件
- 所有會影響實作的架構決策皆已確認或明確延後。
- 已確認是否需要正式 Log；不需要時沒有加入 Logging 建置工作。
- 核准架構與資料流已寫入
docs/planning/architecture.md。 CONTEXT.md只新增已確認的專有名詞、關係與歧義。- 使用者的實作方法已驗證、修正或拒絕，並說明依據。
- 測試接縫與驗證邊界明確。
- 使用者核准架構摘要。