vicunav/vicunav-transform-claude-to-gutenberg

Transformar Claude Code a Gutenberg FSE

Objetivo

將已批准的 Claude Code 專案轉換為一個原生、可維護的 WordPress 網站。保留已商定的設計、內容和行為，同時避免拖入前端原型中那些 WordPress 已提供可編輯區塊解決方案的架構。

將原始專案視為視覺和功能規格。僅在授權的 LocalWP 環境中工作。未經明確批准，不得修改生產環境，也不得刪除內容、Site Editor 自訂設定或本地資料。

收集最低限度的上下文

在編輯前確認或發現以下資訊：

• Claude Code 中已匯出或精煉的專案路徑；
• LocalWP 網站和目標主題的路徑；
• 構成已批准設計的提交、建置或確切狀態；
• 涵蓋的頁面、斷點、狀態和互動；
• 本地網站的實際 WordPress 和 PHP 版本；
• 目標是 1:1 對等、已批准的優化還是重新設計；
• 必須可從 WordPress 編輯的內容和整合；
• 外掛、自訂區塊、字型和資產授權的限制。

如果缺少會改變內容、架構、功能或設計的決策，請停止並要求提供。如果缺少可從文件系統、前端或本地網站恢復的數據，請進行檢查並記錄假設。

載入可重複使用的基礎

根據階段應用已安裝的官方技能：

• wp-project-triage：分類 WordPress 專案及其工具鏈；
• wp-block-themes：實作 theme.json、模板、模板部件、模式以及 FSE 樣式；
• wp-block-development：僅當某互動需要自訂區塊時使用；
• wp-wpcli-and-ops：使用 WP-CLI 檢查或更改內容和選項；
• unlazy（如已安裝）：針對規模較大的遷移（超過一個頁面，或任何將在沒有持續監督下報告為完成的工作）的結案紀律。請參閱下方「以閘道紀律關閉每個工作單元」。

首先確認目標版本。如果某個官方技能指向比 LocalWP 更新的 WordPress 版本，則僅使用相容的 API，並查閱官方文件以解決差異。

在適當時閱讀自有資源：

• source-contract.md：在凍結基準線和定義遷移合約之前；
• migration-manifest.md：在捕獲基準線或實施任何具有視覺影響的變更之前；
• translation-map.md：在決定 Gutenberg 架構之前以及翻譯每個元件期間；
• localwp.md：在操作網站或其資料庫之前；
• qa-checklist.md：在第一個可見區段之前，以及在宣告工作完成之前再次使用；
• upstream.md：在更新、審計或重新分發已重複使用的基礎時；
• templates/gates-fse-migration.md：在為某個頁面或區段開啟 $unlazy 時，作為要複製和填寫的初始分類帳，而不是從頭開始撰寫閘道。

執行流程

1. 讀取兩個專案中直接相關的本地指令、Git 狀態和文件。
2. 執行 scripts/audit_source.mjs <source-path> 並手動審查其發現。不要將啟發式報告視為架構決策。
3. 建立遷移清單，索引所有預期組合，並執行 scripts/validate_migration_manifest.mjs <manifest-path>。
4. 在乾淨環境中啟動原始前端，並在桌面、平板和手機上捕獲基準線，包括相關的互動狀態。
5. 建立遷移合約：頁面、區段、文案、資產、代碼記號、互動、資料來源、整合以及驗收標準。
6. 將可重複使用的代碼記號與局部幾何分離。將前者映射到 theme.json，並透過區塊、佈局和最少的語意類別來保留後者。
7. 設計 FSE 架構：模板、模板部件、模式、頁面內容，以及僅在必要時才設計的自訂區塊或外掛。
8. 首先實作一個代表性區段。在將模式擴展到網站其餘部分之前，比較前端和 Site Editor。
9. 逐頁、逐區段進行遷移。在整個實作過程中保持原始專案可見作為參考。如果 $unlazy 可用，在實作之前（而非之後），透過將 templates/gates-fse-migration.md 複製到該頁面或區段專屬的 GATES.md 來開啟一個工作單元。
10. 透過專案文件化的流程在 LocalWP 中安裝或啟用主題。以冪等方式建立或更新內容，同時保留現有內容。
11. 執行 scripts/validate_fse_theme.mjs <theme-path> 並修正所有錯誤。審查適用的警告。
12. 在前端和 Site Editor 中完成視覺、結構、編輯、響應式、無障礙和效能的 QA。
13. 透過 capture_visual_evidence.mjs、compare_visual_evidence.mjs 和 verify_visual_evidence.mjs 執行捕獲、比較和閘道；手動並排和重疊審查。對於每個至少有一個全出血區段的頁面，另外執行 scripts/verify_editor_frontend_parity.mjs（需要一個使用 scripts/wp_auth_cookies.php 生成的真實會話 cookie，請參閱 translation-map.md）並要求 PARIDAD_EDITOR_FRONTEND_OK：僅憑人類視覺比較不足以發現此類錯誤，該專案中已有兩次記錄。如果該工作單元有 GATES.md，請執行 node <skill-dir-de-unlazy>/scripts/gate-check.mjs --reverify GATES.md 並要求 ALL MET 後才能繼續。
14. 提供證據、限制、回滾方案和下一個工作單元。如果使用了 $unlazy，請包含已通過、未通過和已放棄的閘道合格 ID；不要將存在待處理或已放棄閘道的工作單元描述為已完成。

以閘道紀律關閉每個工作單元 ($unlazy)

