React Doctorとは？npxで使うReactコード診断ツールの使い方・スコア・ESLintとの違い

React Doctorは、高速なReactツールで知られるMillion.jsの開発元が公開したReact専用のコード診断ツールです。npx react-doctor@latestと打つだけで、セキュリティ・パフォーマンス・設計といった観点からコードベースを静的解析し、健全性を0〜100点のスコアで採点します。エンジンにはRust製のoxlintを採用し、大規模プロジェクトでも短時間で走り切ります。2026年のv2で設計思想が大きく変わり、単にコードをスキャンするだけでなく、Claude CodeやCursorといったAIエージェントに診断ルールを登録して「問題のあるReactを最初から書かせない」使い方が中心になりました。本記事では、React Doctorの導入と実行、スコアの読み方、ESLintやReact Scanとの使い分け、CI/CDへの組み込みとdoctor.config.tsでの調整までを、最新版の仕様に沿って整理します。

まとめ：React Doctorの要点

• React DoctorはMillion.js開発元が公開したReact特化の静的解析ツールで、npx react-doctor@latestの1コマンドで実行できる。エンジンはRust製のoxlint。
• セキュリティ・パフォーマンス・設計・アクセシビリティなど約100のReact向けルールで診断し、コードベースの健全性を0〜100点で採点する。
• v2ではnpx react-doctor@latest installでClaude CodeやCursorにルールを「スキル」として登録し、エージェントが問題のあるコードを書く前に防ぐ使い方が主軸になった。
• ESLintが汎用リント、React Scanがランタイムの再レンダリング可視化に強いのに対し、React DoctorはReact特化の静的診断とスコアリングを1コマンドで担う。
• CIではci install・--diff・--blockingを組み合わせ、基準を下回るPRのマージを自動でブロックできる。
• ルールやファイルの除外はdoctor.config.tsのignoreで制御する。仕様更新が速いため、正確なコマンドやスコアは公式で最新を確認したい。

React Doctorの概要とv2で変わった立ち位置

まずReact Doctorがどんなツールで、どの課題を解くために生まれたのかを押さえます。汎用のリンターと何が違い、2026年のv2で使い方の重心がどう移ったのかを理解しておくと、後半のインストールや運用設計が読みやすくなります。

Million.js開発元がoxlintエンジンで作るReact特化の静的解析ツール

React Doctorは、仮想DOM高速化ライブラリMillion.jsを手がけたAiden Bai氏の開発元による製品です。汎用のJavaScriptリンターがスタイルや一般的なバグを広く見るのに対し、React DoctorはReact固有の問題パターンに絞って診断する点が最大の違いです。内部エンジンにはRust製のリンターoxlintを使っており、数万行規模のコードベースでも待たされずにスキャンが終わります。oxlint自体の設計や速度についてはOxlintとは何か？Rust製JavaScript/TypeScript向け次世代リンターの概要と特徴で詳しく解説しています。

診断はコードを実行せずに行う静的解析です。テストのように動かして確かめるのではなく、ソースを読み取ってリスクのある書き方を指摘するため、CIやレビュー前の段階で問題を先取りできます。静的解析とテストやレビューの役割分担は静的コード解析と他のコード品質管理手法との違いで整理しています。

「スキャンする」から「エージェントが書く前に防ぐ」へ転換したv2の設計思想

初期のReact Doctorは「コードベースをスキャンして点数を出すCLI」でした。2026年のv2では、リポジトリの説明文が「あなたのエージェントは質の悪いReactを書く。それを捕まえる」に変わり、AIコーディングエージェント向けの色合いが強くなっています。中心になったのが、診断ルールをエージェントの参照する「スキル」として登録するinstall導線です。

この転換には理由があります。AIにコンポーネント生成を任せる開発が一般化し、生成物にReact特有のアンチパターンが混ざるケースが増えました。事後にスキャンして直すより、エージェントがコードを書く時点でルールを守らせるほうが手戻りが小さい。React Doctorはこの「予防」に軸足を移したツールだと理解しておくと、後述のインストールやAI連携の意図が掴めます。なお、ネット上には旧仕様（npx skills addや--fixなど）を前提にした解説も残っているため、コマンドは本記事後半の「古いチュートリアルとの違い」も参照してください。

