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（必需——代理不应操作可见浏览器）

如果输出中缺少 baseReplayId，则省略它；改用该技能中的快速检查模式。

同时考虑模拟一个由 local relevant-sessions 发现的意外流程的会话——即覆盖了你本不打算更改的代码的会话——以检查意外的副作用。

获得分析结果后，对每个视觉差异进行分类：

• 预期 — 该步骤更改的直接、预期结果。继续。
• 意外 — 不是该步骤目标的视觉变化（包括代码的副作用，即使可以解释）。进行调查。

如果是意外且原因明确： 修复代码并重新模拟。

如果原因不明确： 使用模拟输出 URL 中的回放 ID 创建一个自包含的、AI 可读的调试工作区（参见 debug.md）：

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

两个 ID 都来自模拟输出 URL：头部回放 ID 是 View simulation at: URL 的最后一个路径段；基础回放 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。