meticulous-iterative-dev

使用 Meticulous 進行疊代式前端開發

當實作多步驟前端變更時使用此技能。在每個步驟後，執行一次快速的本地視覺檢查，利用 Meticulous 及早發現回歸與非預期副作用。完成所有步驟後，再執行完整的雲端測試執行，以在所有錄製的工作階段上進行驗證。

開始前，先執行 meticulous-cli-update 技能以確保 Meticulous CLI 為最新版本——除非本次對話中已執行過，則可跳過。

前置需求

• 本地開發伺服器正在執行（例如 npm run dev 或 pnpm dev），並在已知 URL（如 http://localhost:3000）提供服務
• 已通過 Meticulous 驗證：執行 meticulous auth whoami 以透過 OAuth 登入（也可使用 METICULOUS_API_TOKEN 或 ~/.meticulous/config.json 中的 API token）
• Meticulous CLI 已安裝並在 PATH 中（meticulous-cli-update 技能會處理此項）

---

逐步循環

針對變更的每個步驟重複以下流程。

步驟 1 — 實作該步驟的變更

進行此步驟的程式碼修改。

步驟 2 — 尋找相關工作階段

執行：

meticulous local relevant-sessions

如果你已提交前幾個步驟，並希望僅找出與此步驟未提交變更相關的工作階段，請傳入最後一次提交的 SHA：

meticulous local relevant-sessions --startingPointSha=<sha-of-last-commit>

完整選項參考請見 meticulous-cli 技能的 local 參考。從輸出中每個工作階段需擷取的關鍵欄位：

• Session ID — 模擬時作為 --sessionId 傳入
• Base replay ID — 該工作階段在基礎分支上的重播 ID；作為 --baseReplayId 傳入以進行比對。若該工作階段從未在基礎分支上重播，則可能不存在。
• Relevance — IsRelevant / IsRelevantBeta 表示該工作階段直接執行了變更的程式碼。

如果沒有回傳任何工作階段，表示變更的程式碼未被任何錄製的工作階段涵蓋。請直接前往步驟 4（提交），並依賴最終的雲端執行來獲得涵蓋率。

步驟 3 — 模擬與分析

選取 1–2 個最相關的工作階段（優先選取 IsRelevant 而非 IsRelevantBeta）。針對每個工作階段，依照 meticulous-simulate-and-diff 技能操作，使用：

• 步驟 2 輸出中的 --sessionId 與 --baseReplayId
• --appUrl=http://localhost:<port> 指向你的本地開發伺服器
• --headless（必要——代理程式不應操作可見的瀏覽器）

如果輸出中缺少 baseReplayId，則省略該參數；改用該技能中的快速檢查模式。

此外，也應考慮模擬一個由 local relevant-sessions 發現的非預期流程——即涵蓋你未打算修改的程式碼的工作階段——以檢查是否有非預期的副作用。

取得分析結果後，分類每個視覺差異：

• 預期 — 此步驟變更的直接、預期結果。繼續進行。
• 非預期 — 非此步驟目標的視覺變更（包括即使可解釋的程式碼副作用）。進行調查。

如果是非預期且原因明確： 修正程式碼並重新模擬。

如果原因不明： 使用模擬輸出 URL 中的重播 ID 建立一個自包含、AI 可讀的除錯工作區（參見 debug.md）：

meticulous debug replay <headReplayId> --baseReplayId=<baseReplayId>

兩個 ID 均來自模擬輸出 URL：head replay ID 是 View simulation at: URL 的最後一個路徑區段；base replay ID 是模擬指令中使用的 --baseReplayId。開啟工作區進行診斷、修正，然後重新模擬。

步驟 4 — 提交

一旦該步驟的視覺輸出正確，提交你的變更：

git add -p
git commit -m "<此步驟的簡潔描述>"

在每個步驟後提交，意味著下一次疊代的 --startingPointSha 呼叫會計算相對於此檢查點的差異，避免先前步驟的變更膨脹相關工作階段的集合。

返回步驟 1 進行下一個步驟。

---

所有步驟完成後——完整雲端測試執行

當所有步驟完成並提交後，執行一次完整的雲端測試執行，以在所有錄製的工作階段（而不只是你本地模擬的 1–2 個）上進行驗證：

遵循 meticulous-test 技能。

雲端執行會將你的分支與基礎分支在完整黃金工作階段集上進行比較，並回報任何視覺回歸。

---

最終步驟——向 Meticulous 回報回饋

雲端測試執行完成後（meticulous-test/meticulous-review 技能會以各自的回饋步驟結束，涵蓋執行本身），提交一則關於疊代循環的簡短回饋：逐步模擬是否及早發現了回歸？什麼能讓工作流程更順暢？

meticulous agent submit-feedback --message="<一兩句話>" --outcome=<helped|neutral|hindered> --skill=meticulous-iterative-dev

MCP 工具：submit_feedback。