セキュリティから設計まで約100ルールで採点する0〜100スコア

React Doctorは約100のReact向けルールを備え、検出結果をもとにコードベースの健全性を0〜100点のスコアにまとめます。スコアはプロジェクト全体の状態を一目で把握するための指標で、点数の高低から改善の必要度を判断できます。個々の指摘にはerror・warningといった重大度が付くため、どこから手を付けるべきかの優先順位も立てやすい設計です。

公式リポジトリには著名OSSプロジェクトのスコア例も公開されていますが、スコアは対象コードの更新やルールのバージョンで変動します。他プロジェクトの点数は相場感の参考にとどめ、自分のプロジェクトでは点数の絶対値より「前回より上がったか」という推移で見るのが実務的です。

npxで完結するインストールと3つの実行モード

React Doctorの導入は非常に軽く、グローバルインストールや依存追加を必要としません。用途に応じて「その場でスキャン」「エージェントにルール登録」「CIへ組み込み」の3つの入り口が用意されています。

npx react-doctor@latest で追加インストール不要のスキャンを実行

もっとも手軽なのは、プロジェクトルートで次のコマンドを実行する方法です。

npx react-doctor@latest

Node.js環境さえあれば、npxがその都度最新版を取得して診断を走らせます。使用しているフレームワークやReactのバージョンは自動で検出されるため、事前の設定ファイルは不要です。実行するとプロジェクト全体の0〜100スコアと、検出された問題のサマリーが表示されます。まずはこのコマンドで現状の点数を把握し、改善の起点にするのが基本の流れです。

install サブコマンドでClaude Code・Cursorにルールを登録する手順

v2の主役がこのコマンドです。

npx react-doctor@latest install

これを実行すると、React DoctorのルールがAIコーディングエージェント向けの「スキル」としてプロジェクトに書き込まれます。対応するエージェントはコード生成や修正の際にこのルールを参照し、dangerouslySetInnerHTMLの乱用やkey属性の欠落といった問題を含むコードを最初から避けるようになります。Claude Code・Cursor・Codex・OpenCodeをはじめ多くのクライアントに対応しています。Claude Code自体の使い方はClaude Codeとは？できること・使い方・料金とコード解析の実力【2026年版】を参照してください。

ci install でCIワークフローに診断を組み込む導線

チーム全体で基準を揃えるには、CIへの組み込み用コマンドを使います。

npx react-doctor@latest ci install

このコマンドはCI向けのワークフロー設定を用意し、プルリクエストごとに自動でスコアを算出する仕組みを整えます。個人のローカルスキャン、エージェントへのルール登録、CIでの継続チェックという3層を組み合わせることで、書く前・書いた直後・マージ前の各タイミングで品質をガードできます。

診断カテゴリと約100ルールが検出するReact特有の問題

React Doctorのルールは、state&effects・パフォーマンス・アーキテクチャ・セキュリティ・アクセシビリティといったカテゴリに分類され、Next.jsなどフレームワーク固有のパックも用意されています。ここでは実務で効きやすい代表的な検出領域を見ていきます。

dangerouslySetInnerHTMLなどセキュリティ系ルールが防ぐXSSリスク

セキュリティ系ルールは、開発者が無意識に使ってしまうAPIの誤用を静的に検出します。代表例がdangerouslySetInnerHTMLで、サニタイズされていないHTMLを直接DOMに挿入するとXSS（クロスサイトスクリプティング）の起点になり得ます。ユーザー入力がそのままレンダリングに渡るパターンなども対象で、こうした指摘はerror扱いになりやすくスコアへの影響も大きめです。レビューで見落としがちな脆弱性を、コミット前に洗い出せる点が価値になります。

不要な再レンダリングを抑えるパフォーマンス系ルールの判定

Reactのパフォーマンス劣化で頻度が高いのが、不要な再レンダリングです。レンダリング関数内でインライン定義したオブジェクトや関数は毎回新しい参照を生み、子コンポーネントの無駄な再描画を招きます。React Doctorはこうしたパターンや、メモ化が必要な箇所の抜けを指摘します。ただし過剰なメモ化までは推奨せず、実際に影響が見込まれる箇所に絞る設計のため、指摘に素直に従っても「メモ化しすぎ」という別のアンチパターンに陥りにくくなっています。

