meticulous-iterative-dev

Meticulous を使用した綿密なフロントエンド開発

複数のステップにわたるフロントエンドの変更を実装するときは、このスキルを使用してください。各ステップの後に Meticulous を使ってローカルで簡易的なビジュアルチェックを実行し、リグレッションや意図しない副作用を早期に検出します。すべてのステップが完了したら、クラウドで全テストを実行し、記録済みのすべてのセッションを検証します。

開始する前に、meticulous-cli-update スキルを実行して Meticulous CLI とスキルが最新であることを確認してください。ただし、この会話の前の段階ですでに実行済みの場合は、スキップしてください。

前提条件

• ローカル開発サーバーが起動していること（例：npm run dev または pnpm dev）。アプリが http://localhost:3000 など、既知の URL で配信されていること
• 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 リファレンス を参照してください。出力から抽出する主なフィールドは次のとおりです。

• 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 "<concise description of this step>"

各ステップの後にコミットすると、次の反復で --startingPointSha を指定した呼び出しが、このチェックポイントとの差分を計算します。そのため、前のステップの変更によって関連セッションの範囲が不必要に広がることを防げます。

次のステップに進むには、ステップ 1 に戻ります。

---

すべてのステップの後 — クラウドでの全テスト実行

すべてのステップが完了し、コミットされたら、記録されているすべてのセッション（ローカルでシミュレーションした 1～2 件だけではありません）に対して検証するため、クラウドで全テストを実行します。

meticulous-test スキルに従ってください。

クラウドでのテスト実行では、ゴールデンセットの全セッションを対象に、ベースブランチと現在のブランチを比較し、視覚的なリグレッションがあれば報告します。

---

最後のステップ — Meticulous にフィードバックを報告する

クラウドでのテスト実行が完了したら（meticulous-test／meticulous-review スキルでは、テスト実行自体に関するフィードバックをまとめる独自のステップで終了します）、反復的な開発サイクルについて、簡潔なフィードバックを 1 件送信してください。各ステップでのシミュレーションによってリグレッションを早期に発見できたか、また、どのような点があればワークフローがより簡単になったかを記載します。

# 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")