実況：Claude Code が「ダークモード切替を追加して」を処理する

1 発話に対して裏で走るツール呼び出しを、時系列でそのまま並べたページです。 「再生」を押すか、右下の矢印で 1 ステップずつ進めて、Observe → Plan → Act → Verify の流れを追体験してください。途中で Verify が失敗し、自動で Observe に戻る箇所も含まれています。

速度
0 / 14 ステップ•Observe × 0Plan × 0Act × 0Verify × 0
  1. 「再生」を押すと、ツール呼び出しがここに時系列で流れます。

各フェーズで即コピーして使う実務プロンプト

Observe → Plan → Act → Verify の各段階で、AI にそのまま投げれば「1 段階分だけ」進めてくれるプロンプトです。 右上の「コピー」ボタンでクリップボードへ入ります。<やりたいこと> や <番号> の部分だけ差し替えてご利用ください。

Observe

Observe — 現状把握プロンプト

使いどころ：着手直後 / エラーで詰まった直後に、いきなり手を動かす前に投げる。

これから「<やりたいこと / 直したい症状>」に着手します。
まだコードは書かないでください。

以下だけを行い、結果を箇条書きで返してください:
1. 関係しそうなファイル / モジュールを一覧化（ripgrep 等で確認した実ファイルのみ）
2. 既存のパターン・命名規則・使っているライブラリとバージョン
3. 影響範囲（同じ前提を共有する兄弟ファイル / ルート / RLS 等）
4. 現時点で不明・確認が必要な点

推測ではなく、実際に読んだ内容だけを根拠にしてください。
Plan

Plan — 実装計画プロンプト

使いどころ：Observe の結果が出そろい、コードを書く直前。

Observe の結果をふまえて、実装計画だけを立ててください。まだコードは書かないでください。

次の形式で答えてください:
- 受け入れ条件（ユーザー視点で「これが満たされれば完了」を 1〜3 行）
- 変更するファイルと役割（新規 / 修正の区別つき）
- 手順を 3〜7 ステップに分割
- 各ステップの Verify 方法（型 / テスト / 画面 / ログ など具体的に）
- 想定リスクとロールバック手順

ステップ数が多すぎる場合は先にスコープを切ってください。
Act

Act — 実装実行プロンプト

使いどころ：Plan に合意したあと、実際に差分を書かせるとき。

承認した Plan のステップ <番号> だけを実装してください。

ルール:
- 変更ファイルを最新状態で read してから差分を書く
- 触るのは Plan で挙げたファイルのみ。関係ないリファクタは禁止
- 追加した import はファイル冒頭に置く
- ライブラリの API は実在シグネチャ（package.json のバージョン / d.ts）に合わせる
- 差分の最後に「このステップの Verify 方法」を 1 行で書く

複数ステップをまとめて進めない。1 ステップ終わったら止まって報告してください。
Verify

Verify — 検証プロンプト

使いどころ：Act の直後、「動きました」と言い切る前に必ず投げる。

いま実装した差分について、以下を実際に実行して結果を貼ってください。推測での「大丈夫そう」は禁止です。

1. 型チェック / ビルド（tsgo, bun run build 等）の生ログ
2. 関連テストがあれば実行、無ければ最小限の再現手順
3. UI 変更なら Playwright / preview でスクリーンショットを撮り、受け入れ条件を満たしているか目視
4. サーバー処理ならログ / DB を叩いて期待値と一致するか確認
5. 同じ前提を共有する兄弟箇所（他ルート / 他ハンドラ）に同じバグが残っていないか rg で横断確認

失敗した場合は Act に戻る前に、原因仮説を 2 つ以上挙げてから 1 つに絞ってください。

Verify で意図とズレたときの失敗パターン × 次の Act チェックリスト

Verify が「型は通ったが仕様とズレる」「同じエラーで回り続ける」といった状態になったら、 Act を差し替える前に、まずは下のチェックリストで Observe をやり直すのが最短です。

① 型エラー / import 不備で Verify が落ちる