Hooks順序やkey欠落などReact固有の不具合を静的に検出

useStateやuseEffectは、コンポーネントのトップレベルで一貫した順序で呼ぶ必要があり、条件分岐やループ内で呼ぶと動作が壊れます。React Doctorはこの違反を重い重大度で検出し、実行前にバグを止めます。リストレンダリングでのkey属性の欠落や、配列インデックスをkeyに使うことで並び替え時にUIが崩れる書き方も指摘対象です。テストでは再現しづらいこの種の不具合を、静的解析で早期に潰せます。

Next.js・TanStack・React Nativeのフレームワークパック対応

React Doctorは素のReactだけでなく、Next.jsやTanStack、React Native／Expoといった主要スタック向けのルールパックも持ちます。プロジェクトルートを指定すれば使用フレームワークを自動判定するため、追加設定なしでそのスタック固有の注意点も診断に含められます。TypeScriptで書かれたReactプロジェクトにも対応し、JSX・TSXの双方を解析します。一方、VueやAngularなどReact以外のプロジェクトは診断対象外です。

0〜100スコアの読み方とCI判定に効くオプション

スコアは単体で眺めるより、CIや差分診断と組み合わせて「基準を割ったら止める」運用に載せると効果が出ます。主要オプションを用途別に整理します。

–score でスコアだけを出力しCIの合否ラインに使う

--scoreを付けると、詳細な指摘を省いて数値スコアだけを出力します。

npx react-doctor@latest --score

この出力をシェルスクリプトで受け取り、しきい値と比較すればCIの合否判定に使えます。人が読むためのレポートと、機械が判定するための数値を切り替えられる作りです。

–diff・–staged で変更分だけを診断し実行時間を短縮

全ファイルを毎回スキャンするとCI時間が伸びます。--diffに基準ブランチを渡すと差分ファイルだけを診断でき、--stagedではステージ済みの変更に絞れます。

npx react-doctor@latest --diff origin/main

PR単位のチェックは差分診断、プロジェクト全体の傾向把握は定期実行、と使い分けると、フィードバックを速く保ちながら既存コードの負債も見逃しません。差分診断だけに頼ると既存コードに埋もれた問題を拾えない点には注意が必要です。

–blocking でしきい値を下回るPRをマージブロック

--blockingに重大度レベル（error・warning・none。既定はerror）を渡すと、その水準以上の問題が残っている場合にコマンドが失敗（非ゼロ終了）します。

npx react-doctor@latest --diff origin/main --blocking error

GitHubのブランチ保護ルールで必須チェックに指定しておけば、基準を満たさないPRはマージボタンがグレーアウトし、物理的にマージできなくなります。品質基準の運用が個人の裁量に依存しなくなる点が効きます。

–category・–json・–verbose でレポートを整形・連携

--categoryで特定カテゴリだけに絞った診断、--json（さらに軽い--json-compact）で機械処理向けの構造化出力ができます。JSON出力を使えば、診断結果をSlack通知やダッシュボードに流す独自の連携も組めます。ルールごとの内訳やファイル単位の詳細は--verboseで確認でき、特定の指摘がなぜ出たのかはwhyサブコマンド（例 npx react-doctor@latest why src/App.tsx:42）で個別に掘り下げられます。

doctor.config.ts でルールとファイルを絞り込むカスタマイズ

すべてのルールがすべてのプロジェクトに当てはまるわけではありません。React Doctorはプロジェクトルートに置くdoctor.config.tsで、除外するルールやファイルを制御します。設定はTypeScriptで記述します。

ignoreのrules・files・overridesで誤検出を抑える設定例

設定ファイルの中心はignoreで、除外するルール（rules）、対象外にするパス（files）、特定条件だけ挙動を変えるoverridesを指定します。おおまかには次のような形です。

export default {
  ignore: {
    rules: ["react/no-danger"],
    files: ["src/generated/**"],
  },
}

キー名や書式はバージョンで変わることがあるため、実際に導入する際は公式ドキュメントで最新の記法を確認してください。

自動生成コードや公開APIを診断対象から外す実務判断

