--- title: "React Doctorとは？使い方・スコアの仕組み・CI設定とESLintとの違い【0.9.18対応】" url: "https://www.issoh.co.jp/tech/details/11069/" published: 2026-02-19 updated: 2026-11-03 categories: ["React"] publisher: "株式会社一創" --- # React Doctorとは？使い方・スコアの仕組み・CI設定とESLintとの違い【0.9.18対応】 React Doctorは、Million Software, Inc.（Million.jsの開発元）が公開しているReact専用のコード診断CLIです。プロジェクトのルートで`npx react-doctor@latest`を実行すると、バグ・パフォーマンス・セキュリティ・アクセシビリティ・保守性の5カテゴリで問題を列挙し、0〜100のヘルススコアを返します。本記事は2026年10月12日公開の0.9.18を基準に、サンプルプロジェクトで実行した結果を交えて、スコアの算出方法、`--scope`による差分診断、設定ファイル、コーディングエージェントへの導入、GitHub Actionの設定までを整理します。 ## まとめ：React Doctor 0.9.18の要点 - 実行は`npx react-doctor@latest`の1行。Node.jsは`^20.19.0 || >=22.13.0`が必要で、内部ではoxlintで解析する。 - スコアは手元で計算されず、診断結果を`react.doctor/api/score`へ送って算出される。`--no-score`やオフラインではスコアが出ない。 - CIの合否は`--blocking`（既定`error`）で決まる。`--score`はerrorが残っていても終了コード0を返すので、合否判定には使えない。 - 差分だけを見るなら`--scope changed`。以前の`--diff`は非推奨の別名として残っている。 - 設定は`doctor.config.*`（ts・js・jsonなど8形式）か`package.json`の`reactDoctor`キー。`rules disable`などのコマンドで書き込める。 - ライセンスは改変MIT。AIの学習データへの利用と、React Doctorを主な価値とする有償サービスとしての提供には書面の許諾が要る。 ## React Doctorの開発元・版・ライセンス ### Million Software製のReact専用スキャナー 公式ドキュメントはReact Doctorを、Reactのコードを決定的（同じコードなら同じ結果）に検査するスキャナーと説明しています。対応は React・Next.js・Vite・TanStack・React Native・Expo・Preact です。解析エンジンにはRust製のoxlintを使い、npmパッケージの依存には`oxlint`・`oxc-parser`・`eslint-plugin-react-hooks`が含まれます。oxlint自体の速度やESLintとの違いは[OxlintとESLintの違いとは？読み方・速度実測・移行手順とBiomeとの比較](/tech/details/8351/)で扱っています。 ルールの数は資料によって違います。0.9.18の`rules list --json`は906件を返し、そのうち既定で有効なのは688件でした。公式のルール索引は「802 active rules」と書いています。数え方の範囲が違うため、記事や資料で「約100ルール」「60以上」とあるのは初期の版の数字だと読んでください。 ### 製品名・GitHub Actionのv2とnpm版番号の区別 npmの`react-doctor`は2026年2月13日に公開され、10月時点でも0.9系です。一方、公式ブログは2026年2月17日に「React Doctor v1」、5月8日に「React Doctor v2」を発表しました。v2はReact NativeとExpo向けルール、useEffectの解析、ESLintプラグインとしての提供を加えた製品上の区切りです。GitHub Actionのタグも`@v2`（2026年10月31日時点の最新タグはv2.4.0）で、CLIのnpm版番号とは別に進んでいます。「react doctor v2」で検索して`npm i react-doctor@2`を試しても、該当する版は存在しません。 ### GitHubリポジトリとライセンス リポジトリは[github.com/millionco/react-doctor](https://github.com/millionco/react-doctor)で、GitHub APIで2026年10月31日に取得したスター数は15,072です。READMEには「MIT-licensed」とありますが、[LICENSEファイル](https://github.com/millionco/react-doctor/blob/main/LICENSE)の題名は「Modified MIT License」で、次の2つの用途に事前の書面許諾を求めています。 - ソフトウェアやその派生物を、機械学習モデルやAIシステムの学習・ファインチューニング・評価のデータとして使うこと - React Doctorを主な価値とする有償・ホスト型のサービス（商用APIやSaaS）として第三者に提供すること 社内の開発やCIで使う分には無償です。React Doctorを組み込んだ診断サービスを社外へ販売する計画があるなら、着手前に許諾の要否を確認してください。 ## npx react-doctorでスキャンする手順 ### 実行コマンドと主なオプション プロジェクトのルートで次を実行します。グローバルインストールは不要で、フレームワークとReactの版は自動で判定されます。 ``` npx react-doctor@latest npx react-doctor@latest --verbose # ファイルと行番号を表示 npx --yes react-doctor@latest --yes # npmとReact Doctorの確認を省略 npx react-doctor@latest --json | jq '.summary' ``` モノレポでは`--project web,admin`でワークスペースを選び、プロジェクトごとに採点させます。`--category Performance`は表示を絞るだけで、スキャン対象のファイルは変わりません。 ### サンプル2ファイルで実行した結果（48点） 2026年10月31日にNode.js 26.5.0・React 19.2.0の最小構成で、診断対象の書き方を入れた2ファイルにreact-doctor 0.9.18を実行しました。`useEffect`内で絞り込み結果を`setState`する、`useEffect`内で`fetch`する、`li`に`onClick`を付ける、`img`に`alt`が無い、といった内容です。 ``` React Doctor — rd-sample Score: 48 / 100 Critical 7 issues Accessibility: 1 error, 2 warnings Bugs: 4 warnings ✖ Image missing alt text react-doctor/alt-text ⚠ Derived value copied into state react-doctor/no-derived-state ⚠ Data fetching inside an effect react-doctor/no-fetch-in-effect ⚠ fetch Response consumed without status check ⚠ Effect promise .then sets state with no catch ⚠ Click handler missing keyboard handler ⚠ Handler on non-interactive element ``` 2ファイルの走査は1.5〜2.4秒でした。`alt`を足してerrorを0件にすると、warning 6件のまま65点（17点増）に上がりました。公式の手順では、セキュリティとパフォーマンスの指摘を先に扱い、その後にその他のerrorを修正します。 同じファイルで`dangerouslySetInnerHTML`にユーザー入力を渡していましたが、指摘はありませんでした。該当ルール`react-doctor/no-danger`は既定で無効（`defaultEnabled: false`）だからです。XSS対策として使うなら、設定で明示的に有効にする必要があります。 ### why・rules explainによる指摘理由の確認 指摘の意味が分からないとき、または抑制コメントが効かないときは`why`に「ファイル:行」を渡します。該当箇所のコード、カテゴリ、推奨する直し方、近くに抑制コメントがあるかどうかが表示されます。ルールそのものの説明は`rules explain`で読めます。 ``` npx react-doctor@latest why src/UserList.tsx:20 npx react-doctor@latest rules explain react-doctor/no-derived-state ``` 静的解析には誤検知が付きものです。指摘を鵜呑みにしない判断の手順は[静的コード解析の誤検知と限界｜レビュー・テストとの責任分担](/tech/details/7475/)にまとめています。 ## 0〜100スコアの算出方法とCIの終了コード ### react.doctor APIによるスコア算出と送信データ 0.9.18のソース（`dist/index.js`の`requestScore`）を読むと、スコアはCLIの中で計算されていません。診断結果をgzip圧縮したJSONで`https://www.react.doctor/api/score`へPOSTし、返ってきた点数とラベル（Great・Criticalなど）を表示しています。送信内容は次のとおりです。 - 各診断のルール名・メッセージ・行などと、秘匿情報を伏せたファイルパス（ソースコード本文の送信処理は無い） - リポジトリ名・コミットSHA・フレームワーク・Reactの版・ソースファイル数・既定ブランチ・React Doctorの版 このため、`--no-score`を付けた場合は「Score disabled」、採点APIに到達できない場合は「Score unavailable」と表示され、点数は出ません。GitHub Actionの`score`出力も、APIに届かないときは空になります。社外への送信が契約上許されないリポジトリでは`--no-score --no-supply-chain`を付けて採点APIとクラッシュ報告、Socket.devへの依存検査の通信を止め、点数ではなくerror・warningの件数で管理するのが現実的です。なお、クラッシュ報告はSentry、利用状況の計測はAxiomへ送られ、[Data Use](https://www.react.doctor/docs/legal/data-use)は「ファイルの内容やコード片は送らない」と明記しています。 ### blockingとscoreオプションの終了コードの違い サンプルで終了コードを測ると次のとおりでした（error 1件・warning 6件の状態）。 | コマンド | 終了コード | | ---------------------------------------- | -------- | | `npx react-doctor -y`（既定 blocking=error） | 1 | | `--score` | 0（48を出力） | | `--blocking none` | 0 | | `--blocking warning` | 1 | | errorを0件にして既定で実行 | 0 | `--score`は数値を出力するだけで、errorが残っていても成功で終わります。CIを止めたいなら`--blocking error`か`warning`を使い、点数のしきい値で止めたいなら`--score`の出力をシェルで比較する処理を自分で書く必要があります。GitLabなどで「警告ありだが失敗ではない」状態を表すには`--warning-exit-code`で2〜255の値を指定できます。 ## scopeオプションによる差分診断の範囲と制約 0.9.18では診断範囲を`--scope`で選びます。既定は`full`です。部分スコープでは基準のブランチを自動で探し、`--base main`で固定もできます。 | scope | 報告する範囲 | | ------------ | ---------------------------------- | | `full` | プロジェクト全体（既定） | | `files` | 変更したファイルの全指摘 | | `changed` | 基準と比べて新たに増えた指摘だけ | | `lines` | 変更行に掛かる指摘 | | `contextual` | 変更した関数・JSX要素・ファイル内の既存指摘（0.9.18で追加） | サンプルで`main`から枝を切り、条件分岐の後に`useState`を呼ぶコンポーネントを1つ追加して`--scope changed --base main`を実行すると、既存の7件は出ず、`react-doctor/rules-of-hooks`のerror 1件だけが報告されました。旧来の`--diff main`も動きますが、`The '--diff' flag is deprecated; use '--scope changed'`（原文はバッククォート）という警告が出ます。 コミット前のフックには`--staged`を使います。`unused-file`や`circular-dependency`などプロジェクト全体の依存グラフを見る6ルールは既定で無効で、有効にしても`full`のときしか動きません。差分診断だけを回していると、未使用ファイルや循環依存は見つからない点に注意してください。 ## doctor.config.jsonとrulesコマンドによるルール調整 ### 設定ファイルの置き場所と形式 React Doctorはスキャンするディレクトリから`.git`かモノレポのルートまで親をたどり、`doctor.config.*`を探します。拡張子は`.ts`・`.mts`・`.cts`・`.js`・`.mjs`・`.cjs`・`.json`・`.jsonc`の8種類で、`package.json`の`reactDoctor`キーにも書けます。JSONはJSON5として読まれるため、コメントや末尾のカンマも許されます。コマンドラインの指定は設定より優先されます。 ``` { "$schema": "https://react.doctor/schema/config.json", "ignore": { "files": ["src/generated/**"], "overrides": [ { "files": ["components/search/HighlightedSnippet.tsx"], "rules": ["react-doctor/no-danger"] } ] }, "rules": { "react-doctor/no-danger": "warn", "react-doctor/no-array-index-as-key": "error" }, "categories": { "Maintainability": "warn" } } ``` この例は、既定で無効の`no-danger`を有効にしたうえで、サニタイズ済みのHTMLを意図して描画する1ファイルだけを除外しています。カテゴリ名は`Security`・`Bugs`・`Performance`・`Accessibility`・`Maintainability`の5つで、個別ルールの指定がカテゴリの指定より優先されます。 ### rulesコマンドによる設定ファイルの作成・更新 手で書く代わりに、`rules`サブコマンドが既存の設定ファイルを編集します。設定ファイルが無ければ`doctor.config.json`を新規作成します。サンプルで`alt-text`を無効にすると、次のファイルができました。 ``` $ npx react-doctor rules disable react-doctor/alt-text Set react-doctor/alt-text → off Updated doctor.config.json (created) $ cat doctor.config.json { "$schema": "https://react.doctor/schema/config.json", "rules": { "react-doctor/alt-text": "off" } } ``` ### ignore・rules・surfacesの使い分け 3つは止める場所が違います。`rules`や`categories`で`off`にするとルール自体が走りません。`ignore.rules`はルールを走らせたうえで結果から落とします。`surfaces`ではCLI表示・PRコメント・スコア・CIの失敗判定を個別に制御でき、手元に表示を残してCIの失敗判定から除外する設定もできます。既存コードに大量の指摘があるチームは、いきなり`off`にせず`surfaces`でCIの判定から外し、手元では見える状態を保つほうが負債を見失いません。1行だけ抑制するなら、直前の行に`// react-doctor-disable-next-line react-doctor/no-derived-state`と書きます。 ## Claude Code・Cursorなどエージェントへの導入 `npx react-doctor@latest install`は、コーディングエージェント用のスキル`/react-doctor`を入れるコマンドです。手元で`install --dry-run --yes`を実行すると、検出したエージェント（この環境ではClaude Code・Codex・Gemini CLI・GitHub Copilot・Mistral Vibe・OpenCode・OpenHands）へのスキル配置に加えて、次の変更が予定として表示されました。 - `package.json`に`doctor`スクリプトを追加し、`react-doctor`を開発依存に入れる - `.git/hooks/pre-commit`に、コミットを止めない診断（`--staged --blocking warning`）を入れる。Husky・Lefthookなど既存のフック管理があればそれを使う - `.github/workflows/react-doctor.yml`を作る 入るスキル（SKILL.md）の中身は「Reactのコードを変えたら`npx react-doctor@latest --verbose --scope changed`を実行し、スコアが下がっていないか確かめる」という指示です。エージェントが書く前に防ぐのではなく、書いた直後に自分で検査させる仕組みだと理解しておくと期待値がずれません。編集のたびに結果を返すネイティブフック（Claude CodeとCursor）は既定で入らず、`--agent-hooks`を付けたときだけ入ります。Claude Codeで既存コードを調べる使い方は[Claude Codeでソースコード解析する方法](/tech/details/5571/)、Cursor側のルール管理は[.cursorrulesとは？非推奨の現状と.cursor/rules（.mdc）への移行](/tech/details/8227/)を参照してください。 注意点が1つあります。`@latest`は固定版ではなくnpmのlatestタグを指定しますが、取得時にはローカルのインストールやキャッシュが再利用される場合があります。サプライチェーンの観点で版を固定したいなら、`install`で開発依存に入れた版を`npm run doctor`で使う運用に寄せてください。 ## GitHub Actionsによるプルリクエスト診断の設定 ### ci installが書くワークフロー `npx react-doctor@latest ci install --yes`を実行すると、次の要点を持つ`.github/workflows/react-doctor.yml`が生成されました（コメントは省略）。 ``` on: pull_request: types: [opened, synchronize, reopened, ready_for_review] push: branches: ["main"] permissions: contents: read pull-requests: write issues: write statuses: write jobs: react-doctor: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 with: fetch-depth: 0 - uses: millionco/react-doctor@v2 ``` Actionの既定は`blocking: none`（指摘してもチェックを落とさない）と`scope: changed`です。CLIの既定（`blocking=error`・`scope=full`）と逆なので、同じ感覚で設定すると「Actionでは落ちない」ことに驚きます。PRにはまとめのコメント1件、変更行へのインラインコメント、スコア付きのコミットステータスが付き、`main`へのpushでは点数を記録するだけです。`fetch-depth: 0`を外した浅いチェックアウトで比較元コミットを取得できない場合は、変更ファイルの既存指摘まで報告されることがあります。 ### v1からv2で変わった入力 | v1 | v2 | | -------------------- | ------------------- | | `fail-on` | `blocking` | | `annotations` | `review-comments` | | `non-blocking: true` | `blocking: none` | | （なし） | `scope`（既定 changed） | | `node-version` 既定22 | 既定24 | 既存のワークフローは`npx react-doctor@latest ci upgrade`で書き換えられます。2026年春ごろの解説には`millionco/react-doctor@main`に`diff: main`と`github-token`を渡す例がありますが、v2の入力一覧にはどちらもありません。 ### blockingと必須チェックによるマージ制御 チームが指摘の質に納得してから、`npx react-doctor@latest ci config --blocking error`で失敗判定を有効にします。さらにGitHubの「Settings → Branches → Branch protection rules」でReact Doctorのチェックを必須にしないと、チェックが赤でもマージボタンは押せます。フォークからのPRには書き込み権限が無いため、診断は走ってもコメントは付きません。React製の業務アプリで品質基準づくりから開発まで任せたい場合は、[業務用・Webアプリ開発](/service/apps/business/)の支援内容も参考にしてください。 ## ESLint・oxlintプラグインとReact Scanとの違い ### oxlint-plugin-react-doctorとeslint-plugin-react-doctorの登録・設定 CLIを別に回さず、いつものリントの中でReact Doctorのルールを使いたいときは、2026年5月15日にnpmへ公開された2つのプラグイン（いずれも0.9.18）を使います。oxlintでは`.oxlintrc.json`の`jsPlugins`に登録します。 ``` { "jsPlugins": [{ "name": "react-doctor", "specifier": "oxlint-plugin-react-doctor" }], "rules": { "react-doctor/no-fetch-in-effect": "warn", "react-doctor/no-derived-state": "warn" } } ``` ESLintではflat configに`reactDoctor.configs.recommended`を足し、Next.jsなら`next`、React Nativeなら`react-native`のプリセットを重ねます。ただし秘密情報や設定ファイルを調べる`security-scan`系のルールはプラグイン単体では動かず、Socket.devによる依存パッケージの検査（既定でスコア50未満を報告）もCLIだけの機能です。依存検査の仕組みは[socket.devとは？npm/PyPIのサプライチェーン攻撃を防ぐ仕組みと料金](/tech/details/12685/)で解説しています。ESLintのflat config自体は[ESLintをVSCodeで使う設定手順](/tech/details/3286/)を参照してください。 ### React Scanは実行時、React Doctorは静的解析が中心 同じ開発者のReact Scan（npm 0.5.7）は、動いているアプリの再レンダリングをブラウザ上で可視化するツールです。React Doctorはソースを読むだけで判定するので、実際に遅いかどうかまでは分かりません。ただし0.9.18には`npx react-doctor@latest scan http://localhost:3000`もあり、手元のChromeを一時プロファイルで開いてDevToolsのパフォーマンストレースを最大5分記録します。トレースはローカルに保存され、アップロードはされません。描画の無駄を数字で確かめたい場面ではこちらかReact Scan、書き方の問題を一律に拾う場面では通常のスキャン、と分けると重複しません。React CompilerやHooksの書き方が指摘の多くを占めるため、[React Compilerとは？Vite・Next.js・Expoでの導入](/tech/details/9415/)と[Reactフック（Hooks）とは？全18種の一覧](/tech/details/3671/)も併せて読むと、指摘の理由を追いやすくなります。 ## 古い手順の見分け方と導入を見送る場面 React Doctorは版の進みが速く、検索で見つかる手順の多くが古くなっています。次の記述を見たら、0.9.18では動かないか非推奨だと判断してください。 - `--fix`や`--prompt`：v1発表時（2026年2月）の機能で、現行のCLIリファレンスにありません - `curl -fsSL https://react.doctor/install-skill.sh | bash`や`npx skills add`：現在は`npx react-doctor@latest install`に一本化 - `--diff`：`--scope changed`の非推奨の別名 - Actionの`fail-on`・`annotations`・`@main`：v2の`blocking`・`review-comments`・`@v2`へ 導入を見送るべき場面もあります。まず、コードや診断結果を社外のAPIへ一切出せない閉域環境では、スコアという看板機能が使えません。件数管理で足りるなら導入する価値はありますが、点数をKPIにする計画なら成立しません。次に、ESLintの`eslint-plugin-react-hooks`と`jsx-a11y`を既に厳しく運用しているチームでは、指摘の多くが既存のリントと重なり、上乗せになるのはeffect系やフレームワーク固有の指摘、複雑な関数・重複JSXの検査、サプライチェーン検査などです。導入前に`--scope full --blocking none`で1回走らせ、既存のリントで拾えていない指摘が何件あるかを数えてから決めるのが確実です。 ## React Doctorに関するよくある質問 ### React Doctorは無料で使えますか？ 社内の開発やCIでの利用は無料です。ライセンスは改変MITで、AIの学習・評価データとしての利用と、React Doctorを主な価値とする有償サービスとしての提供には、Million Software, Inc.の書面許諾が必要です。 ### React DoctorのGitHubリポジトリはどこですか？ github.com/millionco/react-doctor です。CLI本体は`packages/react-doctor`にあり、GitHub Actionの`action.yml`も同じリポジトリのルートに置かれています。ドキュメントはreact.doctor/docsで公開されています。 ### React Doctorとoxlintの関係は？ React Doctorは内部でoxlintを使ってルールを実行します。逆に、既にoxlintを使っているプロジェクトでは`oxlint-plugin-react-doctor`を入れると、React Doctorのルールをoxlintの中で動かせます。その場合スコアと依存パッケージ検査は付きません。 ### npx react-native doctorとは別物ですか？ 別物です。`npx react-native doctor`はReact Native CLIのコマンドで、Node.js・iOS・Androidの開発環境の不備を診断して直します。Expoの`npx expo-doctor`もプロジェクトの既知の問題を調べるツールです。React Doctorはコードの書き方を検査するもので、React Nativeのプロジェクトにも使えます。Expoでは依存関係や設定の静的チェックも行いますが、ネイティブ開発環境全体を診断するツールの代替にはなりません。 ### 設定ファイルの名前は何ですか？ `doctor.config.ts`・`doctor.config.json`など、`doctor.config.*`の8形式のどれかです。`package.json`の`reactDoctor`キーでも構いません。同じディレクトリに複数あると最初に見つかった有効な1つだけが使われるので、1ディレクトリ1ファイルにしてください。 ## 関連記事 - [OxlintとESLintの違いとは？読み方・速度実測・移行手順とBiomeとの比較【1.88対応】](/tech/details/8351/) - [ESLintをVSCodeで使う設定手順｜ESLint 10のflat configと保存時の自動修正【10.13対応】](/tech/details/3286/) - [React Compilerとは？Vite・Next.js・Expoでの導入とRust版・ESLint・useMemoの扱い【2026年10月】](/tech/details/9415/) - [socket.devとは？npm/PyPIのサプライチェーン攻撃を防ぐ仕組みと料金](/tech/details/12685/) - [静的コード解析の誤検知と限界｜レビュー・テストとの責任分担](/tech/details/7475/) --- 出典: [React Doctorとは？使い方・スコアの仕組み・CI設定とESLintとの違い【0.9.18対応】]()（株式会社一創）