React開発現場でコード品質を維持するために必要なReact Doctorという診断ツールの全体像

React開発現場でコード品質を維持するために必要なReact Doctorという診断ツールの全体像

Reactで構築されたフロントエンドプロジェクトが大規模化するにつれ、コンポーネントの設計品質やセキュリティ上の問題を人力だけで管理することは困難になっていきます。コードレビューで見落とされがちなパフォーマンス上のアンチパターンや、依存関係の肥大化による保守性の低下は、リリース後のトラブルとして表面化するケースも少なくありません。React Doctorは、こうしたReact開発に特有の課題を1コマンドで可視化し、改善の優先順位まで示してくれるオープンソースの静的解析ツールです。この章では、React Doctorがどのような背景で生まれ、どんな特徴を持つのかを俯瞰的に整理します。

Million.js開発元が提供するReact特化型静的解析ツールとしての位置づけと設計思想

React Doctorは、高速な仮想DOM実装で知られるMillion.jsの開発元であるMillion Software, Inc.が提供するオープンソースツールです。開発者のAiden Bai氏は16歳でMillion.jsを公開し、その後React ScanやReact Grabなど複数のReact関連ツールを手がけてきた実績を持っています。これらの開発経験から蓄積されたReactエコシステムへの深い知見が、React Doctorの診断ルール設計にも反映されています。

汎用的なJavaScriptリンターとは異なり、React Doctorの設計思想は「Reactプロジェクトに特化した実践的な診断」に集中している点が最大の特徴です。47以上のベストプラクティスルールはすべてReactの実務で頻出する問題パターンをカバーしており、セキュリティ・パフォーマンス・正確性・アーキテクチャの4軸で横断的にコードベースを評価します。さらに、AIコーディングエージェントとのスキル連携を前提とした設計がなされており、検出した問題をそのまま自動修正のワークフローに接続できる点も、従来のリンターにはない発想といえます。

セキュリティ・パフォーマンス・正確性・設計の4カテゴリで診断する仕組みと検出精度

React Doctorの診断は、大きく4つのカテゴリに分類されます。1つ目のセキュリティ領域では、dangerouslySetInnerHTMLの使用やXSSに繋がるパターンなど、ブラウザ上で実害が出るリスクを検出します。2つ目のパフォーマンス領域では、不必要な再レンダリングを引き起こすインライン関数定義やメモ化の不備を指摘します。

3つ目の正確性（Correctness）領域は、Hooksの呼び出し順序違反やリストレンダリング時のkey属性欠落など、Reactの仕様に起因するランタイムエラーを未然に防ぐルール群です。4つ目のアーキテクチャ領域は、デッドコードの蓄積やエクスポート構造の問題など、保守性に影響する設計上の課題を洗い出します。各診断結果にはerrorまたはwarningの重大度が付与されるため、対応の緊急度を客観的に判断することが可能です。この4軸構造により、単なるスタイルチェックにとどまらない実践的なコード健全性評価が実現されています。

GitHub Stars 2,000超のOSSが支持される理由と開発コミュニティの活発度

React DoctorはGitHub上で2,000以上のStarを獲得しており、React関連の開発ツールのなかでも高い注目度を示しています。リポジトリには約60のフォークが存在し、少数のコアコントリビューターによる活発な開発が継続されています。急速にStar数を伸ばしている成長期のプロジェクトであり、ツールの将来性を評価するうえで注目すべき指標です。

支持を集めている背景には、「1コマンドで実行できる手軽さ」と「診断結果の具体性」という2つの要素があります。ESLintのように複雑な初期設定を必要とせず、npx react-doctor@latest .を実行するだけで即座にスコアと改善提案が得られます。また、公式リポジトリのREADMEにはtldraw（84点）やSupabase（69点）といった著名OSSプロジェクトのスコアが公開されており、自分のプロジェクトとの比較ができる点もコミュニティの関心を集めている理由の一つです。

Next.js・Vite・Remixなど主要フレームワーク対応状況と自動検出の動作条件

React Doctorは、プロジェクトルートのディレクトリを指定するだけで、使用しているフレームワークやReactのバージョンを自動検出する仕組みを備えています。公式ドキュメントではnpmキーワードに「nextjs」が含まれており、Reactベースの主要なフレームワークでの動作が想定されています。特別な設定ファイルを事前に用意する必要はありません。

プログラマティックAPIを利用した場合、result.projectプロパティから検出されたフレームワーク名やReactバージョンの情報を取得できるため、自動レポート生成時に環境情報を含めることも可能です。ただし、React以外のライブラリ（Vue.jsやAngularなど）で構築されたプロジェクトは診断対象外となります。TypeScriptで記述されたReactプロジェクトにも対応しており、JSX・TSXファイルの双方を解析対象に含めます。この幅広い対応範囲が、さまざまな技術スタックのチームで導入しやすい理由となっています。

CLIとプログラマティックAPIの2系統で利用できる柔軟なインターフェース設計

