Claude デスクトップアプリの「Code」を使い始めたばかりの方へ ｜ 公式ガイド「Debug your configuration」を、たとえ話で読みとく ｜ 2026年8月
Claude Code（クロード・コード）を使いはじめると、だれもが一度はこうつぶやきます。
あなた：「CLAUDE.md（クロード・エムディー）にちゃんと書いたのに、Claude が守ってくれない……」
あなた：「設定ファイルを直したのに、何も変わらない……壊れた？」
あなた：「追加したはずの機能（MCP とかフックとか）が、どこにも出てこない……」
こういうとき、「AI が気まぐれなんだ」「自分には向いていない」と思ってしまいがちです。でも、どうか安心してください。Claude Code を作っている会社（Anthropic）が、このお悩みのために公式の「調べ方ガイド」を公開しています。この本は、そのガイドを専門用語がまったくわからない方でも読めるように、はじめから書き直したものです。
「設定したのに効かない」の原因は、たいてい次の3つのどれかです。
① そのファイルが、そもそも読み込まれていない
② 読み込まれてはいるが、あなたが思っているのと別の場所から読まれている
③ 別の設定が、あなたの設定を上書きしてしまっている
そして Claude Code には、「いま何が読み込まれているか」をClaude 自身に見せてもらうための合言葉が用意されています。合言葉を覚えれば、原因の①②③のどれなのかを、自分で突きとめられます。
この本は、次のような方を想定して書いています。ひとつでも当てはまれば、ぴったりの読者です。
カタカナ語や英語が出てきたら、その場で「つまりこういう意味です」と添えます。巻末に用語集（第15章）もあります。
いきなりコマンドの一覧は出しません。まず「なぜそうなるのか」を身近なたとえで理解し、それから手順に進みます。理由がわかると、手順は忘れにくくなります。
公式ガイドの中には、黒い画面（ターミナル）でしか使えない手順もあります。この本では、各手順に デスクトップOK または ターミナル専用 の印を付けて区別します。ターミナル専用の手順は「こういうものがある」と知っておくだけで十分です。
| 部 | 内容 | こんな方に |
|---|---|---|
| 第1部（第2〜4章） 考え方をつかむ | 「効かない」の正体、Claude Code が読んでいる「設定」の種類、合言葉の打ち方。 | 全員必読。ここが土台です。 |
| 第2部（第5〜11章） 調べて直す | 合言葉ごとの使い方と、CLAUDE.md・設定ファイル・MCP・フックそれぞれの「効かないとき」の調べ方。 | いま困っている方は、該当する章へ。 |
| 第3部（第12〜15章） 早見表と用語集 | 症状から原因を引ける一覧表、迷ったときの最短手順、よくある質問、用語集。 | 困ったときに開く「お守り」として。 |
/context——「いま机の上に何があるか」を見る/memory /doctor /status ほかそれでは、お茶でも用意して、ゆっくり始めましょう。急がなくて大丈夫です。
あなたの会社に、とても優秀な新人さんが入ってきたと想像してください。この新人さんが Claude Code です。あなたは新人さんに仕事をしてもらうために、いろいろな「紙」を用意します。
ところが、新人さんが引き継ぎ書の通りに動いてくれません。さて、何が起きているのでしょう。考えられるのは、たいてい次の3つです。
あなたは書いたつもりでも、間違った引き出しにしまっていた。あるいはファイル名を間違えていて、新人さんが「自分あての書類」だと気づけなかった。Claude Code の世界では、これが一番多い原因です。ファイルの置き場所や名前が、決まりと少し違うだけで、読み込まれません。
たとえば、会社全体の引き継ぎ書と、あなたの部署だけの引き継ぎ書が両方あって、新人さんは「部署の方」を読んでいた。あなたは「会社全体の方」を直していたので、変化がなかった。Claude Code の設定は、複数の場所に同じ種類のファイルを置けるため、こういうことが起きます。
あなたが「A でお願いします」と書いたのに、もっと優先順位の高い別の紙に「B でやること」と書いてあった。新人さんは、優先順位のルールに従って B を選んだ。Claude Code には「どの設定が勝つか」の順番が決まっていて、知らないうちに負けていることがあります。
公式ガイドには、もうひとつ大事なことが書かれています。紙はちゃんと届いていて、読まれてもいるのに、それでも守られない場合です。
指示があいまいで何通りにも受け取れる。2枚の紙の内容が食い違っている。紙が長くなりすぎて、一つひとつのルールへの注意が薄まっている。——こういうとき、新人さんは悪気なく「別の解釈」をしてしまいます。この場合は、置き場所を直しても解決しません。文章そのものを直す必要があります。
①〜④のどれが起きているかは、外から見ているだけではわかりません。でも、新人さんに「いま、あなたの机の上にはどの紙がありますか？」と聞けば、すぐにわかります。Claude Code には、まさにそのための合言葉が用意されています。第2部で、ひとつずつ覚えていきましょう。
第2章で「紙」とひとくくりにしたものは、実際には5種類あります。種類ごとに「置き場所」と「見るための合言葉」が違うので、まず顔ぶれを覚えましょう。新人さんのたとえで言えば、こんな対応です。
| 名前 | たとえ | どんなもの？ | ファイルの形 |
|---|---|---|---|
| CLAUDE.md （クロード・エムディー） | 引き継ぎ書 | 「うちのプロジェクトはこうなっています」「こういうやり方で」と、Claude に事情を教える文書。メモリファイルとも呼ばれます。 | ふつうの文字だけのファイル（.md） |
| settings.json （セッティングス・ジェイソン） | 社内規則 | 「これはやっていい／ダメ」（許可・禁止）や、細かい動作の設定を機械的に決めるファイル。 | JSON という決まった書式（後述） |
| フック（Hooks） | 見張り役 | 「Claude がファイルを書き込む直前に、自動でこのチェックを走らせる」のような、決まったタイミングで自動で動く仕掛け。 | settings.json の中に書く |
| MCP サーバー （エム・シー・ピー） | 外部パートナー会社 | Claude に「Google ドライブを読める」「天気を調べられる」のような外の機能を貸してくれるしくみ。 | .mcp.json という専用ファイル |
| スキル（Skills） | 作業手順書 | 「議事録を作るときは、この手順で」のような、特定の作業の段取りをまとめた文書。Claude が必要なときに取り出して読みます。 | SKILL.md というファイルを、フォルダに入れる |
settings.json の「json（ジェイソン）」は、コンピュータが読みやすいように決められた書き方のルールです。たとえば、こんな見た目をしています。
波かっこ { } と、二重引用符 " " と、コロン : で「名前」と「中身」を対にして書きます。人間が読むにはちょっと堅苦しいのですが、1文字でも間違えると、ファイル全体が無効になるという厳しい性格を持っています。この性格が、第8章・第10章のトラブルにつながってきます。
CLAUDE.md や SKILL.md の「md」は「マークダウン」の略です。こちらは JSON とは正反対で、ただの文字のファイルです。「#」を付ければ見出し、「-」を付ければ箇条書き、というゆるい約束があるだけ。メモ帳で開いて、日本語でふつうに書けます。
公式ガイドが、わざわざ囲みで強調している考え方があります。
CLAUDE.md は、Claude がよい判断をできるように事情を教えるためのものです。「うちではこうやっています」という文化の共有です。一方、settings.json の許可・禁止設定やフックは、Claude がどう判断しようと関係なく、機械的に止めるためのものです。
ですから、「絶対にやってほしくないこと」を CLAUDE.md に書くのは、実は不十分です。新人さんに「これはやらないでね」と口頭で頼むのと、鍵をかけるのとの違いです。絶対に起きてほしくないことは、鍵（権限・フック）の側に書きましょう。
ここから先、/context や /doctor のような、スラッシュ（斜め線）で始まる言葉がたくさん出てきます。これをスラッシュコマンドと呼びます。「命令」と訳されることもありますが、この本では親しみをこめて「合言葉」と呼ぶことにします。
Claude デスクトップアプリの「Code」タブを開いて、いつも質問を打ち込んでいる入力欄に、そのまま /context と打って送信するだけです。特別な画面も、特別な操作もいりません。
/ を打つ/context と打って Enter（送信）。すると、Claude の返事の代わりに「いま読み込んでいるものの一覧」が表示されます。
ここで、正直にお伝えしなければならないことがあります。公式ガイドに出てくる「調べる手段」には、大きく2種類あります。
/context /doctor /memory /mcp /hooks /status /permissions /skills /debug など。すべてスラッシュで始まります。会話中に打つものなので、デスクトップ版でもそのまま使えます。
claude doctor claude --debug claude --safe-mode など。スラッシュではなく claude という単語で始まります。これらはClaude Code を起動する前に、黒い画面（ターミナル）で打つものです。デスクトップ版の入力欄に打っても動きません。
📍 この本では「スラッシュで始まる合言葉はデスクトップ版の入力欄でも使える」という前提で書いています。公式ガイドはこの区別を明示していないため、筆者がデスクトップ版の仕組み（ふつうの会話と同じ入力欄を使う）から判断したものです。もしお使いの版で候補一覧に出てこない合言葉があれば、その合言葉はまだデスクトップ版に対応していない可能性があります。その場合は無理に使わず、次の手段に進んでください。
「黒い画面は使わない」と決めている方は、ターミナル専用の手段を「そういう道もある」と知っておくだけで十分です。この本の手順の大半は、デスクトップ版の合言葉だけで完結するように組み立てています。どうしてもターミナルが必要な場面（第11章）では、その旨をはっきり書きます。
/。claude ○○ の形のものはターミナル専用で、デスクトップ版の入力欄では動かない。「そういう道もある」と知っておけば十分。/context——「いま机の上に何があるか」を見る「何か効いていない」と感じたら、最初に打つ合言葉は必ず /context です。コンテキストとは「いま Claude が読んでいるもの全部」のことです。新人さんに「いま机の上にある書類を、全部見せて」と頼むのに相当します。
/context を打つと、Claude がいま抱えている情報が、種類ごとに分けて表示されます。
はじめのうちは、細かい数字は気にしなくて大丈夫です。見るべきことはひとつだけ。「自分が用意したはずのものが、一覧に出ているか」です。
第2章の原因①（届いていない）です。置き場所かファイル名が違います。種類ごとの直し方は、第7〜10章へ。
第2章の原因③（上書き）か原因④（書き方）です。CLAUDE.md なら文章の書き方を、settings.json なら「重ね着の順番」（第8章）を疑います。
プロジェクトの奥のフォルダ（サブディレクトリ）に置いた CLAUDE.md は、起動したときには読み込まれません。Claude がそのフォルダの中のファイルを「読む」ときに、はじめて読み込まれます。ですから、起動直後に /context を打っても出てこないのは正常です。「書き込むとき」や「新しく作るとき」では読み込まれない点にも注意してください。
/context。「いま読み込まれているもの」の一覧が出る。/context が「全体をざっと見る」合言葉だとすれば、ここで紹介するのは「特定の引き出しだけをじっくり見る」合言葉です。全部を暗記する必要はありません。「こういうときは、これ」という対応だけ、ゆるく覚えてください。すべて デスクトップOK の入力欄に打つタイプです。
| 合言葉 | 何が見える？ | こんなときに |
|---|---|---|
/memory | CLAUDE.md などメモリファイルの置き場所の一覧。ユーザー用（あなた全体）とプロジェクト用（この作業フォルダ）の両方。そこから開いて編集もできる。自動メモリのフォルダと、そのオン／オフ切り替えも。 | 「CLAUDE.md が、どこのものが読まれているのか知りたい」 |
/skills | 使えるスキル（作業手順書）の一覧。プロジェクト・ユーザー・プラグインのどこ由来かも表示。 | 「作ったスキルが出てこない」 |
/hooks | いま有効なフック（見張り役）の一覧。 | 「フックが動かない」 |
/mcp | つながっている MCP（外部パートナー）と、その接続状態。 | 「MCP が使えない」 |
/permissions | いま最終的に効いている許可・禁止のルール。 | 「禁止したはずの操作ができてしまう」「許可したのに毎回聞かれる」 |
/doctor | 健康診断。インストール状態、書き方が間違っている設定ファイル、使われていない拡張、名前がかぶっている部下（サブエージェント）、CLAUDE.md の中でコードから読み取れるので書かなくてよい内容など。直し方の提案つき。 | 「何が悪いのかまったく見当がつかない」ときの、最初の相談相手 |
/debug [困りごと] | 詳しい記録（ログ）を取り始めて、Claude 自身にその記録と設定の場所を見ながら原因を診断してもらう。 | 「自分では手に負えない。Claude に調べてもらいたい」 |
/status | いま有効な設定の出どころ一覧。会社が配っている「管理設定」が効いているかどうかも。 | 「自分では触っていない設定が効いている気がする」 |
8つもあると覚えきれないので、まずは3つだけ。
/context → /doctor → /debug 困りごと
（全体を見る）→（健康診断してもらう）→（Claude に原因を調べてもらう）
この3つで、初心者が遭遇するトラブルの大半は見当がつきます。残りの5つは、第7章以降で「この種類のトラブルなら、この合言葉」として、必要な場面で改めて登場します。
/debug の使い方、もう少しだけ/debug の後ろに、日本語で困りごとを書けます。たとえば：
こう打つと、Claude が記録を取り始め、設定ファイルの場所と記録の中身を照らし合わせながら、「ここが原因ではないか」と診断してくれます。自分で原因を考えるのがむずかしいときの、とても心強い味方です。
設定のトラブルで一番やっかいなのは、エラーも出ず、画面上は何事もなく動いているのに、実は読み込みに失敗している状態です（専門用語で「サイレントフェイル＝無言の失敗」と言います）。たとえばフックは、名前を1文字間違えるだけで何のメッセージも出さずに無効になります。「エラーが出ていないから大丈夫」ではなく、「/context や /hooks の一覧に出ているから大丈夫」を合格の基準にしてください。
/memory（CLAUDE.md）、/skills、/hooks、/mcp、/permissions、/doctor、/debug、/status。/context → /doctor → /debug 困りごと。いちばん多い相談が、これです。手順は、たった2段階です。
/context と /memory/context の「メモリファイル」の欄に、あなたの CLAUDE.md が出ているか確認します。出ていなければ、/memory を打って、Claude が「CLAUDE.md はここにあるはず」と思っている場所の一覧を見ます。あなたが書いたファイルの場所と、見比べてください。
CLAUDE.md です。/context に出ているのに Claude が守らない。このとき、置き場所をいくら直しても解決しません。原因は文章の書き方にあります。公式ガイドは、守られにくくなる3つの原因を挙げています。
「きれいに書いて」では、Claude の「きれい」とあなたの「きれい」がずれます。「1文は60文字以内」「見出しは付けない」のように、守れたかどうかを判定できる形で書きます。
ユーザー用の CLAUDE.md に「英語で」、プロジェクト用に「日本語で」と書いてあれば、Claude はどちらかを選ぶしかありません。/memory で両方を開き、矛盾をなくします。
ルールが100個あれば、1個あたりの注意は100分の1です。本当に大事なものだけを残し、細かい作業手順はスキル（第3章）に分けると効果的です。
「絶対に○○しないこと」は、CLAUDE.md（口頭の頼みごと）ではなく、権限やフック（鍵）に書きます。第3章の区別を思い出してください。
公式ガイドは、CLAUDE.md を「新しく入ったチームメイトに伝えるような内容」に使うのがよい、と書いています。たとえば：
逆に、「絶対にやってはいけないこと」の保証には向いていません。それは第3章で見たとおり、鍵（権限・フック）の仕事です。
Claude Code には、調べものを任せる「Explore（エクスプロア）」や、計画を立てる「Plan（プラン）」という最初から組み込まれている部下（サブエージェント）がいます。この2人は、CLAUDE.md を読みません。ですから、この部下に仕事を任せるときに CLAUDE.md のルールを守ってほしければ、頼むときの文章の中に、そのルールをもう一度書く必要があります。一方、あなたが自分で作った部下（カスタムサブエージェント）は、ふつうに CLAUDE.md を読みます。その部下に絶対守らせたいことは、部下の定義ファイルの本文に書くと確実です。
/context で読まれているか確認。出なければ /memory で場所を見比べる。名前は大文字の CLAUDE.md、「.txt」が付いていないか、フォルダの位置は正しいか。settings.json のトラブルは、ほぼ2種類です。「書き方を間違えて、ファイルごと無効になっている」か、「別の settings.json に上書きされている」かです。
/doctor——書き方の間違いを見つける第3章で、JSON は「1文字の間違いで全部無効」という厳しい性格だと書きました。カンマの付け忘れ、かっこの閉じ忘れ、全角の引用符「”」の混入——どれも、ファイルをまるごと無効にします。しかも、無効になったことは、目立つ形では知らされません。
そこで /doctor です。健康診断の中で「書き方が間違っている設定ファイル」を見つけて教えてくれます。設定ファイルを触ったあとに何かおかしければ、まず /doctor と覚えてください。
※ ターミナルが使える方は、claude doctor（スラッシュなし）でも同じ診断を、Claude Code を起動せずに見られます。ターミナル専用
settings.json は、複数の場所に置けるファイルです。そして同じ項目が複数の場所にあるとき、「より身近なもの」が勝ちます。服の重ね着を思い浮かべてください。下着の上にシャツ、シャツの上に上着。外から見えるのは、いちばん外側の上着です。
言葉で整理すると、こうなります。
| 順位 | 置き場所 | だれに効く？ | たとえ |
|---|---|---|---|
| 1（最強） | 管理設定（会社の IT 部門が配る）／環境変数・起動オプション | 会社のパソコン全体 | 会社の就業規則。個人では変えられない |
| 2 | プロジェクト内の .claude/settings.local.json | このプロジェクトの、あなただけ | 自分の机の引き出しの付せん |
| 3 | プロジェクト内の .claude/settings.json | このプロジェクトの全員 | この部署のルール |
| 4（最弱） | ホームフォルダの ~/.claude/settings.json | あなたの全プロジェクト | あなた個人の基本方針 |
※ ~（チルダ）は「あなたのホームフォルダ」の略記号です。Mac なら「ユーザ」→「あなたの名前」のフォルダのことです。頭に点が付いた .claude のようなフォルダは「隠しフォルダ」で、Finder ではふだん見えません。Finder で Command + Shift + .（ピリオド）を押すと表示／非表示を切り替えられます。
よくあります。以前に「とりあえず自分だけ」のつもりで local に書いた設定が残っていて、それが勝ち続けている。/permissions や /status で「最終的に効いている値」を見て、自分の設定と違っていたら、より外側のファイルを疑います。
~/.claude.json と ~/.claude/settings.json を取り違えた名前がそっくりな、別のファイルが2つあります。~/.claude.json（フォルダではなく、ファイル）は、アプリの内部状態や画面の切り替えを保存する場所で、権限・フック・環境変数を書いても読まれません。それらは ~/.claude/settings.json（.claude フォルダの中の settings.json）に書きます。「いくら書いても効かない」ときは、どちらのファイルを開いているか、パス（住所）を指でなぞって確認してください。
うれしいお知らせをひとつ。settings.json を直して保存すると、動いている最中の Claude Code に、少し間をおいて自動で反映されます。再起動は不要です。数秒待ってから /hooks や /permissions を打ち直して、新しい内容が出ていればOKです。
/doctor。JSON の書き間違いでファイルごと無効になっていないか見つけてもらう。/permissions と /status で見る。~/.claude.json（ファイル）と ~/.claude/settings.json（フォルダの中）は別物。権限・フック・環境変数は後者に書く。MCP は「外部パートナー会社」です。Claude に新しい機能を貸してくれる、外のサービスや小さなプログラムのことでした。パートナーが動かないときの調べ方は、/mcp で「状態」を見ることから始まります。
/mcp で見える3つの状態/mcp を打つと、設定してあるすべての MCP が、それぞれの状態つきで一覧になります。状態はおおむね次の3つに分かれ、それぞれ原因と対処が違います。
| 状態 | 意味（たとえ） | よくある原因 | 対処 |
|---|---|---|---|
| 未承認／無効 | パートナーと契約書は用意したが、あなたのハンコがまだ | プロジェクト用の .mcp.json に書いた MCP は、最初の1回だけ「使ってよいですか？」と聞かれます。この確認を閉じてしまうと、ずっと無効のまま。 | /mcp の画面から、その MCP を選んで承認する。 |
| 失敗（failed） | パートナーに電話したが、つながらない | 起動に使う命令やファイルの場所が「相対パス」（いまいる場所からの道順）で書かれていて、起動したフォルダによっては見つからない。 | ファイルの場所を「絶対パス」（/Users/hiro/… のように、根元からの完全な住所）で書く。npx や uvx のように、すでに「通り道（PATH）」に登録されている命令は、そのままでOK。 |
| 接続済みだが、道具がゼロ | 電話はつながったが、何も貸してくれない | パートナー側が、道具の一覧を返してこない。 | /mcp で Reconnect（再接続）を選ぶ。それでもゼロなら、詳しい記録を見る必要がある（後述）。 |
状態以前に、/mcp の一覧に名前すら出てこない場合は、第2章の原因①、つまり「届いていない」です。MCP の設定は、置き場所と書き方の決まりがやや細かいので、次の3点を確認してください。
.mcp.json は、プロジェクトのいちばん上にあるか.claude フォルダの中に入れてしまうと読まれません。Claude Code で開いているフォルダの、直下に置きます。
mcpServers になっているか別のツール（VS Code など）から設定をコピーしてくると、見出しが servers になっていることがあります。Claude Code が読むのは mcpServers という見出しだけです。
mcpServers を書いていないかよくある勘違いです。settings.json は MCP の設定を読みません。プロジェクト用なら .mcp.json に、あなた全体用ならターミナルで claude mcp add --scope user を使います（後者は ターミナル専用）。
MCP の中には、API キー（外部サービスの利用券のようなもの）を必要とするものがあります。これを「環境変数（パソコン全体で共有するメモ）」に書いておいたのに、MCP に届いていない——という相談もあります。
理由は、Claude Code が MCP を起動するとき、自分の環境のメモの一部を、わざと外して渡すためです（安全のための仕様です）。確実な方法は、.mcp.json のその MCP の項目の中に env という欄を作って直接書くことです。そうすれば、起動したフォルダや環境に関係なく届きます。
公式ガイドでは、最後の手段として claude --debug=mcp で起動し、~/.claude/debug/（セッションID）.txt という記録ファイルの中の、MCP 側のエラーメッセージを読む方法が紹介されています。これはターミナルが必要です。デスクトップ版だけで進めたい方は、/debug MCPの○○が道具を返してこない と打って、Claude に記録を読んでもらう方法を先に試してください。
/mcp で状態を見る。「未承認」なら承認、「失敗」ならファイルの場所を絶対パスに、「道具ゼロ」なら Reconnect。.mcp.json はプロジェクトのいちばん上、見出しは mcpServers、settings.json には書かない。.mcp.json の中の env 欄に直接書くのが確実。フックは「決まったタイミングで、自動で動く見張り役」でした。たとえば「Claude がファイルを書き換える直前に、必ずバックアップを取る」のような仕掛けです。フックのトラブルは、ほぼすべて「書き方」に集中しているのが特徴です。
/hooks——一覧に出ているか/hooks を打つと、いまの会話で有効なフックが、タイミング（イベント）ごとに並びます。ここに出ていなければ、読まれていません。原因はほぼひとつ。
「hooks.json」のような別のファイルを作っても読まれません（プラグインという特別な仕組みだけが例外です）。settings.json の中に "hooks" という見出しを作り、その中に書きます。
フックにはマッチャー（matcher）という欄があります。「どの道具が使われたときに動くか」を指定する、いわば見張り役への「この人が来たら声をかけて」という指示です。ここの書き方を間違えると、見張り役は何も言わずに、ただ見逃します。エラーは出ません。これが第6章で警告した「無言の失敗」の典型です。
公式ガイドが挙げる、マッチャーの間違いは3つです。
| 間違い | なぜダメ？ | 正しくは |
|---|---|---|
複数の道具を 配列（["Edit", "Write"]）で書いた | マッチャーは「1本の文字列」でなければならず、配列は書式エラー。Claude Code は設定エラーを表示し、その settings.json をまるごと拒否する。ほかのフックも全部消える。 | 1本の文字列にして、縦棒 | でつなぐ："Edit|Write" |
区切りにカンマ "Edit,Write" を使った（古い版） | v2.1.191 より前の Claude Code では、カンマは「ただのカンマという文字」と解釈され、何にも一致しない。 | 縦棒 | を使う。新しい版（v2.1.191以降）ならカンマも縦棒と同じ意味になる。 |
道具の名前を小文字で書いた（"bash"） | 大文字・小文字は区別される。道具の名前は頭が大文字：Bash Edit Write Read。 | "Bash" のように、頭を大文字に。 |
つづりの間違いも同様です。"Wirte" と打てば、そんな道具は存在しないので、見張り役は永遠に誰にも声をかけません。
上の表の1つ目は特に要注意です。マッチャーを配列で書くと、そのファイルに書いたほかのフック・権限・設定まで、全部無効になります。「フックをひとつ足したら、前から効いていた禁止ルールまで効かなくなった」という場合は、これを疑ってください。/doctor が「書式の検証に失敗」と教えてくれます。
※ 会社が配る「管理設定」の場合だけは例外で、間違った項目だけが取り除かれ、ほかのフックは生き残ります。
/hooks をもう一度第8章でも触れたとおり、settings.json は保存すれば自動で反映されます。/hooks がまだ古い内容を表示していたら、数秒待ってからもう一度 /hooks を打って、表示を更新してください。
公式ガイドの最後の手段は、claude --debug で起動し、実際にその道具を使わせて、記録の中で「どのイベントが起きて、どのマッチャーが照合され、フックが何を返したか」を1行ずつ追う方法です。ターミナルが必要です。デスクトップ版の方は、/debug フックが動かない で Claude に記録を読んでもらう方法を先に試してください。
/hooks に出ていなければ、settings.json の "hooks" の中に書いているか確認。専用ファイルはない。|、道具名は頭が大文字、つづりを確認。/doctor で検出できる。ここまでの調べ方で見当がつかないとき、最後に残るのが「いったん全部の設定を外して、それでも問題が起きるか試す」という方法です。医者が「まず薬を全部やめてみましょう」と言うのと同じ発想です。
正直にお伝えすると、この章の手段はどちらもターミナル専用です。デスクトップ版だけで進めたい方は、「こういう考え方がある」と知っておき、必要なときに詳しい方に頼む、という付き合い方で十分です。
claude --safe-mode で起動すると、あなたが追加したものが全部オフの状態で始まります。CLAUDE.md、スキル、プラグイン、フック、MCP、自作のコマンドや部下、すべてオフ。ログイン・モデル選択・基本の道具・権限は、ふつうに動きます。
犯人は、オフにしたもののどれかです。第7〜10章の合言葉で、ひとつずつ絞り込みます。
犯人は、追加したものの外側——settings.json そのもの、管理設定、環境変数など——にいます。手段2へ。
※ 会社が配る管理設定のフックと方針だけは、セーフモードでも生きています。
もっと徹底的にやるなら、「設定フォルダはここですよ」と Claude Code に教える目印（CLAUDE_CONFIG_DIR という環境変数）を、空っぽのフォルダに向けて起動します。さらに、.claude フォルダも .mcp.json も CLAUDE.md もない場所から起動すれば、プロジェクト側の設定も読まれません。
成功すると、はじめて使うときの画面（テーマの色選びなど）が出ます。それが「まっさらで起動できた」しるしです。2回目以降は、その空フォルダに初回設定が保存されるので、この画面は出ません。
まっさらで問題が消えたら、犯人はあなたの ~/.claude かプロジェクトの .claude の中にいます。ファイルを1つずつ空フォルダにコピーしては試す、を繰り返して、どのファイルを入れた瞬間に問題が再発するかを突き止めます。まっさらでも残るなら、犯人は設定の外です。/status で管理設定を確認し、環境変数を疑い、それでもダメなら公式の「トラブルシューティング」ページへ、という流れになります。
📍 ターミナルを使わずに、近いことをする工夫として、筆者は次の手順をおすすめします（公式ガイドに書かれた方法ではなく、筆者の経験則です）。
書類 の中などに、何も入っていない新しいフォルダを作る。この方法では、プロジェクト側の設定（プロジェクト用 CLAUDE.md、.claude/settings.json、.mcp.json）だけが外れます。ユーザー用の設定（~/.claude 配下）は残ったままなので、完全な「まっさら」ではありません。それでも「プロジェクト側が犯人か、ユーザー側が犯人か」の大きな切り分けはできます。
claude --safe-mode）と、まっさら設定フォルダ（CLAUDE_CONFIG_DIR）の2段階。どちらもターミナル専用。公式ガイドの末尾にある一覧表を、やさしい言葉に置きかえたものです。「バグかな？」と思う前に、この表を一度なぞってください。大半はここに載っています。
| 症状 | 原因 | 直し方 |
|---|---|---|
| フックがまったく動かない | マッチャーを配列 [ ] で書いている | 1本の文字列にして縦棒でつなぐ："Edit|Write" |
| フックがまったく動かない | 区切りにカンマを使っていて、Claude Code が v2.1.191 より古い | 縦棒 | に変える。または Claude Code を新しくする |
| フックがまったく動かない | 道具名が小文字（"bash"） | 頭を大文字に：Bash Edit Write Read |
| フックがまったく動かない | 専用ファイルに書いている | settings.json の "hooks" の中に書く（専用ファイルはない） |
| 会話の終わりに、後片付けの処理が走らない | SessionEnd（会話終了）のフックを作っていない | settings.json に SessionEnd のフックを追加する |
| 症状 | 原因 | 直し方 |
|---|---|---|
| 全体に効かせたはずの権限・フック・環境変数が無視される | ~/.claude.json（別のファイル）に書いている | ~/.claude/settings.json（フォルダの中）に書く |
| settings.json の値が無視される | 同じ項目が settings.local.json にある | local のほうが勝つ。local を直すか、項目を消す |
Bash(rm *) を禁止したのに /bin/rm や find -delete が通る | 禁止ルールは「命令の文字列の見た目」で判定する。中身の実体までは見ない | 変形パターンも1つずつ禁止に足す。確実に止めたいなら PreToolUse フックかサンドボックス（隔離された箱）を使う |
| 症状 | 原因 | 直し方 |
|---|---|---|
スキルが /skills に出ない | .claude/skills/名前.md と、ファイルを直接置いている | フォルダを作って中に SKILL.md：.claude/skills/名前/SKILL.md |
スキルは /skills に出るが、Claude が使ってくれない | disable-model-invocation: true（人間専用の印）が付いている。または説明文と頼み方が合っていない | /skills で「user-only」の表示を確認。説明文を、実際の頼み方に近い言葉に書き直す |
| 奥のフォルダの CLAUDE.md が無視される | 起動時には読まれない。Claude がそのフォルダのファイルを読んだときに読まれる | 仕様どおり。最初から効かせたい内容は、プロジェクト直下の CLAUDE.md に書く |
| 部下（サブエージェント）が CLAUDE.md を無視する | 組み込みの Explore / Plan は読まない仕様 | 任せるときの指示文にルールを書き直す。自作の部下なら、定義ファイルの本文に書く |
| 症状 | 原因 | 直し方 |
|---|---|---|
.mcp.json の MCP が読まれない | .claude/ の中に置いている。または見出しが servers（VS Code の形式） | プロジェクトのいちばん上に置き、見出しを mcpServers にする |
settings.json に mcpServers を書いたのに出ない | settings.json は MCP を読まない | プロジェクト用は .mcp.json、ユーザー用はターミナルで claude mcp add --scope user |
| MCP を足したのに出ない | 初回の承認を閉じてしまった | /mcp で承認する |
| 起動するフォルダによって MCP が失敗する | 相対パス（いまの場所からの道順）で書いている | 絶対パス（根元からの完全な住所）で書く |
| MCP に環境変数（API キーなど）が届かない | Claude Code は安全のため一部の環境変数を外して起動する | .mcp.json のその MCP の項目に env 欄を作って直接書く |
「何から手を付ければいいかわからない」というときのために、デスクトップ版の入力欄だけで完結する手順を、順番に並べました。上から順に、止まったところで原因が見つかります。
/context を打つ/doctor を打つ/memory、権限なら /permissions、フックなら /hooks、MCP なら /mcp。「最終的に効いている内容」が自分の意図と違えば、上書きを疑う（第8章の重ね着）。
/status で出どころを見る/debug 困りごとを日本語で と打つこの5手順を終えてもわからない場合は、第11章の「まっさらで試す」（ターミナルが必要）か、詳しい方への相談を検討してください。そのとき、手順1〜5で何が表示されたかを添えて相談すると、話がとても早く進みます。
Q：設定ファイルを直したら、Claude Code を再起動しないといけませんか？
A：settings.json は、保存すれば少し間をおいて自動で反映されます。再起動は不要です。数秒待って、/hooks や /permissions で新しい内容が出ていればOKです。
Q：CLAUDE.md に「絶対に○○しないこと」と書いたのに、やってしまいました。壊れていますか？
A：壊れていません。CLAUDE.md は「事情を教える」道具であって、「機械的に止める」道具ではありません。絶対に止めたいことは、settings.json の権限（deny）やフックという「鍵」の側に書いてください（第3章）。
Q：エラーは何も出ていません。それなら大丈夫ですよね？
A：残念ながら、そうとは限りません。フックのマッチャーのつづり間違いなど、何も言わずに無効になる失敗がいくつもあります。「エラーが出ない」ではなく「/context や /hooks の一覧に出ている」を合格の基準にしてください（第6章）。
Q：「~/.claude.json」と「~/.claude/settings.json」、どちらに書けばいいですか？
A：権限・フック・環境変数は、必ず ~/.claude/settings.json（.claude フォルダの中）です。~/.claude.json（フォルダの外にある、単独のファイル）は、アプリの内部状態を保存する別物で、そこに書いても読まれません（第8章）。
Q：ターミナルを使わないと、結局ダメなのでは？
A：初心者がぶつかるトラブルの大半は、デスクトップ版の合言葉（第13章の5手順）で原因がわかります。ターミナルが必要になるのは、「全部外してまっさらで試す」という最終手段（第11章）と、詳しい記録を直接読む場面だけです。そこまで行くのは、かなりまれです。
Q：「隠しフォルダ」の .claude が Finder で見つかりません。
A：Mac の Finder で Command + Shift + .（ピリオド）を押すと、隠しファイル・フォルダの表示／非表示が切り替わります。もう一度押せば元に戻ります。
| 用語 | やさしい意味 | 初出 |
|---|---|---|
| CLAUDE.md（クロード・エムディー） | Claude に「このプロジェクトの事情」を教える引き継ぎ書。ふつうの文字のファイル。メモリファイルとも呼ぶ。 | 第3章 |
| settings.json（セッティングス・ジェイソン） | 許可・禁止や細かい動作を機械的に決める社内規則のファイル。JSON 書式。複数の場所に置け、外側が勝つ。 | 第3章・第8章 |
| settings.local.json | プロジェクトの中で「あなただけ」に効く settings.json。プロジェクト用 settings.json より強い。 | 第8章 |
| JSON（ジェイソン） | コンピュータ向けの厳格な書き方のルール。1文字の間違いでファイル全体が無効になる。 | 第3章 |
| マークダウン（.md） | 「#」で見出し、「-」で箇条書き、というゆるい約束で書くただの文字ファイル。 | 第3章 |
| フック（Hooks） | 決まったタイミングで自動で動く見張り役。settings.json の中に書く。 | 第3章・第10章 |
| マッチャー（matcher） | フックに「どの道具が使われたら動くか」を指定する欄。1本の文字列で、縦棒で複数指定。大文字・小文字を区別。 | 第10章 |
| MCP（エム・シー・ピー） | Claude に外の機能を貸してくれる外部パートナー。プロジェクト用は .mcp.json に書く。 | 第3章・第9章 |
| スキル（Skills） | 特定の作業の段取りをまとめた作業手順書。フォルダの中の SKILL.md。 | 第3章 |
| サブエージェント（部下） | Claude が仕事を任せる専門の部下。組み込みの Explore / Plan は CLAUDE.md を読まない。 | 第7章 |
| コンテキスト | いま Claude が読んでいるもの全部。/context で一覧できる。 | 第5章 |
| スラッシュコマンド（合言葉） | /context のように、入力欄に打つ特別な言葉。デスクトップ版でも使える。 | 第4章 |
| ターミナル | 黒い画面で文字だけで命令する道具。claude ○○ の形の命令はここで打つ。 | 第4章 |
| 管理設定 | 会社の IT 部門がパソコン全体に配る設定。個人では変えられず、最優先で効く。 | 第8章 |
| 環境変数 | パソコン全体で共有する、名前付きのメモ。設定を上書きする力を持つものがある。 | 第8章・第9章 |
| 相対パス／絶対パス | 「いまの場所からの道順」／「根元からの完全な住所」。MCP の起動には絶対パスが安全。 | 第9章 |
| PATH（パス） | 「命令を探しに行く通り道」の一覧。ここに登録された命令（npx など）は名前だけで呼べる。 | 第9章 |
| サイレントフェイル（無言の失敗） | エラーを出さずに、こっそり失敗している状態。いちばん危険。一覧表示で確かめる。 | 第6章 |
| セーフモード | 追加した設定を全部オフにして起動する方法（claude --safe-mode）。ターミナル専用。 | 第11章 |
| CLAUDE_CONFIG_DIR | 「設定フォルダはここ」と Claude Code に教える環境変数。空フォルダに向ければ、まっさらで起動できる。ターミナル専用。 | 第11章 |
| 隠しフォルダ | 名前が「.」で始まる、ふだん見えないフォルダ。.claude など。Mac は Command + Shift + . で表示。 | 第8章 |
| ~（チルダ） | 「あなたのホームフォルダ」を指す略記号。 | 第8章 |
最後まで読んでくださって、ありがとうございます。
「設定したのに効かない」は、AI が気まぐれなのではなく、紙が机に届いていないか、別の紙が読まれているか、別の紙に上書きされているか——そのどれかであることが、ほとんどです。そして、どれなのかは、Claude 自身に「いま何を読んでいるか」を見せてもらえばわかります。
次に何かがおかしいと感じたら、まず /context。それだけ覚えて帰っていただければ、この本の役目は果たせました。焦らず、ひとつずつ。応援しています。