FSWP 架構師 是做什麼的？
在此階段結束並產出經批准的 PRD 或變更摘要之前，不得撰寫任何程式碼。目標：在一輪問題和一則可供審查的文件中做出所有決定，杜絕後續來回溝通。
步驟 0：工作類型與分類
- 從
fswp-developer/references/work-types.md確認工作類型：新外掛、新主題、更新、附加元件、核心修補。 - 更新、附加元件、核心修補，或任何未知的程式碼庫： 先執行
python3 scripts/detect_wp_project.py <路徑>。它會回報專案類型（外掛、主題、區塊主題、Core 簽出版本、網站、未知）、主要檔案與標頭欄位、版本與最低版本提示、工具鏈（Composer、npm、PHPCS、PHPStan、測試），以及找到的鉤子/REST 路由/區塊。將發現結果引用到計劃中。此腳本僅讀取檔案。 - 即使未包含「外掛」或「主題」等字詞，只要請求涉及外掛或主題形狀（如文章類型、REST 整合、管理儀表板、自訂範本、全站樣式、任何需要啟用或解除安裝行為的內容），仍計入此類。作為 FluentSnippets 檔案提供的單一 shortcode 工具則屬於
wordpress-mini-app-builder，而非此處。
步驟 0a：尚無 PRD
若使用者要求開始建置，但尚無 PRD 或變更摘要：請要求他們先提供，再開始進行。請勿開始實作，也請勿直接跳到步驟 1。若使用者明確堅持（「直接建置就好」、「跳過 PRD」），則可免除該要求：直接跳到步驟 1，並根據該問題輪次撰寫文件。
步驟 0b：使用者提供的 PRD、AGENTS.md、架構文件
在撰寫程式碼前，請閱讀這些文件，並根據 fswp-plugin-developer/references/standards.md 及其他內部規則進行檢查。
- 無實際衝突： 使用提供的文件加上內部標準繼續進行；內部規則填補缺口。
- 實際衝突（文件要求某項內部規則禁止的事項，例如安全性捷徑或命名方案）：明確列出雙方觀點，並詢問應遵循哪一方。切勿悄悄將其混合。
- 提供的 PRD 仍需經過步驟 4，並無豁免。
步驟 1：一輪關鍵問題
在可用時使用結構化問題工具（Claude Code：AskUserQuestion；claude.ai：ask_user_input_v0）；否則使用一份精簡的編號列表。最多 3-4 個問題，依工作類型選擇：
| 工作類型 | 詢問內容 |
|---|---|
| 新外掛 | 發布目標（WordPress.org、私有 zip、兩者）；功能範圍（文章類型、自訂資料表、REST、排程、管理畫面、前端輸出）；前端設計系統（如果有的話，使用使用者的系統，或中性的）；靜態與動態行為；此專案的程式碼前綴/縮寫 |
| 新主題 | 區塊主題或傳統主題；發布方式（WordPress.org 主題目錄、私有、客戶網站）；起點（從頭開始、作為現有主題的子主題）；需要哪些內容類型和頁面版面；此專案的程式碼前綴/縮寫 |
| 更新 | 目標（錯誤修正、新功能、相容性、重構）；交付方式（對儲存庫的修補、zip、直接編輯）；哪些內容不得更改 |
| 附加元件 | 主產品及其支援的版本範圍；附加元件新增了什麼；主產品遺失時應如何處理 |
| 核心修補 | 工單編號或錯誤描述；目標元件；是否已有 Trac 工單 |
所有開放式問題（欄位名稱、業務規則、邊緣情況、工作名稱）都會被推斷出來，並列在 PRD 的「假設」部分下，而非提出來問。除非第一輪問題的答案產生了真正需要分叉的阻擋性情況，否則不會進行第二輪。
前綴/縮寫： 對於新外掛和新主題工作，詢問專案程式碼應使用哪個簡短縮寫或前綴；如果使用者沒有，則從專案名稱推導出 2-3 個候選項供其選擇。沒有內建預設值，也絕不使用此工具本身的名稱或品牌作為替代。完整規則、確切的問題措辭以及例外情況（主題的 4 字元最小長度、產品 slug 與程式碼前綴、保留名稱）：請參閱 fswp-developer/references/brand-naming.md。絕對不要使用 WP 或 Plugin 作為前綴。對於更新和附加元件工作，則不詢問；保留專案現有的前綴。預設最低版本：WordPress 6.4、PHP 7.4；只在有特定需求時才提高（例如為了使用列舉而要求 PHP 8.1）。在必要時，請查閱官方文件以確認當前需求。
專案資訊（同一輪，絕不進行第二輪）： 公司名稱、產品名稱、作者、貢獻者，以及連結（網站、文件、支援、儲存庫）。僅詢問尚未說明的部分。切勿發明缺失的值：未說明的連結或貢獻者將在所有生成的檔案中省略。
技術堆疊決策： 對於新工作，在起草 PRD 之前決定管理 UI 層級和 JS 層級（請參閱 fswp-plugin-developer/references/standards.md 第 2 節）。對於現有工作，除非有明確理由更改，否則保留現有堆疊。
步驟 2：競爭者研究
該類別中的 2-3 個主要產品（WordPress.org 目錄或 SaaS）。記錄基本必備功能、常見抱怨以及值得遵循的慣例。進行少量搜尋；在文件中列出 3-5 條要點。核心修補則跳過此步驟；改為研究工單歷史。
步驟 3：文件
- 新外掛、新主題： 使用
references/prd-template.md中的 PRD 範本（內含主題變體說明）。 - 更新、附加元件： 使用
references/change-brief-template.md中的變更摘要範本：目前行為、要求行為、功能對照清單（必須保持正常運作的事項）、相容性表格、風險、測試計劃。 - 核心修補： 使用
references/change-brief-template.md中的工單優先摘要，加上fswp-core-contributor中的步驟。
將前端行為透過 JS 層級檢查清單（fswp-plugin-developer/references/frontend-output.md）的 5 點進行評估，並說明其層級。衍生計數（token、區塊、路由、畫面） 必須來自資料或程式碼，而非來自記憶。
步驟 4：審查關卡（唯一的一個）
呈現文件。決策已明確且已做出；使用者一次性批准或修正。如果 JS 層級是 Alpine，請說明並獲得明確同意。在批准之前，不得進行任何骨架或編輯；批准的修正會先被納入。
遷移模式
用於在新堆疊上重建現有外掛。在進行任何程式碼變更之前：
- 基線： 為每個畫面與狀態截取螢幕截圖，並從舊版本匯出參考資料（設定、資料、生成的檔案）。儲存在
baseline/目錄下。 - 功能對照矩陣： 將每個舊功能、設定、鉤子、shortcode、REST 路由與儲存選項，對應到：保留 / 變更（理由） / 捨棄（理由）。未列出的內容不得悄悄傳入。
- 匯出差異比對： 重建後，重新生成相同的匯出項目，並與基線進行比對。差異必須是蓄意的並已列出。
- 視覺回歸關卡： 將新的螢幕截圖與每個畫面的基線進行比較；未解釋的差異將阻止交付（提供給
fswp-qa-engineer）。 - 資料路徑： 從舊版本儲存資料進行的升級必須在不重新啟用的情況下運作（請參閱
fswp-qa-engineer）。
步驟 5：交接文件（多階段建置）
當建置將跨越多個階段時，請將以下兩個檔案寫入外掛儲存庫的根目錄（而非 zip）：
AGENTS.md：這是什麼；指令（建置、測試、QA 關卡）；架構圖；內部規則與慣例；決策與限制；雷區與禁止觸碰區；完成的定義。HANDOFF.md：當前狀態；程式碼對應（檔案：職責）；已驗證 / 未驗證表格（每個 PRD 情境，附上 PASS / FAIL / NOT RUN 及證據）；待辦事項；下一步。
在每次暫停時更新兩者，並且在結束任何尚未完成的階段之前。