Claude Code /checkup 詳細解説：コンテキストの整理、設定の修正、エージェントのセキュリティ向上

はじめに

Claude Codeに、より高度な組み込み設定チェックアップ機能が追加されました。バージョン2.1.205では、Anthropicが既存の/doctorワークフローを拡張し、設定問題の診断と修正が可能になりました。/checkupは同じセッション内ワークフローのエイリアスとして利用できます。

この変更は単一のスラッシュコマンドで起動されるため、一見小さな変更に見えます。しかし実際には、長期運用されるClaude Code環境でよく発生する問題、すなわち未使用のスキル、古いModel Context Protocolサーバー、過度に大きな指示ファイル、動作の遅いフック、古いインストール、繰り返し表示される権限プロンプトなどが徐々に環境を複雑化する問題に対処しています。

目的は単に問題を報告することだけではありません。更新されたチェックアップは環境を検査し、提案する変更内容を説明し、適用前に承認を求めることができます。

/checkup

正規のコマンドも使用可能です：

/doctor

ワンコマンド設定チェックアップ

Claude Code 2.1.205の変更ログによると、/doctorは現在、問題の診断と修正が可能な完全な設定チェックアップであり、/checkupはそのエイリアスです。

これは以下の個別のターミナルコマンドとは異なります：

claude doctor

ターミナルコマンドは、インタラクティブセッションを開始せずに、読み取り専用のインストールと設定の診断情報を出力します。一方、セッション内の/doctorまたは/checkupワークフローは、修正案を提案し、Claudeが利用可能なツールを通じてクリーンアップを調整できるため、より高度な処理が可能です。

Claude Codeの開発者Boris Cherny氏は、チェックアップが処理するよう設計された以下のジョブについて説明しています：

1. 未使用のスキル、MCPサーバー、プラグインのクリーンアップ
2. チェックイン済みのプロジェクト指示とローカルのCLAUDE.md指示の重複排除
3. 過度に大きなルートCLAUDE.mdをネストされたファイルと再利用可能なスキルに分割
4. 動作の遅いフックの特定と無効化
5. Claude Codeの最新バージョンへの更新
6. 適切な場合の自動モードのデフォルト有効化
7. 頻繁に拒否される読み取り専用コマンドの事前承認
8. 環境を低速または不安定にするその他の設定問題の検出

このコマンドは変更を加える前に確認を求めます。

チェックアップが実際に確認する項目

1. 未使用のスキル、MCPサーバー、プラグイン

Claude Codeはスキル、プラグイン、フック、MCPサーバーで拡張できます。これらの統合機能は便利ですが、成熟した環境では、もはや必要のないコンポーネントが蓄積されることがよくあります。

relevant.

過去の課題トラッカー用に追加されたままのMCPサーバーや、チームがもう使用していないワークフロー用に作成されたスキル、コマンドが置き換えられたにもかかわらず有効化されたままのプラグインなどが存在する可能性があります。

チェックアップにより、これらの未使用コンポーネントを明らかにし、削除または無効化を提案します。

これは重要です。ツールや指示は、現在のタスクに積極的に役立っていない場合でも、注意力やコンテキストを消費する可能性があるからです。無関係な統合が少なければ、権限モデルの監査も容易になります。

2. 重複または肥大化した CLAUDE.md の指示

CLAUDE.md ファイルは、Claude Code に対する永続的な指示を提供します。ビルドコマンド、コーディング規約、アーキテクチャに関する注意事項、テスト要件、プロジェクト固有のルールなどを含めることができます。

これらのファイルはセッションコンテキストに読み込まれます。Anthropic は各ファイルを簡潔に保ち、ネストされた指示ファイルを定期的に見直して、古くなったルールや矛盾するルールがないか確認することを推奨しています。

時間の経過とともに、プロジェクトでは以下のようないくつかの一般的な問題が発生する可能性があります。