React Doctorには、ターミナルから直接実行するCLIインターフェースと、Node.jsコード内から呼び出せるプログラマティックAPIの2つの利用手段が用意されています。CLIはnpx -y react-doctor@latest .のようにワンライナーで実行でき、開発者個人のローカル環境での手軽な品質チェックに最適です。オプションも豊富で、--verboseによる詳細表示、--scoreによるスコアのみの出力、--diffによる差分スキャンなど、用途に応じた使い分けが可能になっています。

一方のプログラマティックAPIは、import { diagnose } from "react-doctor/api"でインポートし、diagnose関数にプロジェクトパスを渡すことで結果オブジェクトを取得する仕組みです。戻り値にはスコア、診断配列、プロジェクト情報が含まれるため、独自のダッシュボードやSlack通知との統合など、チーム独自のワークフローに組み込む拡張的な用途に向いています。この2系統の設計により、個人の日常利用からチーム単位の自動化運用まで幅広い導入形態に対応できる構造になっています。

セキュリティからアーキテクチャまで47以上の診断ルールが検出する問題領域と対象範囲

React Doctorが備える47以上の診断ルールは、実務でよく遭遇するReact特有の問題パターンを体系的にカバーしています。各ルールはセキュリティ・パフォーマンス・正確性・アーキテクチャのいずれかに分類され、単なるコーディングスタイルの統一ではなく、アプリケーションの品質や安全性に直結する問題を優先的に検出する設計です。この章では、各領域の代表的なルールと、その検出がプロジェクトにもたらす具体的なメリットを掘り下げます。

dangerouslySetInnerHTMLやXSS関連など見落としがちなセキュリティルール5選の検出例

Reactアプリケーションにおけるセキュリティリスクの多くは、開発者が無意識に使用してしまうAPIの誤用から生じます。React Doctorのセキュリティ系ルールは、こうした見落としやすい問題を静的解析で検出します。代表的なのがreact/no-dangerルールで、dangerouslySetInnerHTMLの使用箇所を警告します。このプロパティはサニタイズされていないHTMLを直接DOMに挿入する手段であり、XSS（クロスサイトスクリプティング）攻撃の起点になりやすいため、原則として使用を避けるべきとされています。

そのほかにも、ユーザー入力値がそのままレンダリングに渡されるパターンや、外部ライブラリを介した間接的なスクリプト注入のリスクを検出するルールが含まれます。セキュリティ系のルールはseverityがerrorに設定されているケースが多く、スコアへの影響度も高い傾向にあります。コードレビューの段階でこれらの問題が自動検出されることで、脆弱性がプロダクション環境に持ち込まれるリスクを大幅に低減できます。

不要な再レンダリングやメモ化漏れを特定するパフォーマンス系ルールの判定基準

Reactアプリケーションのパフォーマンス劣化でもっとも頻度が高い原因は、不必要なコンポーネントの再レンダリングです。React Doctorのパフォーマンス系ルールは、この問題を引き起こす典型的なコードパターンを静的に検出します。たとえば、レンダリング関数内でインライン定義されたオブジェクトや関数は、毎回新しい参照を生成するため、子コンポーネントの無駄な再レンダリングを誘発します。

React.memoやuseMemo、useCallbackによるメモ化が適切に行われていない箇所も検出対象です。ただし、React Doctorは過剰なメモ化を推奨するわけではなく、実際にパフォーマンスへの影響が見込まれる箇所に限定して警告を出す設計となっています。この判定基準の絞り込みにより、メモ化の過剰適用というもう一つのアンチパターンを避けつつ、本当に対処すべきボトルネックに集中できます。検出結果のhelp属性には具体的な改善手法が記載されるため、対処方法の調査コストも削減できます。

Hooks呼び出し順序やkey属性の欠落などReact固有の正確性ルールが防ぐ実行時エラー

Reactには、フレームワーク固有のルールに違反するとランタイムエラーやUI上の不具合が発生する特殊な制約があります。もっとも代表的なのが、Hooksの呼び出し順序に関するルールです。useStateやuseEffectなどのHooksは、コンポーネントのトップレベルで一貫した順序で呼び出される必要があり、条件分岐やループ内で呼び出すと予測不能な動作を引き起こします。React Doctorはこのパターンをerrorレベルで検出し、バグの発生を未然に防ぎます。

もう一つの頻出パターンが、リストレンダリング時のkey属性の欠落または不適切な値の使用です。key属性はReactの差分検出アルゴリズムがコンポーネントの同一性を判定するために使用する識別子であり、配列のインデックスをkeyに使用するとリストの並び替え時にUIが破損することがあります。React Doctorはkey属性の欠落だけでなく、インデックスベースのkeyに対しても警告を出す場合があります。こうした正確性ルールは、テストで発見しづらいバグを早期に排除するためにとくに有効です。

デッドコード検出機能が未使用エクスポートを洗い出す仕組みとknipプラグイン連携