症状：
tsgo / build が `Cannot find module` `TS2307` `is not defined` などを吐く。ビルドは通るが実行時に ReferenceError。
典型的な原因：
Act で差分だけを書き、周辺の import 位置・拡張子・エクスポート形式（default vs named）を Observe し直していない。
次の Act に進む前のチェックリスト
  • 対象ファイルを最新状態で read し直したか（差分前提の記憶で書いていないか）
  • 追加した import はファイル冒頭にあるか（関数内・return 後になっていないか）
  • default export と named import が食い違っていないか
  • パス alias（@/…）と相対パスが混在していないか
  • 同名の別ファイルを import していないか（ripgrep で重複確認）

② テスト or ビルドは通ったが、挙動が仕様とズレる

症状：
「動くけど求めたものと違う」。ボタンは付いたが動かない、値は返るが単位が違う、など。
典型的な原因：
Verify を「型 / ビルドが通る」で終わらせていて、ユーザーの受け入れ条件を Observe していない。
次の Act に進む前のチェックリスト
  • ユーザー発話から受け入れ条件を 1 行に書き起こしたか
  • 実際に画面 / API を叩いた（screenshot・curl・DB 参照）か
  • 境界値（空配列・null・0・大文字小文字）を 1 つでも試したか
  • 既存の類似機能と挙動が揃っているか（他のトグル、他の API と比較）
  • 副作用（他ページ・他ユーザー・他ロール）に影響していないか

③ 幻の API / 存在しない関数を呼んでいる

症状：
実行時に `X is not a function` `undefined is not an object`。ライブラリの API が最新版と違う。
典型的な原因：
モデルの記憶に頼って書き、実際のパッケージバージョン・型定義を Observe していない。
次の Act に進む前のチェックリスト
  • package.json の該当ライブラリのバージョンを確認したか
  • node_modules/<pkg>/dist/*.d.ts か公式ドキュメントで実在シグネチャを確認したか
  • 以前のプロジェクト由来の書き方（v3 記法など）を持ち込んでいないか
  • 型エラーを `as any` で握りつぶしていないか

④ 同じエラーで 3 回以上ループしている

症状：
同じ箇所を何度も修正しては同じエラーに戻る。差分は小さいが状況が進まない。
典型的な原因：
誤った Plan を維持したまま Act だけを差し替えている。Observe が浅く、原因を特定していない。
次の Act に進む前のチェックリスト
  • エラーメッセージを 1 語ずつ読み直したか（似た別の型エラーではないか）
  • スタックトレースの一番下ではなく「アプリコードの最初のフレーム」を見たか
  • console / network / server function logs を実際に開いたか
  • 原因仮説を書き出し、成立していない仮説を捨てたか
  • 3 手戻って別アプローチ（別ライブラリ・別ファイル配置）を検討したか

⑤ 一部だけ直して周辺の同型バグを取り残す

症状：
指摘された 1 ファイルは直ったが、同じ前提で書かれた他ルート / 他フェッチャで同じバグが再発する。
典型的な原因：
Verify を「その 1 箇所」で閉じてしまう。"原因のカテゴリ" ではなく "現象のインスタンス" しか直していない。
次の Act に進む前のチェックリスト
  • 同じ前提を共有する兄弟ファイル（routes / hooks / RLS ポリシー）を列挙したか
  • 壊れていたパターン（例: user_id フィルタ抜け）を rg で横断検索したか
  • 同じ修正を要する箇所を 1 ターンでまとめて直したか
  • 回帰テスト / ドキュメントに再発防止のメモを残したか

⑥ Verify を人間任せにして『完了』と言い切る

症状：
『修正しました』と応答するが、実際にはビルドもテストも通していない。次ターンで即差し戻し。
典型的な原因：
Act の直後に手を止めている。エージェントとしての Verify（build / test / screenshot）が抜けている。
次の Act に進む前のチェックリスト
  • 型チェック（tsgo など）を実行したか
  • ビルド or 該当テストを走らせて exit code を確認したか
  • UI 変更なら Playwright / preview で目視スクリーンショットを取ったか
  • サーバー処理ならログ / DB を叩いて結果を確認したか
  • 確認できていない項目を『未確認』と正直にユーザーへ伝えたか
合言葉：Verify が赤くなったら、真っ先に Act を書き直さない。 まず Observe に戻る ── 実ファイル、実ログ、実 UI を見てから、次の 1 手を決める。