• ローカルファイルとチェックイン済みファイルの両方に同じルールが存在する。
• コードベースが変更された後も古い指示が残っている。
• ルートファイルが、無関係な手順の長い集まりに成長する。
• チーム全体のルールとディレクトリ固有のルールが混在している。
• 詳細なワークフローが CLAUDE.md に保存されているが、オンデマンドのスキルとして使用した方が適している。

チェックアップは、ローカルの指示とプロジェクトの指示を比較し、重複を特定し、より焦点を絞った構造を提案します。

実用的なレイアウトは次のようになります。

project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── testing.md
│   └── skills/
│       └── release/
│           └── SKILL.md
└── packages/
    └── api/
        └── CLAUDE.md

ルートファイルには、リポジトリ全体で必要なルールのみを含めることができます。より具体的な指示は、Claude が関連ディレクトリ内で作業するときに読み込まれ、再利用可能な手順は、呼び出されたときに読み込まれるスキルになります。

3. 低速または冗長なフック

フックは、Claude Code のライフサイクルにおける特定の時点で実行される決定論的なアクションです。ファイルのフォーマット、コマンドの検証、ポリシーの適用、通知の送信、Claude Code と内部システムの統合などを行うことができます。

フックは、その価値がコストを正当化する場合にのみ有用です。ツール呼び出しのたびに 2、3 秒を追加するスクリプトは、長いセッション全体で大きな遅延を生み出す可能性があります。

チェックアップは、以下のようなフックを特定するのに役立ちます。

• 常に低速である。
• 意図したよりも頻繁にトリガーされている。
• 別の検証ステップと重複している。
• もはや存在しないスクリプトを参照している。
• ユーザーが無視することを学習したエラーを生成している。
• アクティブなワークフローに接続されていない。

不要なフックを無効にすると、速度が向上するだけでなく、ノイズが減り、重要な障害に気づきやすくなります。

4. インストールとアップデートの問題

ランチャーの破損、古いインストール、部分的なアップデートは、混乱を招く動作を引き起こす可能性があります。セットアップチェックアップは、インストールの健全性を検査し、Claude Code の更新を推奨できます。

インストールされているバージョンを手動で確認するには、以下を使用します。

claude --version

正確な更新方法は、Claude Code のインストール方法によって異なります。

マネージドエンタープライズデプロイメントでは、特定のバージョンを意図的に固定することがあります。そのため、ユーザーは新しいリリースが存在するという理由だけで組織のポリシーを上書きすべきではありません。

5. 読み取り専用権限の繰り返しプロンプト

Claude Codeは、リスクの低い調査と環境を変更するアクションを分離する権限システムを使用しています。

Anthropicのセキュリティドキュメントによると、ls、cat、git statusなどの組み込みの読み取り専用コマンドは、プロンプトなしで実行できます。ファイルを編集するコマンド、bash操作を変更する可能性のあるコマンド、または追加のシステムにアクセスするコマンドは、承認が必要な場合があります。

ユーザーが無害な読み取り専用コマンドを繰り返し拒否または手動で承認する場合、チェックアップはより明確な権限ルールを提案できます。その目的は、広範な書き込みアクセス権を付与することなく、プロンプト疲れを軽減することです。

適切な権限ルールは狭く設定されるべきです。特定の読み取り専用パターンを承認することは、シェルやツールのカテゴリ全体を許可するよりも安全です。

コンテキスト維持の重要性

AIコーディングエージェントは、複数の種類の情報を1つの作業コンテキストに収める必要があります。

• 現在の会話
• 関連するソースファイル
• ツールの結果とコマンド出力
• CLAUDE.mdの指示
• スキルの説明
• MCPツールの定義
• 計画、タスクの状態、中間的な発見事項

コンテキストウィンドウは有限です。大量の無関係なセットアップ情報があると、実際の問題に対処するためのスペースが減少します。

これは、インストールされたすべてのスキルやMCPサーバーが自動的に完全に読み込まれることを意味するわけではありません。Claude Codeは、オンデマンドのスキルボディやツールディスカバリーなどのメカニズムを使用して、コンテキスト使用量を制御します。それでも、不要な設定はさらなる複雑さを生み出し、古い指示や統合がセッションに影響を与える可能性を高めます。