プロジェクトが成長するにつれ、使われなくなったコンポーネントや関数がコードベースに残り続ける「デッドコード」の問題は深刻化します。React Doctorはデフォルトでデッドコード検出機能を有効にしており、未使用のエクスポートや到達不能なモジュールを自動的に洗い出します。この機能はknipプラグインと連携して動作し、プロジェクト全体の依存関係グラフを解析することで高い精度を実現しています。

デッドコードの蓄積は、バンドルサイズの肥大化やビルド時間の増加だけでなく、新規メンバーのオンボーディング時に不要なコードの理解に時間を費やすという隠れたコストも生じさせます。React Doctorの診断結果では、knip/exportsというルール名で未使用エクスポートが報告され、各検出箇所のファイルパスと行番号が明示されます。もし意図的に残しているエクスポート（ライブラリの公開APIなど）がある場合は、設定ファイルでknip/exportsルールを除外対象に追加することで誤検出を抑制できます。

react-doctor.config.jsonで特定ルールやファイルを除外するカスタマイズ設定の実務例

すべての診断ルールがすべてのプロジェクトに当てはまるわけではありません。React Doctorでは、プロジェクトルートにreact-doctor.config.jsonを配置することで、除外するルールやファイルパターンを細かく制御できます。設定ファイルのignoreオブジェクトにrules配列とfiles配列を指定する構造で、記述はシンプルです。