実務でよくある除外対象は、自動生成されるコードです。GraphQLのスキーマ生成やOpenAPIからのクライアント生成が出力するコードは、React Doctorのルールを当てても改善余地がないためfilesで除外します。また、リッチテキストエディタ周辺で意図的にdangerouslySetInnerHTMLを使う場合は、該当ルールをrulesで外すのが合理的です。除外は「直せない・直す必要がない」箇所に限定し、安易に広げないことがスコアの信頼性を保つコツです。

AIエージェント連携で「問題を書かせない」ワークフロー

v2のReact Doctorがもっとも価値を発揮するのが、AIコーディングエージェントとの連携です。事後にスキャンして直すのではなく、エージェントがコードを書く段階でルールを守らせる使い方を見ていきます。

install でスキルを登録しClaude Code・Cursor・Codexが参照する仕組み

npx react-doctor@latest installを実行すると、ルールがスキルファイルとしてプロジェクトに書き込まれ、対応エージェントがそれをコンテキストとして読み込みます。以降、エージェントにコンポーネント生成を頼むと、key属性の付与やHooks順序の遵守、危険なAPIの回避を織り込んだコードが出やすくなります。Cursor側でルールをどう管理するかはCursor Rulesとは何か？AI開発の新常識となる基本概念とその現場導入でのメリットを徹底解説も参考になります。

事後修正から予防へ——エージェントに渡すことの実務効果

従来のリンターは「書いたあとに間違いを指摘する」ツールでした。ルールをエージェントに渡すと、そもそも間違いを含むコードが生成されにくくなります。指摘件数を減らすための修正作業自体が減るため、レビューはロジックや設計の議論に集中できます。生成AIにReactを任せる比率が高いチームほど、この予防効果は大きくなります。

AI修正を鵜呑みにせず人間レビューを組み合わせる判断基準

ただし、AIの生成・修正を無条件に採用するのは危険です。第一に、AIはコードが「なぜその書き方なのか」という背景まで理解しているとは限らず、互換性維持などの意図的な書き方を壊すことがあります。第二に、ある問題を直す変更が別のルールに抵触することがあります。第三に、テストが薄い状態で自動生成を通すと、動作未確認のままマージしてしまいます。エージェント任せにせず、変更後にReact Doctorを再実行してスコアの改善を確認し、テストを通したうえで人がレビューする——この順序を崩さないことが肝心です。

ESLint・React Scanとの違いと古いチュートリアルの整理

「React Doctorは既存ツールと何が違うのか」「ネットの手順どおりに動かないのはなぜか」は、実際によく検索される疑問です。似たツールとの住み分けと、出回っている旧情報との差を整理します。

汎用リントのESLintとReact特化のReact Doctorの補完関係

ESLintはJavaScript全般に使える汎用リンターで、プラグインを足してReactやアクセシビリティのルールを組み込みます。React Doctorはこの構成作業を省き、React向けのルールとスコアリングを最初から束ねて提供します。両者は競合ではなく、汎用ルールはESLint、React特有の健全性チェックとスコアはReact Doctor、という補完関係で併用できます。ESLintの役割そのものはESLintとは？VSCodeでの設定からflat config・Prettier連携まで解説【ESLint v10対応】を参照してください。

ランタイム再レンダリング可視化のReact Scanとの役割分担

同じ開発元のReact Scanは、アプリを動かしながら再レンダリングをブラウザ上で可視化するランタイム寄りのツールです。実際に動かして初めて見える描画の無駄を掴むのに向きます。対してReact Doctorはコードを実行せずに静的解析する立場で、CIやレビュー前のチェックに向きます。「動かして観察する」React Scanと「書いた段階で静的に弾く」React Doctorは、担当する工程が異なるため両方使っても役割が被りません。

「npx skills add」「–fix」など古いチュートリアルとの違い

React Doctorは更新が速く、初期に書かれた解説と現行仕様がずれています。とくに次の点は旧情報の可能性が高いので注意してください。スキル登録は現在npx react-doctor@latest installで行い、以前紹介されていたnpx skills add形式とは異なります。また、検出結果を自動修正する--fixや、結果をクリップボードにコピーする--promptを案内する記事もありますが、現行の主要フラグは--score・--diff・--blocking・--category・--jsonなどで、自動修正はエージェントへのルール登録側に統合されています。設定ファイル名もreact-doctor.config.jsonではなくdoctor.config.tsです。手順どおりに動かないときは、参照している記事の版が古くないかをまず疑うと早く解決します。