したがって、健全なセットアップには、ソフトウェアプロジェクトと同じ種類のメンテナンスが必要です。

1. 使用しなくなったものを削除する
2. グローバルな指示を簡潔に保つ
3. 専門的な手順をスコープ付きファイルまたはスキルに移動する
4. 統合と権限を監査する
5. フックのコストを測定する
6. 主要なプロジェクト変更後にセットアップを見直す

診断から支援型クリーンアップへ

従来の診断ツールは、多くの場合、エラーをリストアップした後に停止していました。ユーザーはすべての警告を理解し、関連ファイルを見つけ、修正方法を決定し、手動で適用する必要がありました。

更新されたセッション内チェックアップは、よりエージェント的なパターンに従います。

1. 現在の環境を検査する
2. 特定の問題を特定する
3. クリーンアップの利点を推定する
4. 提案された変更を提示する
5. ユーザーに完全なクリーンアップ、選択した修正、またはレポートのみのオプションを選択させる
6. 承認された変更のみを適用する
7. 確認のためにファイルの変更を表示可能な状態にする

これにより、ワークフローは受動的なエラーレポートではなく、対話型のメンテナンスアシスタントに近づきます。

承認ステップは重要です。ツールは、ユーザーの承認なしに変更を適用すべきではありません。

プロジェクトスキルを静かに削除したり、指示ファイルを書き換えたり、設定が非効率だと判断しただけで権限の動作を変更したりすることはありません。

自律コマンドに関する安全性の改善

同じリリースには、Claude Codeがより自律的に動作する際のリスクを低減するための変更も含まれています。

セッションログにおける承認の偽装防止

バックグラウンドタスクの通知では、人間による入力が行われなかった場合、その旨が明示的に表示されるようになりました。これは、トランスクリプト内のテキストが実際のユーザー承認と誤認されるのを防ぐためのものです。

エージェントにとって、「トランスクリプトに承認らしきテキストが含まれている」ことと、「ユーザーがインターフェースを通じて実際にこのアクションを承認した」ことの違いは極めて重要です。セキュリティに敏感な判断には、信頼できる承認チャネルが必要です。

リスクのある rm -rf コマンドに対する追加確認

変更ログには、オートモードの改善も記載されています。Claude Codeは、パスにコンテキストから解決できない変数が含まれている場合、rm -rf を実行する前に確認を求めます。

危険な例としては以下が挙げられます：

rm -rf "$TARGET_DIR/"

TARGET_DIR が空であるか、誤って展開された場合、結果はスクリプト作成者の意図とは大きく異なるものになる可能性があります。

正しい教訓は、1回の確認プロンプトで破壊的なシェルコマンドが安全になるということではありません。ユーザーは引き続き解決されたパスを確認し、可能な限りサンドボックスや使い捨て環境を使用し、バックアップを維持し、本番システムでの広範な削除コマンドを避けるべきです。

自律性には境界が必要

このリリースは、一見矛盾するように見える2つの目標を組み合わせています：

• 定型的な読み取り専用作業における不要な中断を減らす
• 不確実または破壊的なアクションに対して、より強力な確認を追加する

これらの目標は相互に機能します。有用なエージェントは、明確に定義された安全な領域内では迅速に動作し、不可逆的な結果を招く境界に近づいたときには速度を落とすべきです。

/doctor、/checkup、claude doctor

類似した名前は混乱を招く可能性があります。

Claudeにアクティブなセットアップを検査・整理してもらいたいほとんどのユーザーには、/doctor または /checkup が該当するコマンドです。

スクリプト、サポートチェック、またはセッション外でのクイックインストール診断には、claude doctor の方が適しています。

/checkup を安全に実行する方法

ステップ1：現在のリポジトリの状態を確認する

ツールに設定ファイルの変更を許可する前に、重要な作業がコミットまたはバックアップされていることを確認してください。

