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 令牌）
• 已安装 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 参考文档。从每个会话的输出中提取以下关键字段：

• 会话 ID — 模拟时作为 --sessionId 传入
• 基础回放 ID — 此会话在基础分支上的回放；作为 --baseReplayId 传入以进行差异比较。如果此会话从未在基础分支上回放过，则可能没有此字段。
• 相关性 — IsRelevant / IsRelevantBeta 表示此会话直接运行了已更改的代码。

如果没有返回会话，说明已记录的会话均未覆盖更改的代码。继续执行步骤 4（提交），并依靠最终云端运行进行覆盖验证。

步骤 3 — 模拟并分析

选择 1–2 个最相关的会话（优先选择 IsRelevant，而非 IsRelevantBeta）。对每个会话，按照 meticulous-simulate-and-diff 技能操作，并使用：

• 步骤 2 输出中的 --sessionId 和 --baseReplayId
• --appUrl=http://localhost:<port>，指向本地开发服务器
• --headless（必填 — Agent 不应操作可见浏览器）

如果输出中没有 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 "<concise description of this step>"

每一步完成后都提交，意味着下一轮的 --startingPointSha 调用会相对于此检查点计算差异，避免之前步骤的更改扩大相关会话的范围。

返回步骤 1，继续下一步。

所有步骤完成后 — 全量云端测试

完成所有步骤并提交后，运行全量云端测试，以验证所有已记录的会话（而不只是你在本地模拟的 1–2 个会话）：

遵循 meticulous-test 技能。

云端测试会将你的分支与基分支进行比较，覆盖完整的黄金会话集，并报告任何视觉回归。

---

最后一步 — 向 Meticulous 提交反馈

云端测试完成后（meticulous-test/meticulous-review 技能都会以各自针对本次运行的反馈步骤结束），提交一条简短反馈，说明迭代流程的情况：逐步模拟是否及早发现了回归，以及哪些改进会让工作流更轻松？

# CLI
meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --skill=meticulous-iterative-dev

# MCP
submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", skill="meticulous-iterative-dev")