setup-doctor

setup-doctor

プロジェクト内およびユーザーレベルでの AI コーディングエージェントの設定を監査し、結果を 0〜100 点で採点して、修正が必要な項目を具体的に示します。また、ローカルでの利用状況をまとめ、共有可能なカードを作成します。

上のバッジは、このリポジトリ自体に対して setup-doctor を実行して算出したスコアです。

特長

• Doctor は、指示ファイル、スキル、サブエージェント、MCP サーバー、プラグイン、設定、フックを監査します。6 つのカテゴリにわたる 30 のルールを実行し、スコア、評価（優秀、良好、要改善、不十分）と、各検出結果に対する具体的な修正方法を報告します。
• Wrapped は、ローカルのセッションログ（セッション数、利用日数、トークン数、推定コスト、連続利用日数、ペルソナラベル）をまとめ、共有可能なカードを SVG 形式で作成します。オプションで PNG 形式も作成できます。
• Badge は、README 用の静的またはライブのスコアバッジを作成します。
• HTML レポート は、ネットワークリクエストを一切行わない、単一の自己完結型ファイルを生成します。
• MCP サーバー は、あらゆる MCP クライアントで Doctor と Wrapped を読み取り専用ツールとして利用できるようにします。

クイックスタート

インストールは不要です。プロジェクトのルートから実行してください。

npx setup-doctor

デフォルトのコマンドはプロジェクトを監査し、レポートを出力します。

Setup Doctor  score 85/100  (Good)   rules v1.2.0

Instruction files  29/30   Skills  n/a   MCP  n/a   Plugins  n/a   Settings  5/10   Freshness  n/a

Always-loaded context: about 0 tokens

HIGH  SET-02  Hook PreToolUse in .claude/settings.json points to scripts/missing.sh which is missing or not executable
      Fix: Correct the path, make the script executable, or remove the hook.