git status

未コミットのファイルを確認し、無関係なコード変更と設定のクリーンアップを混在させないようにしてください。

ステップ2：目的のプロジェクトでClaude Codeを起動する

cd /path/to/project
claude

プロジェクトの指示、フック、プラグイン、MCP設定がスコープ設定されている可能性があるため、正しいリポジトリからチェックアップを実行することが重要です。

ステップ3：チェックアップを実行する

/checkup

変更を受け入れる前にレポートを読んでください。

ステップ4：範囲を選択する

Claudeが何を提案するかによって、

以下は、指定された内容を自然で正確な日本語に翻訳したものです。

選択肢として、インターフェースには以下のようなオプションが表示される場合があります。

• 推奨クリーンアップを適用する。
• 個別のカテゴリを選択する。
• 現在の設定を維持し、レポートを生成する。
• 決定前に推奨事項について話し合う。

リポジトリにカスタム内部ツールや共有チーム設定がある場合は、選択的クリーンアップを推奨します。

ステップ5：差分を確認する

設定ファイルが変更されたら、それらを確認します。

git diff

特に以下の点に注意してください。

• CLAUDE.md および CLAUDE.local.md
• .claude/ 配下のファイル
• フックの定義
• プラグイン設定
• MCP設定
• パーミッションルール
• 生成されたスキル

ステップ6：通常のワークフローをテストする

日常的に使用するタスクを実行します。必要なツールが引き続き動作すること、関連する指示が読み込まれること、フックが重要なルールを適用すること、パーミッションプロンプトが期待通りに動作することを確認します。

ステップ7：クリーンアップを個別にコミットする

共有プロジェクトの設定が変更された場合は、チームメイトが個別に確認して元に戻せるように、フォーカスしたコミットを使用します。

git add CLAUDE.md .claude/
git commit -m "chore: Claude Code設定をクリーンアップ"

実際に変更されたファイルに合わせてパスを調整してください。

自動クリーンアップをすぐに受け入れるべきでない場合

以下の場合は、確認なしですべての推奨事項を承認しないでください。

• リポジトリが組織管理の設定を使用している場合。
• MCPサーバーがビジネスクリティカルな統合を提供している場合。
• フックがセキュリティまたはコンプライアンスポリシーを適用している場合。
• CLAUDE.mdに移植性のための意図的な重複が含まれている場合。
• プロジェクトがClaude Codeをテスト済みバージョンに固定している場合。
• 複数のチームが同じプラグインや指示階層に依存している場合。
• クリーンアップがパーミッション動作の変更を提案している場合。
• ワーキングツリーに無関係な未コミットの変更が含まれている場合。

そのような場合は、まずチェックアップを監査レポートとして使用します。チームの通常のレビュープロセスを通じて変更について議論または適用してください。

FAQ

Claude Codeの/checkupコマンドとは何ですか？

/checkupは、Claude Code 2.1.205で導入された拡張セッション内/doctorワークフローのエイリアスです。セットアップの問題を監査し、設定、コンテキスト、統合、フック、インストールの健全性、および関連する問題に対する修正を提案できます。

/checkupは/doctorと異なりますか？

現在のClaude Codeバージョンでは、/checkupは/doctorのエイリアスです。対話型Claude Codeセッション内で同じ完全なセットアップチェックアップを呼び出します。

claude doctorは/doctorと同じですか？

いいえ。claude doctorはターミナルから実行され、セッションを開かずに読み取り専用のインストールおよび設定診断を出力します。スラッシュコマンドは、承認を求めた後に修正を調整できます。

/checkupはスキルやMCPサーバーを自動的に削除できますか？

このワークフローは未使用のコンポーネントを特定し、クリーンアップを提案できますが、変更を行う前には確認を求めるように設計されています。特に共有プロジェクトや管理対象プロジェクトでは、ユーザーは提案された削除を確認する必要があります。

大きなCLAUDE.mdがClaude Codeに影響を与えるのはなぜですか？

