debuff doctor：ゲームが起動しないのはなぜ？

npx debuff doctor は debuff プロジェクトのセットアップ全体を一度に確かめ、見つけた問題ごとに修正方法を表示します。対象は Node、debuff パッケージのバージョン、node_modules、debuff.config.ts、アセット、セーブ、エージェントが読むファイル、シナリオが使うブラウザです。--fix は安全な修正を適用してから、もう一度確かめます。壊れたセットアップでは問題が 1 つとは限らないので、最初の問題で止まることはありません。

何もインストールしておらず、.mcp.json も消した新しいプロジェクトでの例です。

◆  Node 24.15.0
◆  package.json found
■  Not installed: @debuffjp/audio, @debuffjp/core, @debuffjp/input, @debuffjp/juice, @debuffjp/cli, typescript, @debuffjp/dev, keiko
│  fix: npm install
■  A package.json script runs tsc, but TypeScript is not installed
│  fix: npm i -D typescript
■  Cannot find module '@debuffjp/cli' imported from 'debuff.config.ts'
│  fix: npm install (the config imports packages that aren't installed yet)
◆  saves.json is valid
▲  AI agents lack project context: missing .mcp.json with the debuff server
│  fix: … .mcp.json needs { "mcpServers": { "debuff": … } }
◆  Agent skills match debuff 0.20.0 (.claude/skills, .agents/skills)
◆  Browser for scenarios, fuzzing and agents: 155.0.8059.85
…

[debuff] 3 problems to fix
         --fix applies the safe fixes

■ は何かが動かなくなる問題、▲ は助言です。続けて npx debuff doctor --fix。

◇  npm install
◇  wrote .mcp.json
◆  8 packages installed
◆  debuff packages all at 0.20.0
◆  TypeScript is installed
◆  debuff.config.ts loaded
◆  AGENTS.md, CLAUDE.md and .mcp.json are set up for AI agents
…
[debuff] all set

確かめること

チェック	これがないと起きること
Node のバージョン	debuff には Node 22 以上が必要
シェルの NODE_ENV	production だと debuff dev で dev コードが無効になり、development だと debuff build が dev コードを残す
インストール済みのパッケージ	node_modules がない、またはインストール済みのバージョンが package.json と違う
debuff のバージョンが 1 つ	@debuffjp/* のパッケージはすべて同じバージョンである必要がある
core が 1 つだけ	@debuffjp/core が入れ子でもう 1 つあると、そのパッケージが別の Game を持つ
@debuffjp/dev	シナリオ、ファズ、dev パネル、エージェントにはその dev フックが必要
TypeScript	スクリプトが tsc を実行するのに、インストールされていない
debuff.config.ts	読み込めない、または間違ったものを export している
アセット	アセットパイプラインが失敗する、または警告を出す
saves.json	正しい JSON ではない
エージェント用ファイル	AGENTS.md、CLAUDE.md、.mcp.json がない
エージェント用スキル	プロジェクトのスキルがない、または別の debuff バージョン向け
ブラウザ	シナリオ、ファズ、MCP サーバー用の Chromium 系ブラウザがない
最新バージョン	新しい debuff が出ている（0.21 から）

助言（▲）でコマンドが失敗することはありません。.mcp.json がないことや新しいリリースは、知っておく価値はあっても、止まる理由にはならないからです。

--fix がすること、しないこと

--fix がするのは、作業を失うおそれのないことだけです。

• インストール、重複の整理、@debuffjp/dev や TypeScript の追加。プロジェクトのロックファイルが示すパッケージマネージャー（npm、pnpm、yarn、bun）を使います。
• .mcp.json がなければ書く。
• インストール済みの debuff バージョン向けに、プロジェクトのエージェント用スキルを書く。

ほかのサーバーが書かれているかもしれないので、既存の .mcp.json は上書きしません。すでに依存しているパッケージのバージョンも変えません。新しいリリースに移るときは、npx debuff upgrade がそれを意図して行います（0.21 から）。

--live はゲームを起動する

静的なチェックが通っても、ゲームが起動しないことはあります。npx debuff doctor --live は開発サーバーも起動し、シナリオが使うブラウザでゲームを開いて、dev フックが出てくるのを待ちます。起動中にゲームが例外を投げればそのエラーを、フックが出てこなければ src/main.ts に足す行を示します。

エージェント向け

npx debuff doctor --json はチェックを 1 つの JSON にして出し、MCP サーバーの doctor ツールも同じものを返します。debuff のほかのコマンドもここを指します。セットアップが原因で失敗すると終了コード 2 で終わり、最後に run npx debuff doctor と出るので、エージェントは再試行ではなくセットアップの確認に向かえます。終了コードの全体は コーディングエージェントが CLI の失敗から必要とするもの にあります。

doctor は必須のチェックが失敗すると 2（0.20 より前は 1）、それ以外は 0 で終わります。

次に何かが起動しなかったら。

npx debuff doctor --fix