LOW   INS-01  No instruction file found for claude
      Fix: Create CLAUDE.md (or the agent's equivalent) with build and test commands, code style rules and a short project layout.

2 findings

検出結果に表示される絶対パスは、読みやすさのために短縮しています。

スコアと各検出結果の解釈方法については、開始ガイドをご覧ください。

コマンド

コマンド	用途
setup-doctor [doctor] [path]	設定を監査し、スコアを出力します。デフォルトのコマンドです。
setup-doctor wrapped	ローカルでの利用状況をまとめ、共有可能なカードを作成します。
setup-doctor badge	README 用のバッジファイルを作成します。
setup-doctor rules	すべてのルールと、そのカテゴリ、重大度、有効状態を一覧表示します。
setup-doctor explain <RULE_ID>	ルールのチェック内容と修正方法を説明します。
setup-doctor diff <before.json> <after.json>	保存済みの 2 つのレポートを比較し、スコアの変化を説明します。
setup-doctor mcp	stdio 経由で MCP サーバーを起動します。

すべてのフラグについては setup-doctor --help を実行するか、コマンドリファレンスをご覧ください。

対応エージェント

エージェント	Doctor	Wrapped
Claude Code	完全対応（30 ルールすべて）	対応
Codex	指示と MCP のルール	対応
GitHub Copilot CLI	指示、スキル、MCP、設定、フック	対応
Cursor	指示、MCP、プロジェクトのスキル	対応（Node 22.5 以降が必要）
その他のエージェント（.windsurfrules、.clinerules）	指示ルールのみ	非対応

エージェントに適用されないカテゴリ（例：Codex のプラグイン）は、失敗として数えるのではなく、スコアの対象から除外されます。詳しくはエージェントをご覧ください。

インストール

方法	コマンドまたは場所
npm（インストール不要）	npx setup-doctor
Homebrew	brew install saxenakapil/setup-doctor/setup-doctor
Claude Code プラグイン	Anthropic のプラグインディレクトリで利用できます。/setup-doctor:doctor と /setup-doctor:wrapped を提供します。
Cursor スキル	skills-cursor/ をプロジェクトの .cursor/skills/ にコピーしてください。Cursor スキルをご覧ください。
MCP クライアント	公式 MCP Registry に io.github.saxenakapil/setup-doctor として登録されています。MCP サーバーをご覧ください。
GitHub Action	saxenakapil/setup-doctor-action@v1。CI 統合をご覧ください。
pre-commit	このリポジトリをフックソースとして追加してください。CI 統合をご覧ください。

共通オプション

オプション	コマンド	説明
--agent claude|codex|cursor|copilot|all	doctor, badge, wrapped	読み込むエージェントを指定します。Doctor と badge はデフォルトで自動検出します。Wrapped のデフォルトは claude です。
--scope project|global|all	doctor, badge	チェックする場所を指定します。
--format terminal|json|html	doctor	出力形式を指定します。
--ci --fail-under <n>	doctor	スコアが n を下回った場合、終了コード 1 で終了します。
--ci --compare	doctor	前回の記録結果と比較し、スコアが下がった場合、終了コード 1 で終了します。
--fix, --dry-run	doctor	安全で機械的に適用できる修正をプレビューまたは適用します。修正モードを参照してください。
--period 7d|30d|ytd|all|YYYY-MM-DD:YYYY-MM-DD	wrapped	期間を指定します。デフォルトは 30d です。
--anonymize, --show-projects, --no-cost	wrapped	プライバシーとコストに関する設定です。Wrappedを参照してください。
--config <path>	doctor, badge, rules, wrapped	<project>/.setupdoctorrc 以外の設定ファイルを使用します。設定を参照してください。

フラグの完全なリファレンス：doctor、wrapped。

バッジ

スコアを README に追加します。

npx setup-doctor badge

setup-doctor-badge.svg を書き込み、現在のスコアを含む Markdown スニペットを出力します。バッジを自動的に最新の状態に保つには、CI から shields.io エンドポイントファイルを公開します。CI 連携を参照してください。

プライバシーと安全性

• 実行時にネットワークへアクセスしません。 テレメトリーやアップデートの確認はありません。CI では自動チェックによってこれを強制します（scripts/check-no-network.mjs）。
• 監査によってエージェントの設定が変更されることはありません。 設定ファイルを編集するのは doctor --fix のみです。差分を表示し、確認を求めてから、先にバックアップを作成します。badge、wrapped、--out は新しい出力ファイルのみを書き込みます。
• シークレットは出力されません。 検出結果にはルールと場所が示されます。値は [REDACTED] と表示されます。
• 共有可能な出力に含まれるのは集計値のみです。 Wrapped カードとバッジには、プロンプト、ファイルパス、ユーザー名、リポジトリ名は含まれません。ローカルレポート（HTML と JSON）にはファイルパスが含まれる場合があるため、共有する前に確認してください。
• セッションログから読み取るのはメタデータのみです。 タイムスタンプ、モデル名、トークン数、ツール名を読み取ります。メッセージ本文は行ごとに破棄されます。
• アカウント、API キー、ログインは不要です。

ドキュメント

• はじめに：最初の実行方法と出力の読み方
• Doctor：監査オプション、出力形式、終了コードの一覧
• Wrapped：期間、プライバシー設定、カード、出力形式
• 修正モード：修正のプレビューと適用、バックアップ、修正可能な項目
• 設定：.setupdoctorrc、ルールの無効化、しきい値、無視パターン
• エージェント：各エージェントが読み取る内容と共有ファイルのスコア付け方法
• CI 連携：GitHub Actions、スコア履歴、PR コメント、バッジ、pre-commit
• MCP サーバー：MCP クライアントから Doctor と Wrapped を使用する方法
• Cursor スキル：Cursor に Doctor と Wrapped のスキルをインストールする方法
• トラブルシューティング：よくある問題と解決方法

リファレンスドキュメント：

• ルール：v1 ルールの仕様
• テーマ：ビジュアルテーマのデザイントークン
• 決定ログ：開発中に行った前提、逸脱、決定事項

コントリビューション

Issue とプルリクエストを歓迎します。プルリクエストを作成する前に、すべてのチェックを実行してください。

npm install
npm run check        # typecheck, tests, privacy guard, version sync, em dash guard
npm run build        # bundles src/bin.ts to dist/bin.js

各ルールは src/rules/ の独立したファイルにあり、test/fixtures/ にトリガー用フィクスチャとクリーンなフィクスチャがあります。ルールは正規化されたモデルを入力とする純粋関数です。ファイルシステムへのアクセスは、src/adapters/ 配下のアダプターのみで行われます。

ライセンス

MIT。詳細は LICENSE をご覧ください。同梱フォントのライセンス（SIL Open Font License 1.1）は src/data/fonts/LICENSES.md に記載されています。