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

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

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

```text
◆  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`。

```text
◇  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
```

## 確かめること {#what-it-checks}

| チェック | これがないと起きること |
| --- | --- |
| 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` がすること、しないこと {#what-fix-does-and-what-it-won-t}

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

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

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

## `--live` はゲームを起動する {#live-boots-the-game}

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

## エージェント向け {#for-agents}

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

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

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

```bash
npx debuff doctor --fix
```