CI/CDでチームのReactコード品質基準を統一する運用

個人環境での実行だけでは、チーム全体の品質は揃いません。CIに組み込み、すべての変更に自動でチェックをかける仕組みを作ります。

GitHub Actionsに ci install で組み込む基本フロー

npx react-doctor@latest ci installでCI用の設定を用意したうえで、GitHub Actionsのワークフローに診断ステップを置きます。プルリクエストをトリガーに、差分診断としきい値判定を回す構成が基本です。

name: react-doctor
on: [pull_request]
jobs:
  doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npx react-doctor@latest --diff origin/main --blocking error

ci installで用意されるワークフローは診断結果をPRに表示するため、レビュアーはログを開かずに問題箇所を把握できます。--json出力を独自のコメント投稿ステップに流す構成も取れます。

差分診断とスケジュール全体診断を組み合わせる2層構成

PRトリガーでは--diffによる差分診断で新規の問題混入を止め、深夜や週末には全体スキャンを定期実行してプロジェクト全体の傾向を追う——この2層構成が実務では効きます。差分側で品質低下の流入を防ぎ、定期側でスコア推移を記録すれば、技術的負債の可視化にもつながります。

段階的にルールを厳格化する導入ロードマップ

既存の大規模プロジェクトに一気に全ルールを適用すると、大量の警告でチームが動けなくなります。第1フェーズはセキュリティのerrorルールだけを有効にし、重大な問題を先に潰します。第2フェーズでReact固有の正確性ルールを足し、第3フェーズでパフォーマンスやアーキテクチャを加える、という順でdoctor.config.tsのignoreを徐々に外していくと無理がありません。各フェーズの移行は、スコアが目標値に届いたかを基準にすると判断がぶれません。

React Doctorに関するよくある質問

React Doctorは無料で使えますか

React DoctorはMillion.jsの開発元が公開しているオープンソースツールで、無料で利用できます。事前インストールも不要で、npx react-doctor@latestを実行すればその都度最新版が取得されて診断が走ります。個人開発からチームのCI運用まで、ライセンス費用なしで導入できます。

React DoctorのGitHubリポジトリはどこにありますか

公式リポジトリはmillionco/react-doctorで、GitHub上で公開されています。1万を超えるStarを集めており（2026年時点）、ルール一覧やスコアの考え方、著名OSSのスコア例はREADMEにまとまっています。ドキュメントは公式サイトのreact.doctorからも辿れます。

npmでインストールしないと使えませんか

グローバルインストールや依存追加は不要です。Node.js環境があればnpx react-doctor@latestで即実行でき、CIでも同じコマンドで動きます。AIエージェントにルールを登録する場合はnpx react-doctor@latest install、CIへ組み込む場合はnpx react-doctor@latest ci installを使います。

Claude CodeやCursorと連携できますか

連携できます。npx react-doctor@latest installを実行するとルールがスキルとして登録され、Claude Code・Cursor・Codex・OpenCodeなどのエージェントが生成・修正時にそれを参照します。これにより、問題を検出してから直すのではなく、問題を含むコードを最初から書かせない予防的な使い方ができます。

ESLintと何が違いますか

ESLintはJavaScript全般の汎用リンターで、プラグインを組み合わせて構成します。React DoctorはReactに特化し、複数カテゴリを横断診断して0〜100点のスコアを出す点が異なります。競合ではなく、汎用ルールはESLint、React固有の健全性チェックとスコアはReact Doctor、という補完関係で併用するのが実務的です。

設定ファイルの名前は何ですか

現行版ではプロジェクトルートに置くdoctor.config.tsで、TypeScriptで記述します。ignoreの下に除外ルールや除外パスを指定します。旧解説にあるreact-doctor.config.jsonとは名前も形式も異なるため、設定が効かないときはファイル名を確認してください。

関連記事

• Oxlintとは何か？Rust製JavaScript/TypeScript向け次世代リンターの概要と特徴
• ESLintとは？VSCodeでの設定からflat config・Prettier連携まで解説【ESLint v10対応】
• 静的コード解析と他のコード品質管理手法との違い
• Claude Codeとは？できること・使い方・料金とコード解析の実力【2026年版】
• Cursor Rulesとは何か？AI開発の新常識となる基本概念とその現場導入でのメリットを徹底解説