実務でよくある除外パターンとしては、自動生成コードのディレクトリ（例：src/generated/**）をfiles配列で除外するケースが挙げられます。GraphQLのスキーマ生成やOpenAPIからのクライアントコード生成では、ツールが出力するコードにReact Doctorのルールを適用しても改善の余地がないためです。また、意図的にdangerouslySetInnerHTMLを使用しているリッチテキストエディタ周辺のコードでは、react/no-dangerをrules配列で除外することも合理的な判断です。設定ファイルの代わりにpackage.json内のreactDoctorキーに同じ内容を記述する方法も用意されていますが、両方が存在する場合は設定ファイルが優先されます。

npx1コマンドで完了するReact Doctorのインストールから初回スキャンまでの実行手順

React Doctorの最大の魅力の一つが、導入の手軽さです。グローバルインストールや依存パッケージの追加を必要とせず、npxコマンド1行で即座に診断を開始できます。この章では、初回実行から各種オプションの活用まで、段階的に解説します。

Node.js環境さえあれば即実行できるnpxコマンドの具体的な記述と実行結果の読み方

React Doctorの最小構成での実行は、ターミナルでプロジェクトルートに移動し、以下のコマンドを入力するだけです。

npx -y react-doctor@latest .

-yフラグはnpxの対話プロンプトをスキップするオプションで、CI環境での利用時にも役立ちます。末尾のドット（.）は現在のディレクトリを解析対象として指定することを意味します。コマンドを実行すると、React Doctorはプロジェクト内のJSX・TSXファイルを走査し、47以上のルールに基づく診断を行います。実行結果にはプロジェクト全体の0〜100スコアと、検出された問題のサマリーが表示されます。スコアはGood（高品質）からNeeds Improvement（改善必要）までのラベルとともに出力されるため、プロジェクトの品質水準を直感的に把握することが可能です。Node.jsがインストールされている環境であれば、追加の依存関係なしに即座に利用を開始できるため、導入判断のハードルがきわめて低い点も特徴です。

–verboseオプションで影響ファイルと行番号まで表示させる詳細診断の活用手順

標準出力ではルールごとの違反件数がサマリー表示されますが、実際の修正作業に取りかかるには、どのファイルの何行目に問題があるのかという具体的な位置情報が必要です。--verboseオプションを付与して実行すると、各ルール違反に対してファイルパスと行番号が一覧表示されます。

npx -y react-doctor@latest . --verbose

この詳細出力は、問題件数が多いプロジェクトでとくに効果を発揮します。ファイル単位で問題が集中している箇所を特定できるため、影響範囲の大きいファイルから優先的に着手するトリアージが可能になるからです。また、出力結果をテキストファイルにリダイレクトしておけば、コードレビュー時の参照資料やチームへの共有素材としても活用できます。日常的な開発ではサマリー表示で全体の傾向を把握し、具体的な修正フェーズに入った段階でverboseに切り替えるという2段階の使い分けが実務上は効率的です。

–diffオプションでPR差分のみスキャンしレビュー工数を削減する実務運用パターン

大規模なReactプロジェクトでは、全ファイルを毎回スキャンすると実行時間が長くなり、CI/CDのボトルネックになることがあります。--diffオプションは、指定したベースブランチからの変更ファイルのみをスキャン対象に絞り込む機能です。

npx -y react-doctor@latest . --diff main

このコマンドはmainブランチとの差分ファイルだけを解析し、新たに追加・変更されたコードに含まれる問題のみを報告します。プルリクエスト単位のコードレビューと組み合わせることで、レビュアーが見るべき問題点を事前にフィルタリングできるため、レビュー工数の削減に直結します。とくにフィーチャーブランチ運用を採用しているチームでは、PRを作成するたびに自動で差分スキャンを実行するワークフローを構築することで、品質チェックの漏れを防ぐ体制が構築できます。ベースブランチの指定を省略した場合は、デフォルトのブランチが自動的に参照されます。

モノレポ構成で–projectオプションを使い複数プロジェクトを個別診断する方法

TurborepoやNxなどのモノレポ構成を採用している開発現場では、1つのリポジトリ内に複数のReactアプリケーションやパッケージが共存しています。React Doctorの--projectオプションは、こうしたワークスペース内の特定プロジェクトを選択して個別に診断するための機能です。

npx -y react-doctor@latest . --project 1

プロジェクト番号はカンマ区切りで複数指定でき、--project 1,3のように記述すれば特定のプロジェクトだけを対象にスキャンが実行されます。また、-y（--yes）オプションと組み合わせると、すべてのワークスペースプロジェクトを対話プロンプトなしで一括スキャンすることも可能です。モノレポ環境では各パッケージの品質水準にばらつきが出やすいため、プロジェクトごとのスコアを定期的に記録し、品質低下の傾向を早期に検知する運用が推奨されます。

初回実行時のスキル自動インストールプロンプトとpackage.json設定の2つの導入経路

React Doctorを初めて実行すると、AIコーディングエージェント向けのスキルファイルを自動インストールするかどうかを尋ねるプロンプトが表示されます。ここで承認すると、CursorやClaude Codeなどのエージェントが47以上のReactベストプラクティスルールを参照できるスキルファイルがプロジェクトに追加されます。この仕組みにより、診断ツールとAIによる自動修正をシームレスに接続する環境が初回実行時点で整います。

もう一つの導入経路として、npx skills add millionco/react-doctorコマンドを使って手動でスキルを追加する方法もあります。チームメンバー全員が同じスキル設定を共有したい場合は、この手動追加の方が管理しやすくなります。さらに、プロジェクトのdevDependenciesにreact-doctorを追加し、package.jsonのscriptsセクションに"doctor": "react-doctor ."と記述しておけば、npm run doctorで日常的に診断を実行する運用フローを定着させることも容易です。チーム全体への展開を見据える場合は、このpackage.jsonへの組み込みがもっとも確実な導入経路といえます。

0〜100点スコアと診断レポートから読み解くコードベースの健全性と改善の優先度

React Doctorが出力する0〜100点のスコアは、プロジェクトの健全性を数値で把握できる指標です。しかし、スコアを単に高い・低いで判断するのではなく、何が減点要因になっているのかを分析し、適切な優先順位で対処することが品質改善の鍵になります。この章では、スコアの評価基準から具体的な改善戦略までを解説します。

tldraw84点・Supabase69点など著名OSSのスコア実例から見る評価基準の相場観

React Doctorの公式リポジトリには、著名なオープンソースプロジェクトのスコアがベンチマークとして公開されています。描画ツールのtldrawとexcalidrawがともに84点でトップクラス、プロジェクト管理ツールのtwentyとplaneが78点、フォームビルダーのformbricksが75点、分析プラットフォームのposthogが72点と続きます。さらに、BaaS基盤として広く利用されるSupabaseが69点、UI構築ツールのonlookも69点、ヘッドレスCMSのpayloadが68点、エラートラッキングのsentryが64点、スケジューリングのcal.comが63点、短縮URLサービスのdubが62点という結果になっています。

この一覧から読み取れるのは、世界的に利用されている著名プロジェクトでも満点近いスコアを出すことは容易ではないという現実です。70点台であれば品質の高い部類に入り、80点を超えていれば非常に優れたコードベースと評価できます。自分のプロジェクトが60点台であったとしても、それは改善の余地があるという示唆であり、直ちに品質が低いと判断する基準にはなりません。これらのベンチマークを自身のプロジェクトスコアと比較することで、現実的な改善目標を設定できます。

error・warningの重大度分類とfilePath・line情報を使った修正対象の特定フロー

React Doctorの各診断結果は、Diagnosticオブジェクトとして構造化されています。このオブジェクトには、filePath（対象ファイルのパス）、rule（ルール名）、severity（errorまたはwarning）、message（問題の説明）、help（修正方法の提案）、lineおよびcolumn（問題箇所の位置）、category（問題カテゴリ）が含まれます。

修正作業を効率的に進めるためには、まずerrorレベルの問題を優先的に解消し、その後warningレベルに着手するという流れが基本です。errorはセキュリティリスクやランタイムエラーに直結する問題が多く、放置するとユーザーに実害が及ぶ可能性があります。一方、warningはパフォーマンスや保守性に関わる改善提案が中心で、即座の対処が必要ないケースもあります。help属性に記載された修正提案を参考にすることで、各問題に対する具体的な対処法を把握できるため、診断結果を見るだけで改善アクションに移行しやすい設計になっています。

スコアが60点未満のプロジェクトで優先すべきセキュリティ系ルールの対処順序

スコアが60点未満のプロジェクトでは、すべての問題を一度に解消しようとすると工数が膨大になり、改善が頓挫するリスクがあります。このような場合は、対処の優先順位を明確にしたうえで段階的に改善を進めることが重要です。もっとも優先度が高いのはセキュリティカテゴリのerror項目で、XSSやスクリプト注入に関連するルール違反はリリース前に必ず解消すべき問題です。

次に着手すべきは、正確性カテゴリのerror項目です。Hooksの呼び出し順序違反やkey属性の欠落は、特定の操作パターンでのみ顕在化するため、テストをすり抜けやすい特徴があります。その後、パフォーマンスカテゴリのwarning項目に取り組み、最後にアーキテクチャ系（デッドコードなど）の整理に移ります。この順序で進めると、ユーザーに直接影響のある問題から先に解消されるため、限られた工数のなかでもっとも効果的にリスクを低減できます。1回のスプリントで5〜10点程度のスコア改善を目標にするのが現実的なペースです。

–scoreオプションでスコアだけ出力しCI判定の合否ラインに活用する数値設計

React Doctorの--scoreオプションは、詳細な診断結果を省略してスコア数値のみを標準出力するためのフラグです。この出力をCI/CDパイプラインのシェルスクリプトで受け取り、しきい値と比較することで、一定のスコアを下回った場合にビルドを失敗させるゲート判定が実装できます。

npx -y react-doctor@latest . --score

しきい値の設定においては、現在のプロジェクトスコアに対して5〜10点の余裕を持たせた値を初期設定とし、品質改善が進むにつれて段階的に引き上げていくアプローチが推奨されます。たとえば、現在のスコアが65点であれば、初期のしきい値を60点に設定し、チームの改善活動によってスコアが安定して70点台に達した段階で65点に引き上げるといった運用です。この段階的なアプローチにより、既存コードの大量修正を強いることなく、新規コードの品質劣化を防止する仕組みを構築できます。

定期スキャンによるスコア推移の記録が技術的負債の可視化につながる改善効果

React Doctorのスコアを一度きりのチェックで終わらせず、定期的に記録・追跡することで、プロジェクトの品質推移を時系列で把握できるようになります。週次や隔週でスコアを記録し、スプレッドシートやダッシュボードに蓄積していくと、どのタイミングで技術的負債が増加したかが可視化されます。大量のフィーチャー追加が行われたスプリント後にスコアが低下していれば、次のスプリントで品質改善タスクを組み込むべきという判断材料になります。

プログラマティックAPIを活用すれば、スキャン結果をJSON形式で出力し、データベースやモニタリングツールに自動投入するパイプラインも構築可能です。この仕組みは、技術的負債の存在を「体感」ではなく「数値」で示す手段として、エンジニアリングマネージャーやプロダクトオーナーとのコミュニケーションにも役立ちます。品質が下がればスコアが下がるという明確な因果関係があることで、品質改善のための工数確保を経営層に説明する際の説得力が大きく向上します。

ESLint・React Scanとの役割の違いからわかるReact Doctorを選ぶべき開発現場の条件

Reactプロジェクトのコード品質を管理するツールは複数存在しますが、それぞれのツールには得意領域と限界があります。React Doctorの価値を正確に理解するには、ESLintやReact Scanとの機能的な違いを把握し、自分の開発現場に最適な組み合わせを選択することが重要です。

ESLintが汎用ルール適用に強い一方でReact Doctorが専門診断に特化する機能差

ESLintはJavaScript・TypeScript全般を対象とする汎用的なリンターであり、Reactに特化したルールはeslint-plugin-reactやeslint-plugin-react-hooksといったプラグインで拡張する形式をとります。コーディングスタイルの統一、変数の未使用検出、構文エラーの検出など、広範な領域をカバーできる反面、設定ファイルの記述が複雑になりやすく、プラグイン間の競合やバージョン管理に手間がかかるという課題があります。

React Doctorは、ESLintのような汎用的なスタイルチェックを目的とするツールではなく、Reactアプリケーションの実践的な品質課題に焦点を当てています。セキュリティ・パフォーマンス・正確性・アーキテクチャの4軸評価、デッドコード検出、0〜100のスコアリング、AIエージェント連携といった機能は、ESLint単体では実現できません。両者は競合関係ではなく補完関係にあるため、ESLintでコーディングスタイルを統一し、React Doctorでアプリケーション品質を診断するという併用が、もっとも実務的な構成です。

React Scanがランタイム再レンダリング検出に強い一方で静的解析をカバーしない領域

React Scanは同じくAiden Bai氏が開発したパフォーマンス診断ツールですが、React Doctorとはアプローチが根本的に異なります。React Scanはアプリケーションを実際にブラウザで動作させ、ランタイムでの再レンダリングを視覚的にハイライト表示するツールです。どのコンポーネントが何回再レンダリングされているかをリアルタイムで確認でき、ブラウザ上で問題箇所を直感的に特定できる点が強みです。

一方で、React Scanはコードを実行しなければ分析が行えないため、セキュリティ上の脆弱性やアーキテクチャ上の問題、デッドコードの検出といった静的解析の領域はカバーしていません。React Doctorはコードを実行せずにソースファイルを解析する静的解析ツールであるため、CI/CDパイプラインでの自動チェックやコードレビュー前の事前検証に適しています。ランタイムでの挙動確認にはReact Scan、コードの静的な品質保証にはReact Doctorという使い分けが、開発プロセス全体を通じた品質管理の最適解です。

47以上のルール・デッドコード検出・スコアリングを1コマンドで完結する統合力の優位性

React Doctorの最大の差別化ポイントは、複数のツールで個別に行っていた品質チェックを1つのコマンドに統合している点です。ESLintでリンティング、knipでデッドコード検出、独自スクリプトでスコア算出といった複数の工程を、npx react-doctor@latest .の一発で完了できます。この統合力は、とくにツールチェーンの管理コストを気にする小〜中規模チームにとって大きなメリットです。

さらに、個別ツールの組み合わせでは実現しづらい「カテゴリ横断の総合スコア」が算出される点も重要です。セキュリティ・パフォーマンス・正確性・アーキテクチャの各観点を統合した1つの数値として品質を表現できるため、チーム内での品質目標の共有が容易になります。個別ツールの出力を人間が総合判断する手間が省けるため、品質チェックの属人化も防げます。ただし、ESLintのような細かなスタイルルールのカスタマイズ性はReact Doctorの主目的ではないため、コーディング規約の厳密な適用が必要な現場ではESLintとの併用を前提とした設計が求められます。

eslint-plugin-reactとの併用パターンで補完関係を構築する設定例

React DoctorとESLintを併用する場合、両者の診断範囲が一部重複するルールについて整理しておく必要があります。React Doctorの診断ルールには、eslint-plugin-reactと同様の検出を行うものが含まれているため、重複するルールでは片方を無効化することで、警告の二重表示を防げます。

具体的な運用としては、ESLint側でコーディングスタイルや構文に関するルール（インデント、セミコロン、import順序など）を管理し、React Doctor側でReact固有の品質診断（セキュリティ・パフォーマンス・デッドコードなど）を担当するという役割分担が明確です。React Doctorの設定ファイルでESLintと重複するルールをignore対象に追加し、ESLint側ではReact Doctor がカバーするパフォーマンス系の一部ルールを緩和する構成にすると、互いの強みを活かした効率的な品質管理体制が構築できます。この補完構成は、既存のESLint環境にReact Doctorを追加導入する際の現実的な移行パターンとして推奨されます。

小規模個人開発と大規模チーム開発それぞれで最適なツール組み合わせの判断基準

プロジェクトの規模やチーム構成によって、最適なツール構成は異なります。個人開発や2〜3人の小規模プロジェクトでは、React Doctor単体の導入で十分な品質管理効果が得られるケースが多いです。設定ファイルの作成も不要で、必要なときにnpxで実行するだけで診断が完了するため、ツール管理のオーバーヘッドがほぼ発生しません。

大規模チームでは、React DoctorをCI/CDに組み込んで自動チェックを義務化しつつ、ESLintでコーディング規約を統一し、React Scanで開発中のパフォーマンス検証を行う3層構成が有効です。チームの人数が増えるほどコーディングスタイルのばらつきや品質のムラが発生しやすくなるため、自動化された品質ゲートの重要性が高まります。導入初期はReact Doctor単体からスタートし、チームの成熟度やプロジェクトの複雑性に応じてツールを追加していく段階的なアプローチが、もっとも失敗の少ない導入戦略です。

Cursor・Claude CodeなどAIエージェントとのスキル連携で実現する自動修正の実務効果

React Doctorの特徴的な機能の一つが、AIコーディングエージェントとのネイティブな連携機構です。診断結果を人間が解釈して修正するだけでなく、AIエージェントに直接ルールを学習させ、検出された問題の自動修正を依頼するワークフローが構築できます。この章では、連携の設定方法から実務での活用上の注意点までを整理します。

npx skills addコマンドで47以上のルールをAIエージェントに学習させるスキル登録手順

React DoctorのルールセットをAIコーディングエージェントに登録するには、npx skills add millionco/react-doctorコマンドを実行します。このコマンドにより、47以上のReactベストプラクティスルールが「スキル」としてプロジェクトに追加され、対応するAIエージェントがそのルールを参照できるようになります。

スキル登録が完了すると、エージェントはコード生成や修正提案の際にReact Doctorのルールを考慮した出力を行うようになります。たとえば、エージェントにコンポーネントの生成を依頼した場合、dangerouslySetInnerHTMLの使用を避け、適切なkey属性を付与し、Hooksの呼び出し順序を守ったコードが生成されやすくなります。この仕組みは、問題を事後的に検出して修正するのではなく、問題を含むコードがそもそも生成されないようにするという予防的なアプローチを可能にする点で、従来のリンティングとは質の異なる品質向上効果があります。

Cursor・Claude Code・Copilotの3大AIエージェント別の連携設定と動作確認方法

React Doctorのスキル連携は、Cursor、Claude Code、GitHub Copilotの3つの主要AIコーディングエージェントに対応していることが公式READMEで明示されています。いずれのエージェントでも、スキルファイルがプロジェクト内に配置されていれば参照される設計になっています。

具体的な連携の流れとしては、npx skills add millionco/react-doctorの実行によりプロジェクト内にスキルファイルが生成され、各AIエージェントがそのファイルをコンテキストとして読み込む仕組みです。スキル連携の規格はskills.shプラットフォームに基づいており、対応エージェントであれば追加設定なしでルールを参照できます。スキル登録後に動作確認を行うには、意図的にルール違反を含むコードの修正をエージェントに依頼し、React Doctorのルールに基づいた修正提案が返ってくるかを確認するのが確実な方法です。なお、各エージェント側のスキル読み込みの詳細な仕様は、それぞれのエージェントの公式ドキュメントを参照することを推奨します。

–fixオプションでAmiを起動し検出問題を自動修正するワークフローの具体的な流れ

React Doctorの--fixオプションは、検出された問題をAIデスクトップコーディング環境「Ami」に引き渡して修正を実行する機能です。コマンドラインでnpx -y react-doctor@latest . --fixと入力すると、スキャン完了後にAmiが起動し、修正可能な問題に対して自動的にコード変更を適用します。

自動修正の対象となるのは、パターンが明確で修正方法が一意に定まる問題が中心です。たとえば、不要なインポートの削除、key属性の追加、非推奨APIの置き換えなど、機械的に処理できる修正がこれに該当します。一方で、アーキテクチャ上の設計判断が必要な問題や、ビジネスロジックに影響する変更は自動修正の対象外となる場合があります。自動修正後は必ずgit diffで変更内容を確認し、意図しない修正が含まれていないかをレビューする運用が推奨されます。このワークフローにより、単純な修正作業にかかる時間を大幅に短縮しながら、品質管理の最終判断は人間が担保するバランスの取れた運用が実現できます。

–promptオプションで診断結果をクリップボードにコピーしAIに渡す手動連携の活用例

--fixオプションによる自動修正とは別に、--promptオプションを使った手動連携も実務上有用です。このオプションを付与して実行すると、直近のスキャン結果がクリップボードにコピーされ、任意のAIチャットインターフェースにそのまま貼り付けて修正依頼を出すことができます。

npx -y react-doctor@latest . --prompt

この手動連携が役立つのは、自動修正では対応しきれない複雑な問題に取り組む場面です。たとえば、パフォーマンス系の警告に対してコンポーネント構造の再設計が必要な場合、診断結果をAIに提示し、「このコンポーネントの再レンダリングを減らすためのリファクタリング案を提示してください」といった形で対話的に修正方針を検討できます。自動修正が得意とする定型的な修正と、手動連携が得意とする設計判断を伴う修正を使い分けることで、診断結果を漏れなく改善アクションに変換できます。

AI自動修正を鵜呑みにせず人間レビューを組み合わせるべき3つの失敗パターン

AIエージェントによる自動修正は生産性を大きく向上させますが、修正結果を無条件に採用することにはリスクが伴います。実務で発生しやすい失敗パターンを理解しておくことが、AIとの効果的な協働には不可欠です。

1つ目の失敗パターンは、自動修正がビジネスロジックの意図を損なうケースです。AIはコードの構文的な正しさは判断できますが、そのコードがなぜそのように書かれたのかという背景まで完全に理解しているわけではありません。意図的に最適でない書き方を選択している箇所（レガシーAPIとの互換性維持など）が自動修正されると、別の不具合を生む可能性があります。2つ目は、自動修正が新たなルール違反を生むケースです。ある問題を解消するために加えた変更が、別のルールに抵触する場合があります。3つ目は、テストカバレッジが不十分な状態で自動修正を適用し、動作確認が不十分なままマージしてしまうケースです。自動修正後はReact Doctorを再実行してスコアが改善していることを確認し、テストスイートを通過させたうえでコードレビューを受けるという3段階のチェックを習慣化することが推奨されます。

CI/CDパイプラインへの組み込みでチーム全体のReactコード品質基準を統一する運用設計

React Doctorを個人の開発環境で利用するだけでは、チーム全体の品質水準を均一に保つことはできません。CI/CDパイプラインに組み込むことで、すべてのコード変更に対して自動的に品質チェックが適用され、基準を下回るコードのマージを防止する仕組みが構築できます。この章では、具体的な実装例から段階的な展開戦略までを解説します。

GitHub Actionsのワークフローにreact-doctorを組み込む具体的なYAML設定例

GitHub Actionsを利用する場合、ワークフローファイルにReact Doctorの実行ステップを追加するだけでCI統合が完了します。プルリクエストの作成やプッシュをトリガーにして自動実行する構成が一般的です。

基本的なYAML設定では、Node.jsのセットアップ後にnpm installで依存関係をインストールし、続いてnpx -y react-doctor@latest . --scoreを実行する流れになります。この構成により、PRを作成するたびにReact Doctorのスコアが算出され、実行ログに記録されます。実行結果をPRのコメントとして自動投稿するステップを追加すれば、レビュアーがCIのログを確認しなくてもスコアを即座に把握できるようになります。ワークフローの実行時間は、プロジェクトの規模によりますが、中規模プロジェクト（ファイル数500程度）で30秒〜1分程度が目安です。

–scoreオプションとしきい値判定を組み合わせたマージブロック自動化の実装方法

スコアを記録するだけでなく、一定のしきい値を下回った場合にPRのマージをブロックする自動化を実装することで、品質基準の強制適用が可能になります。実装方法としては、シェルスクリプトでReact Doctorのスコア出力を変数に格納し、条件分岐でしきい値と比較するアプローチが最もシンプルです。

スコアがしきい値を下回った場合にexit 1を返すことで、GitHub Actionsのステップが失敗扱いとなり、ブランチ保護ルールと組み合わせることでマージが自動的にブロックされます。しきい値の初期設定は、チームの現在のスコア水準から5〜10点低い値にしておくと、既存コードによる即座のブロックを回避しつつ、新たな品質低下を防止できます。この設定をブランチ保護ルールの「Required status checks」に登録しておけば、品質チェックをパスしていないPRはマージボタンがグレーアウトされ、物理的にマージ不可能な状態になります。チームメンバーが意図的にチェックをスキップすることを防げるため、品質基準の属人化を排除できます。

–diff baseオプションでPR単位のスキャンに絞りCI実行時間を短縮する最適化設計

プロジェクトの全ファイルをCI上で毎回スキャンすると、規模が大きくなるにつれて実行時間が増加し、PRのフィードバックループが遅延します。--diffオプションを活用し、PRで変更されたファイルのみをスキャン対象にすることで、この問題を解決できます。

GitHub Actionsの場合、npx -y react-doctor@latest . --diff origin/mainと指定することで、mainブランチからの差分ファイルのみが解析されます。変更が数ファイルに限定されるPRであれば、スキャン時間は数秒まで短縮できます。ただし、差分スキャンのみに依存すると、既存コードに埋もれている問題が検出されないという注意点があります。対策として、差分スキャンをPRのトリガーで実行し、全体スキャンを深夜や週末の定期バッチとして別途実行する2層構成が実務上は効果的です。差分スキャンで新規問題の混入を防ぎつつ、定期スキャンでプロジェクト全体の品質トレンドを継続的にモニタリングする運用が実現できます。

プログラマティックAPIのdiagnose関数を使いカスタムレポートを生成する拡張パターン

React DoctorのプログラマティックAPIを利用すると、診断結果をプログラムで処理し、チーム独自のレポート形式に変換する拡張が可能です。diagnose関数の戻り値には、スコア、診断配列、プロジェクト情報が構造化されたオブジェクトとして含まれるため、これを任意の形式に加工できます。

たとえば、診断結果をカテゴリ別に集計してSlackチャンネルに投稿するスクリプトや、スコア推移をグラフ化してConfluenceページに自動更新する仕組みなどが構築できます。result.diagnostics配列の各要素にはcategoryプロパティが含まれるため、セキュリティ・パフォーマンス・正確性・アーキテクチャごとの問題件数を集計するのも容易です。また、lintとdeadCodeのオプションを個別に制御できるため、「デッドコード検出のみ実行してレポート化する」といった用途特化のスクリプトも作成できます。この拡張性の高さが、組織固有のワークフローにReact Doctorを深く統合する際の大きな利点になります。

チーム導入初期にignore設定で段階的にルールを厳格化するロードマップの設計例

既存の大規模プロジェクトにReact Doctorを導入する際、初日からすべてのルールを有効にすると、大量の警告が出力されてチームが対応しきれない状態に陥る可能性があります。このような場合は、react-doctor.config.jsonのignore設定を活用し、段階的にルールを厳格化していくロードマップを設計することが現実的です。

導入初期の第1フェーズ（1〜2週間）では、セキュリティカテゴリのerrorルールのみを有効にし、それ以外のルールをignoreに追加します。この段階でセキュリティ上の重大な問題を優先的に解消します。第2フェーズ（3〜4週目）では正確性カテゴリのルールを有効化し、Hooksの呼び出し違反やkey属性の欠落に対処します。第3フェーズ（2ヶ月目以降）でパフォーマンスとアーキテクチャのルールを追加し、最終的にすべてのルールを有効にする構成を目指します。各フェーズの移行タイミングでは、React Doctorのスコアが前フェーズで設定した目標値に達しているかを確認し、達成していれば次のフェーズに進むという判断基準を設けることで、チームに過度な負荷をかけずに品質水準を段階的に引き上げることができます。