CLAUDE.mdの指示はセッションコンテキストに入力されるため、長いファイルや重複したファイルは、アクティブなタスクに使用できるスペースを消費します。Anthropicは、大規模プロジェクトには簡潔な指示とスコープ限定のファイルを推奨しています。

すべての手順をCLAUDE.mdから移動すべきですか？

いいえ。安定した手順についてはそのままにしておくことも重要です。

プロジェクトの事実、コーディングルール、必要なコマンドはCLAUDE.mdに記述します。長く再利用可能な手順は、必要なときだけ完全な内容が読み込まれるため、スキルとして保存する方が適していることが多いです。

/checkup を使用すればオートモードは完全に安全ですか？

いいえ。デフォルト設定が改善され、保護機能が追加される可能性はありますが、コマンドと権限の確認は引き続きユーザーの責任です。破壊的な操作、外部への書き込み、本番環境へのアクセス、認証情報の取り扱いには、依然として慎重な管理が必要です。

セットアップチェックアップはどのくらいの頻度で実行すべきですか？

必須の頻度はありません。主要な設定変更後、Claude Code の動作が遅くなったり一貫性が低下したと感じたとき、複数の統合を追加した後、または定期的なプロジェクトメンテナンスレビューの一環として実行すると便利です。

関連ツール

• Claude Code: ターミナル、IDE、デスクトップ、ウェブ向けのAnthropicのエージェント型コーディングツール。
• Claude Code Skills: Claude Code を拡張する、再利用可能なオンデマンド手順を作成します。
• Claude CodeにおけるModel Context Protocol: Claude Code を外部ツール、API、データベース、サービスに接続します。
• Claude Code Hooks: エージェントのライフサイクルの特定の時点で、決定論的な自動化を実行します。
• Claude Code Plugins: スキル、エージェント、フック、MCP統合をパッケージ化して配布します。
• Claude Agent SDK: Claude Code で使用されているものと同じコアツールとエージェントループを使用して、プログラム可能なエージェントを構築します。

関連リンク

• Claude Code Changelog: バージョン2.1.205のセットアップチェックアップの変更を含む、公式リリース履歴。
• Claude Code Commands リファレンス: 組み込みのスラッシュコマンドとバンドルされたスキルのリファレンス。
• Claude Code CLI リファレンス: ターミナルコマンドとCLIフラグに関する公式リファレンス。
• Claude がプロジェクトを記憶する仕組み: CLAUDE.md ファイルの構成と管理に関するガイダンス。
• Claude Code セキュリティ: 権限動作、サンドボックス化、承認コントロール、および安全性に関するガイダンス。
• Claude Code 設定: 設定スコープ、管理設定、プラグイン、MCPポリシー、ファイルシステムコントロール。
• Claude Code トラブルシューティング: 公式の診断および復旧ガイダンス。
• フックによるアクションの自動化: ライフサイクルフックの作成と監査に関する実践的なガイダンス。

まとめ

Claude Code 2.1.205 では、/doctor がより広範なセットアップメンテナンスワークフローに拡張され、/checkup がエイリアスとして追加されました。このコマンドは、未使用の拡張機能、重複した指示、サイズが大きすぎる CLAUDE.md ファイル、動作の遅いフック、インストールの問題を検査できます。

そして反復的な許可行動。

アップデートの最も有用な点は、メンテナンス作業を一つのコマンドで隠蔽できることではない。ワークフローが提案された変更を説明し、環境を変更する前にユーザーを関与させ続けることができる点にある。

また、本リリースはエージェンティックツールにとって重要なパターンを強化している。すなわち、定型的な読み取り専用の作業は摩擦を減らすべきであり、不確実または破壊的な操作にはより強力な保護措置を講じるべきである、ということだ。

より健全なClaude Codeの設定とは、最も多くのスキル、フック、統合機能を備えたものではない。読み込まれたすべてのコンポーネントが明確な目的を持ち、すべての強力なアクションに適切な境界が設けられているもののことである。