當 unlazy 已安裝時，將其視為本技能的結案紀律層，而非替代方案：本技能決定在 FSE 遷移中要驗證什麼；unlazy 則強制要求在開始工作前將這些標準聲明為可執行命令，並在報告完成前使用實際證據重新驗證它們，而不是依賴於「看起來不錯」的視覺判斷。

• 對某個頁面或區段使用 unlazy 的僅限模式（每個工作單元一個 GATES.md，從 templates/gates-fse-migration.md 複製）。僅對具有許多獨立頁面的完整網站使用編排模式，其中每個頁面是深度樹的一個葉子，擁有自己的 OWNS:（自己的模板/模式檔案）和一個整合分支，用於驗證跨頁面導航、共享的頁首/頁尾以及頁面間的回歸缺失。
• 不要將每個瑣碎的修正都轉換為閘道分類帳。將紀律保留給一個頁面、一個完整的網站遷移，或任何其因靜默不完整而付出的成本足以證明使用它的工作單元（請參見真實案例：模板中硬編碼的內容導致一個頁面在多個工作單元中保持空白且無法編輯，直到網站所有者手動發現它）。
• 將實際內容閘道（post_content 非空）調整為專案的實際 WP-CLI 調用；在 LocalWP 中，幾乎從來不是全域 wp 二進位檔（請參閱 localwp.md）。
• 對於任何命令都無法良好衡量的內容（感知視覺保真度、文案的編輯審查），手動閘道仍然有效。不要為了避免手動閘道而強制使用自動化指標；本技能合約已禁止將感知度量轉換為自動對等批准。
• 未經明確向使用者請求，不要安裝 unlazy 的可選停止鉤子；本技能本身要求如此。
• 無論是在 unlazy 的編排模式中，還是在本技能的逐頁遷移中，都將工作路由到適當的模型層級：一個機械化且邊界清晰的工作單元（直接翻譯另一個頁面中已解決的元件、類別調整、已診斷的特定修復）應交給較輕量的模型；一個需要架構判斷、決定區塊 vs. 模式 vs. 自訂文章類型、或任何視覺驗證的工作單元，則由當前會話的模型保留。不要為每個小編輯分配一個完整的代理，而應將它們分組到一次操作中，以減少協調成本。

維護不可協商的合約

• 優先使用核心區塊、主題模式和 WordPress 公開 API。
• 不要使用 core/html 作為保留原型 HTML 的捷徑。
• 使用 theme.json 作為共享代碼記號的唯一真理來源。
• 將模板和模板部件用於全域結構；將頁面內容或模式用於編輯組合。
• 除非有已證實且已批准的需求，否則不要將 React、Tailwind 或原型的執行時引入 WordPress 前端。
• 僅當核心區塊無法以可維護的方式表達某行為或編輯需求時，才建立自訂區塊。
• 將業務邏輯、預訂、訂單和資料模型放在外掛中，而非主題中。
• 本地提供字型和圖片，並保留授權、來源和替代文字。
• 將前端和 Site Editor 維持為強制性的操作面。
• 在沒有有效清單和完整矩陣的情況下，不要實施視覺遷移。
• 不要將感知度量轉換為自動對等批准。
• 不要依賴儲存在資料庫中的意外全域樣式。
• 尊重 prefers-reduced-motion、鍵盤操作、可見焦點以及 WCAG 2.1 AA 標準。
• 不要為了掩蓋設計空白而發明內容、路徑或功能。

應用餐廳示範標準

• 使用區塊和模式建立一個小型且純編輯的菜單。
• 僅當菜單需要結構化編輯、篩選、重用或實際增長時，才提議使用像 vicu_menu_item 這樣的自訂文章類型；在外掛中註冊它並測試其行為。
• 將預訂、訂單、付款、動態營業時間和可用性視為獨立的功能整合。不要使用靜態表單悄悄地模擬它們。
• 透過與已批准架構同步的部件或模式，重複使用頁首、頁尾、預訂號召和聯絡模組。

以可驗證的工作單元進行

僅在滿足以下條件時關閉某個頁面或區段：

• 內容、連結和資產與合約相符；
• 標記有效，且其區塊保持可編輯；
• 前端和編輯器正確呈現樣式；
• 桌面、平板和手機已與基準線進行比較；
• 適用的 hover、focus、active、loading 和 error 狀態已測試；
• 不存在控制台錯誤、意外的遠端資源或對 Claude Code 開發伺服器的依賴；
• 證據對應於已測試的確切狀態；
• 該組合在清單中具有唯一行，且未保持為 pending。

提供可驗證的狀態

報告以下資訊：

• 已完成的頁面和區段；
• 受影響的架構和檔案；
• 核心區塊、模式、自訂區塊或外掛的決策；
• 已執行的命令和檢查及其結果；
• 用於比較的 URL 和視口；
• 已接受的差異、殘留風險和回滾方案；
• 已驗證的清單路徑及其證據矩陣摘要。

不要因為網站能渲染或 HTML 包含相同文案就聲稱視覺對等。對等需要視覺比較和可編輯性驗證。

調用範例

使用 $transform-claude-to-gutenberg 審計此 Claude Code 專案，並為指定的 LocalWP 網站建立首頁的遷移合約。

使用 $transform-claude-to-gutenberg 將餐廳示範轉換為 1:1 的 FSE 區塊主題，使用核心區塊和本地資產。

使用 $transform-claude-to-gutenberg 審查已遷移的主題，並列出阻止其被視為可編輯且與已批准原型視覺等效的因素。