meticulous-iterative-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Iterative Frontend Development with Meticulous

使用Meticulous进行迭代前端开发

Use this skill when implementing a multi-step frontend change. After each step, run a quick local visual check using Meticulous to catch regressions and unintended side effects early. After all steps are complete, run a full cloud test run to validate across all recorded sessions.

Before starting, run the
meticulous-cli-update
skill to ensure the Meticulous CLI is up to date — unless it has already run earlier in this conversation, in which case skip it.

当你实施多步骤前端变更时，可以使用本技能。每完成一步后，使用Meticulous快速运行本地视觉检查，尽早发现回归问题和意外副作用。所有步骤完成后，运行完整的云测试，在所有录制的会话中进行验证。

开始前，请运行
meticulous-cli-update
技能以确保Meticulous CLI是最新版本——除非在本次对话中已经运行过该技能，否则可跳过此步骤。

Prerequisites

前提条件

Local dev server running (e.g.
```
npm run dev
```
or
```
pnpm dev
```
), serving the app at a known URL such as
```
http://localhost:3000
```

API token configured:

~/.meticulous/config.json

METICULOUS_API_TOKEN

environment variable

Meticulous CLI installed and on
```
PATH
```
(the
```
meticulous-cli-update
```
skill handles this)

本地开发服务器已启动（例如
```
npm run dev
```
或
```
pnpm dev
```
），应用通过已知URL提供服务，如
```
http://localhost:3000
```

已配置API令牌：

~/.meticulous/config.json

或

METICULOUS_API_TOKEN

环境变量

已安装Meticulous CLI并添加至
```
PATH
```
（
```
meticulous-cli-update
```
技能可完成此操作）

Per-step loop

分步循环流程

Repeat the following for each step of your change.

针对变更的每一步，重复以下操作。

Step 1 — Implement the step's changes

步骤1 — 实现当前步骤的变更

Make your code changes for this step.

为当前步骤进行代码修改。

Step 2 — Find relevant sessions

步骤2 — 查找相关会话

Run:

bash

meticulous local relevant-sessions

If you have already committed previous steps and want to find sessions relevant only to this step's uncommitted changes, pass the SHA of the last commit:

bash

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

For full option reference see the

meticulous-cli-local

skill. The key fields to extract from each session in the output:

Session ID — pass as
```
--sessionId
```
when simulating
Base replay ID — the replay of this session on the base branch; pass as
```
--baseReplayId
```
to diff against. May be absent if the session has never been replayed on the base branch.
Relevance —
```
IsRelevant
```
/
```
IsRelevantBeta
```
means the session directly exercises changed code.

If no sessions are returned, the changed code is not covered by any recorded session. Proceed to Step 4 (commit) and rely on the final cloud run for coverage.

运行：

bash

meticulous local relevant-sessions

如果你已经提交了之前的步骤，且只想查找与当前步骤未提交变更相关的会话，请传入最后一次提交的SHA值：

bash

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

如需完整选项参考，请查看

meticulous-cli-local

技能。需从输出的每个会话中提取的关键字段：

Session ID — 模拟时作为
```
--sessionId
```
参数传入
Base replay ID — 该会话在基准分支上的回放ID；作为
```
--baseReplayId
```
传入以进行对比。如果该会话从未在基准分支上回放过，则可能不存在此ID。
Relevance —
```
IsRelevant
```
/
```
IsRelevantBeta
```
表示该会话直接涉及被修改的代码。

如果未返回任何会话，说明修改的代码未被任何录制的会话覆盖。直接进入步骤4（提交），并依赖最终的云测试来覆盖。

Step 3 — Simulate and analyse

步骤3 — 模拟与分析

Pick 1–2 of the most relevant sessions (prefer

IsRelevant

over

IsRelevantBeta

). For each, follow the

meticulous-simulate-and-diff

skill using:

```
--sessionId
```
and
```
--baseReplayId
```
from step 2's output
```
--appUrl=http://localhost:<port>
```
pointing at your local dev server
```
--headless
```
(required — agents should not operate a visible browser)

baseReplayId

was absent from the output, omit it; use quick-check mode from that skill instead.

Also consider simulating a session for an unexpected flow surfaced by

local relevant-sessions

— one that covers code you didn't intend to change — to check for unintended side effects.

Once you have the analysis, classify each visual difference:

Expected — a direct, intended consequence of this step's changes. Proceed.
Unexpected — a visual change that was not a goal of this step (including side effects of your code, even if explainable). Investigate.

If unexpected and the cause is clear: fix the code and re-simulate.

If the cause is unclear: create a self-contained AI-readable debug workspace using the replay IDs from the simulation output URL (see the

meticulous-cli-debug

skill):

bash

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

Both IDs come from the simulation output URL: the head replay ID is the last path segment of the

View simulation at:

URL; the base replay ID is the

--baseReplayId

used in the simulate command. Open the workspace to diagnose, fix, and re-simulate.

选择1-2个最相关的会话（优先选择

IsRelevant

而非

IsRelevantBeta

）。针对每个会话，按照

meticulous-simulate-and-diff

技能的指引，使用以下参数：

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

如果输出中没有

baseReplayId

，则省略该参数；改用该技能中的快速检查模式。

还可以考虑模拟

local relevant-sessions

显示的意外流程会话——即涉及你未打算修改的代码的会话——以检查是否存在意外副作用。

完成分析后，对每个视觉差异进行分类：

预期差异 — 当前步骤变更直接导致的预期结果。继续操作。
意外差异 — 并非当前步骤目标的视觉变化（包括代码的副作用，即使可解释）。需进行调查。

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

**如果原因不明确：**使用模拟输出URL中的回放ID创建一个独立的AI可读调试工作区（请查看

meticulous-cli-debug

技能）：

bash

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

这两个ID均来自模拟输出URL：head回放ID是

View simulation at:

URL的最后一个路径段；基准回放ID是模拟命令中使用的

--baseReplayId

。打开工作区进行诊断、修复并重新模拟。

Step 4 — Commit

步骤4 — 提交

Once the step's visual output is correct, commit your changes:

bash

git add -p
git commit -m "<concise description of this step>"

Committing after each step means the next iteration's

--startingPointSha

call computes the diff relative to this checkpoint, preventing prior steps' changes from inflating the set of relevant sessions.

Return to Step 1 for the next step.

确认当前步骤的视觉输出无误后，提交你的变更：

bash

git add -p
git commit -m "<concise description of this step>"

每一步后提交意味着下一次迭代的

--startingPointSha

调用会基于此检查点计算差异，避免之前步骤的变更扩大相关会话的范围。

返回步骤1进行下一步操作。

After all steps — full cloud test run

所有步骤完成后 — 完整云测试运行

Once all steps are complete and committed, run a full cloud test run to validate across all recorded sessions (not just the 1–2 you simulated locally):

Follow the
meticulous-test
skill.

The cloud run compares your branch against the base branch across the full golden set of sessions and reports any visual regressions.

所有步骤完成并提交后，运行完整的云测试，在所有录制的会话中进行验证（而不仅仅是你本地模拟的1-2个会话）：

按照
meticulous-test
技能的指引操作。

云测试会将你的分支与基准分支在所有黄金会话集中进行对比，并报告所有视觉回归问题。