日本語

English

日本語

English

外観

ブログ ·

Claude Code と debuff でゲームを作る ​

このウォークスルーでは、空のフォルダから新しい debuff プロジェクトを作り、調整・再現・検証まで済んだ変更にたどり着くまでを追います。実装は Claude Code に任せ、判断はあなたが下します。使うのは basic テンプレートで、debuff のマスコット buff が左右にスライドしてポンと弾けます。同じループはどの debuff ゲームでも使えます。

必要なのは Node.js と Claude Code です。MCP クライアントなら何でも動きますが、以下のコマンドは Claude Code での表示に合わせています。

1. セットアップ ​

bash
npm create debuff@latest my-game
cd my-game
npm install

新しいプロジェクトには、エージェントに必要なものが最初から揃っています。

  • .mcp.json が debuff の MCP サーバー @debuffjp/mcp を起動します。
  • AGENTS.md にはコマンド、構成、作業ループ、ルールがまとまっています。CLAUDE.md はそこを指しています。
  • scenarios/move-and-pop.json は最初のテストで、スクリーンショットのベースライン付きです。

開発サーバーを起動し、表示された URL を開きます。

bash
npm run dev

続いて、同じフォルダで Claude Code を起動します。

bash
claude

Claude Code はプロジェクトの MCP サーバーを信頼するかどうかを一度だけ聞いてきます。許可すれば、/mcp に debuff が接続済みとして表示されるはずです。

2. ライブかヘッドレスか ​

エージェントにゲームを見るよう頼んでみましょう。エージェントは game_start を呼び、モードを自動で選びます。

  • ライブ：ブラウザで npm run dev のゲームを開いているとき。エージェントはあなたのタブにアタッチして一時停止します。開発オーバーレイ（バッククォートキーで切り替え）に agent バッジが表示され、log タブにはエージェントの操作がすべて、取り消しボタン付きで並びます。game_stop でゲームが再開し、接続が切れます。
  • ヘッドレス：何も開いていないとき、またはエージェントが mode: "headless" を指定したとき。ヘッドレスブラウザに専用のコピーが用意され、時間は game_step を呼んだときだけ進みます。毎回同じ結果が求められるチェックに向いています。

見ながら舵を取りたいときはライブ、ファズや修正の確認のように放っておける作業にはヘッドレスを使いましょう。

3. 瞬間をフラグして、エージェントに再現させる ​

しばらく遊んでみてください。見た目や手触りがおかしいと感じたら、オーバーレイの log タブを開き、入力欄（「flag this moment for the agent…」）に書いて Enter を押します。

矢印キーを離すと buff が行き過ぎる

それからエージェントにメモを見るよう伝えます。エージェントは game_notes を呼び、あなたの言葉とそのティックを受け取ります。そのティックでのシーンの inspect() の状態と、直前のフレームも一緒です。buff がどこにいたか、何を押したかを説明する必要はありません。

次に、その瞬間を再現するよう頼みます。エージェントはメモのティックを指定して game_replay を呼びます。

json
{ "file": ".debuff/replays/replay-tick-412.json", "ticks": 412, "steps": 37, "warnings": [] }

このファイルは、ページを読み込んでからのキー、ポインター、パラメータ変更をすべて含むシナリオです。debuff は固定ステップとシード付き乱数を使うので、実行すればあなたのセッションがそのまま再現されます。

bash
npx debuff scenario .debuff/replays/replay-tick-412.json

これでエージェントは何度でも実行できる再現手順を手に入れました。もちろんあなたもです。warnings には、スローモーションなどリプレイで記録できなかったものが並びます。リプレイは同じ log タブから自分で保存したりコピーしたりもできます。

4. 調整する ​

行き過ぎは手触りの問題で、手触りはパラメータに宿ります。テンプレートでは buff の移動をこう宣言しています。

ts
const tuning = game.params.define("player", {
  speed: { type: "number", default: 140, min: 0, max: 600, units: "px/s" },
  accel: { type: "number", default: 1200, min: 0, max: 5000, units: "px/s²" },
});

エージェントは game_params でこれを読み、game_set_param で変更します。範囲外の値は弾かれます。いちばん手っ取り早いのは tune-feel プロンプトで、Claude Code ではスラッシュコマンドとして表示されます。

/mcp__debuff__tune-feel stop faster when I let go

このプロンプトは、理由付きの小さなパラメータ変更セットを 2〜3 案出し、試す前にあなたの了承を待つようエージェントに指示します。エージェントはあなたのタブで案を適用し、数秒プレイしてフレームをキャプチャします。あなたが試してみて、気に入らなければオーバーレイから取り消し、選びます。そこで初めて、選ばれた値が game.params.define(...) のデフォルトに書き込まれます。

同じことは、オーバーレイの tune タブでも手作業でできます。すべてのパラメータにスライダーがあります。

5. シナリオとファズで検証する ​

変更が完了するのは、確認が済んでからです。確認には 2 つのコマンドを使います。AGENTS.md にそう書いてあるので、エージェントは両方とも実行します。

シナリオ。 npm test は scenarios/*.json をヘッドレスで実行し、各 expect を inspect() の状態と照らし合わせ、キャプチャをベースラインと比較します。

bash
npm test

ステップ 3 のリプレイは回帰テストにできます。エージェントに scenarios/ へコピーしてもらい、おかしかった状態に対する expect を加えます。たとえば、キーを離してから数ティック後の buff の vx です。意図してキャプチャが変わった場合、エージェントは差分画像を見せ、npx debuff scenario --update で受け入れる前にあなたの確認を取るはずです。

ファズ。 npx debuff fuzz は、ランダムだけれどもっともらしい入力で、シミュレーション上の数分間ゲームをプレイします。

bash
npx debuff fuzz

クラッシュ、スタック状態、行ったり来たりのループは、それぞれを正確に再現するシナリオとして .debuff/fuzz/ に保存されます。見つかった問題を直すときは、エージェントが npx debuff scenario <file> でそのファイルを再生し、原因を直し、通るまで再生し直します。--seed で同じ実行を繰り返せ、何か見つかるとコマンドは非ゼロで終了するので、CI でも使えます。

途中でランタイムエラーが出たら、game_errors が説明してくれます。kind は誰の問題か（your-code、debuff-usage、debuff-bug、outside）を示し、where はソースの行を示します。fix-errors プロンプトを使えば、修正と再チェックまでエージェントを導けます。

6. 創作の判断はあなたのもの ​

エージェントが担うのは実装、再現、調整の試行、テストです。ゲームをどうするかはあなたが決めます。この分担はツールそのものに組み込まれています。

  • AGENTS.md とすべての MCP プロンプトが、アート、手触り、難易度、ストーリー、名前はあなたが決めるもので、エージェントは自分で決めずに 2〜3 案を出すよう伝えています。
  • ライブモードでのパラメータ変更は、取り消し付きでオーバーレイに表示されます。
  • スクリーンショットのベースラインは、あなたの承認があるときだけ変わります。

実際には、エージェントは決定済みの答えではなく「止まり方をキビキビさせる方法を 3 つ、キャプチャ付きで用意しました」と返してきます。遊ぶのも、選ぶのも、あなたです。

次へ ​