# Milktea Skills Grill Architecture

> 根據已核准需求、現有程式庫與 Milktea 專案結構偏好，以繁體中文逐一確認 Code／Data／Runtime 根目錄、資料流、模組責任、介面、Schema、整合、相容性與測試接縫。由 milktea-skills-grill-me 在架構階段調用，或在使用者要求深入釐清技術設計時使用；不改需求、不寫規格、不實作。

- Skill: `royalmilkteamaster/milktea-skills-grill-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add royalmilkteamaster/milktea-skills-grill-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/royalmilkteamaster/milktea-skills-grill-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: RoyalMilkteaMaster (https://skillmd.com/u/royalmilkteamaster)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/royalmilkteamaster/milktea-skills-grill-architecture

---


# Milktea Skills Grill Architecture

確認「如何在現有專案中完成需求」。需求未核准時停止。

## 流程

1. 讀取 `docs/planning/requirements.md`、專案指令、程式庫、`CONTEXT.md` 與相關 ADR。
2. 必讀 `references/project-structure-style.md`；確認 Code、Data、Runtime 根目錄與框架例外。
3. 先依已確認需求與專案資訊判斷是否符合下列正式 Log 啟用條件；判斷明確時直接記錄結論與簡短理由，不再詢問。使用者已有明確決定時遵循該決定。資訊不足時才訊問一次以下問題，不得拆成三題:「這個專案會不會有以下任一情況：① 背景 Worker 或排程；② 長時間無人看守的程式；③ Web API 或多人使用系統？如果有，我們才建立正式 Log 系統；如果都沒有，就不建立，以維持系統精簡。」全部為否時，不讀 Logging 參考文件，記錄「正式 Log：不需要」，使用 Console 與 `milktea-skills-debug` 的臨時 Debug Log；任一為是時，才讀取 `references/logging-architecture-style.md` 並確認正式 Logging 方案。
4. 查清現有資料結構、資料流、模組責任、公開介面與測試模式。
5. 列出已知架構限制、使用者的實作偏好與未決技術決策。
6. 依相依順序一次確認一個決策，附推薦、理由與主要代價。
7. 發現需求衝突時退回需求階段，不自行修改需求。
8. 摘要架構並取得使用者核准；把完整核准內容寫入 `docs/planning/architecture.md`。新術語、關係或歧義才更新 `CONTEXT.md`；重大決策依規則寫入 ADR。

既有 `architecture.md` 只更新本次核准範圍，保留未受影響內容。

## 架構面向

- 資料是什麼、由誰擁有、如何流動與修改。
- Code、Data、Runtime 根目錄及其邊界。
- 新檔案的唯一位置、命名與目錄責任。
- 受影響模組及其責任。
- 公開介面、Schema、API contract 與系統整合。
- 錯誤處理、安全、效能與資源限制。
- 是否需要長期保存正式 Log；只有符合啟用條件時才設計 Logger、檔案、輪替與清理。
- 遷移方式、向後相容與回復策略。
- 最高且既有的測試接縫；必要時才新增接縫。
- 可獨立驗證的交付邊界。

## 推薦標準

1. 符合核准需求與專案既有規則。
2. 不破壞既有使用方式，且可實際驗證。
3. 優先沿用既有資料結構、模組與測試接縫。
4. 以最小方案完整解決問題。
5. 架構清楚、可讀、簡潔、可維護。
6. 不為假想需求增加抽象、依賴或擴充點。
7. 新專案預設採用結構偏好；既有專案的差異必須說明，不擅自大搬家。

資訊不足時說明缺口，不假裝有最佳答案。

## ADR

同時符合下列條件時，建議建立 ADR，由使用者決定是否寫入：

- 日後難以逆轉或更換成本高。
- 只看程式碼無法理解原因。
- 曾在多個合理方案間取捨。

寫入 `docs/adr/NNNN-名稱.md`。寫入時才建立目錄，只寫背景、決策、理由與主要後果。

## 摘要格式

```markdown
# 核准架構與資料流

- Code Root：
- Data Root：
- Runtime Root：
- 正式 Log：不需要／需要（理由與方案）
- 目錄與命名：
- 資料與所有權：
- 資料流：
- 模組責任：
- 介面與 Schema：
- 整合與依賴：
- 相容與遷移：
- 測試接縫：
- 驗證邊界：
- ADR：無／條列
- 未決事項：無／條列
```

## 完成條件

- 所有會影響實作的架構決策皆已確認或明確延後。
- 已確認是否需要正式 Log；不需要時沒有加入 Logging 建置工作。
- 核准架構與資料流已寫入 `docs/planning/architecture.md`。
- `CONTEXT.md` 只新增已確認的專有名詞、關係與歧義。
- 使用者的實作方法已驗證、修正或拒絕，並說明依據。
- 測試接縫與驗證邊界明確。
- 使用者核准架構摘要。