Claude Codeのspellcheck設定 — 効く3か所と優先順位

spellcheck設定はどこに書くと効くのか

Claude Codeのスペルチェックは、プロンプト入力欄の綴りミスに下線を引く機能です。既定ではオフで、spellcheck設定で有効にします。要件はClaude Code v2.1.235以降です。

プロジェクトの.claude/settings.jsonと.claude/settings.local.jsonに書いても、Claude Codeはspellcheckを無視します。チームのリポジトリにコミットして全員に配る、という使い方はできません。

3か所に別々の値があるときは、管理設定、--settings、ユーザー設定の順で1つだけが採用されます。項目ごとの合成はしません。

設定の前に入れておく外部コマンド

Claude Codeは自前の辞書を持っていません。綴りが間違いかどうかは、ローカルにインストールしたチェッカーが判定します。

対応するのはaspell・hunspell・ispellの3つです。PATH上にあるものを、この順で探して最初に見つかったものを使います。Windowsでもパッケージマネージャーが置く.cmdのシムまで対象です。

インストールできたかは、ターミナルで確認できます。

aspell --version
hunspell --version
ispell -v

どれも「command not found」なら、PATHに入っていません。設定を書く前に、ここを先に通しておきます。

ユーザー設定に書く

個人で使うなら、いちばん素直な置き場所です。~/.claude/settings.jsonに書けば、開くすべてのプロジェクトで有効になります。

{
  "spellcheck": { "enabled": true }
}

有効になったかは、綴りを間違えた単語を打ってスペースを入れれば分かります。下線が付けば成功です。オフに戻すときは、同じ場所でenabledをfalseにするか、spellcheckごと消します。

設定ファイル全体の作法はClaude Code設定ガイドにまとめてあります。

--settingsで1セッションだけ有効にする

「今日のセッションだけ試したい」なら、--settingsが向いています。JSONをファイルに保存して渡します。

{
  "spellcheck": { "enabled": true }
}

claude --settings spellcheck.json

このファイルの内容は、そのセッションにしか効きません。ユーザー設定は書き換わらないので、試したあとの後始末が要りません。

claude --help(v2.1.289)では、--settings <file-or-json>の説明が「設定JSONファイルのパス、またはJSON文字列」となっています。ファイルを作らず、claude --settings '{"spellcheck":{"enabled":true}}'のように文字列で直接渡す書き方もできます。

管理設定で組織に配る

組織で揃えたいときの経路が管理設定です。配る側は管理設定のいずれかの経路にspellcheckを書きます。受け取る全員に適用され、利用者は自分で切れません。

管理設定の配り方そのものはClaude Code組織管理ガイドが扱っています。

3か所が競合したときの優先順位

一般の設定キーは、高い階層が低い階層を上書きしつつ、書いていないキーは下の値が残る合成になります。spellcheckは違います。

具体例で見ます。ユーザー設定に次の内容があるとします。

{
  "spellcheck": { "enabled": true, "language": "en_GB", "color": "yellow" }
}

ここから、次の挙動が導けます。

• --settingsでenabled: falseを書けば、ユーザー設定が有効でもそのセッションはオフになる
• 管理設定にspellcheckがあると、ユーザー設定のlanguageやcolorは効かない
• 「一部だけ上書き」はできないので、上書きするなら全フィールドを書き直す

「languageだけ変えたいのに、enabledまで書かされる」と感じたら、spellcheckだけが丸ごと置き換わる仕様が原因です。

追加できるフィールド

enabledの隣に、次の3つを置けます。どれも同じブロックの中に書きます。

checkerに名前を書くと、その1つしか使いません。未インストールでも、別のチェッカーには切り替わりません。aspell・hunspell・ispell・auto以外の値は、auto扱いになります。

languageはパスや空白入りの文字列を渡しても無視されます。使えるのは辞書名だけです。colorも、認識できない値ならテーマのエラー色のままです。

hunspellの英国辞書で黄色の下線にする例です。

{
  "spellcheck": {
    "enabled": true,
    "checker": "hunspell",
    "language": "en_GB",
    "color": "yellow"
  }
}

languageを省略すると日本語ロケールで辞書が見つからない

languageを省略すると、チェッカー自身の既定辞書が使われます。既定辞書はチェッカーがロケールから決めるので、日本語環境では落とし穴になります。

aspell 0.60.8.1を、LANG=ja_JP.UTF-8のまま-lなしで動かすと、辞書が見つからないというエラーになりました。-l en_USを付けると同じ入力が動きます。

echo "hello" | aspell list
# Error: No word lists can be found for the language "ja_JP".
echo "teh colour" | aspell -l en_US list
# teh
# colour

Claude Codeの--debugログで見る「辞書が無い」というエラーは、この型に当たる可能性があります。日本語ロケールで下線が出ないときは、languageにen_USのような手元の辞書名を書くと外れる原因の1つです。手元の辞書名はaspell dump dictsで一覧できます。

languageの効果もチェッカー単体で見えます。同じ綴りを、辞書を変えて通すと結果が分かれます。

echo "colour behaviour" | aspell -l en_US list
# colour
# behaviour
echo "colour behaviour" | aspell -l en_GB list
# (出力なし)

英国綴りを書く人がen_USのままだと、正しい綴りに下線が付きます。

日本語のプロンプトでは何が下線になるのか

日本語で指示を書くことが多い人は、この節が肝です。

Claude Codeは、中国語・日本語・韓国語・タイ語・ラオ語・クメール語・ミャンマー語のテキストを検査しません。除外されるのは上記の文字種のテキストだけです。日本語の文に混ざった英単語は、除外の対象に含まれていません。

さらに、コードらしく見えるものは最初から除外されます。

• /helpのようなコマンド、@メンション、URL、ファイルパス、--verboseのようなフラグ
• 数字・アンダースコアを含む語、2文字目以降に大文字がある語(camelCaseなど)、バッククォートで囲んだ語

チェッカー単体にそのまま渡すと、コードらしい語も未知語として返ります。teh recieve claude-code README.md fooBar user_nameをaspellに通すと、teh・recieveのほかにclaude・README・md・fooBarも出力されました。Claude Codeはこの種の語を最初から対象外にするので、同じ入力でも下線は付きません。

辞書に無い固有名詞や社内用語には、チェッカーの判定しだいで下線が付きます。下線を消したい単語は、チェッカーの個人辞書に足します。Claude Code側に単語リストはなく、辞書を編集したら再起動すると反映されます。

入力欄以外は検査対象外です。Claudeの返答やファイルの中身は見ません。シェルモード(!)、Ctrl+Rの履歴検索、音声入力の最中も動きません。スクリーンリーダーモードも対象外です。

オフにしたいときはどこを直すのか

オンにした場所と同じ場所で、オフにします。ユーザー設定ならenabledをfalseにするかspellcheckを消します。--settingsなら、そのファイルを渡さずに起動します。

管理設定で有効にされている場合は、利用者側で切れません。ユーザー設定をfalseにしても、管理設定のブロックが優先されるためです。切りたい場合は、管理設定を配っている管理者に依頼することになります。

逆に、ユーザー設定でオンにしている人が1回だけ切りたいときは、enabledをfalseにした--settingsのファイルを渡す手があります。ユーザー設定のspellcheckより--settingsが上位なので、そのセッションだけオフになります。ただし管理設定がspellcheckを持っている環境では、この手は効きません。

下線が出ないときの切り分け

設定を書いたのに何も出ないときは、まず優先順位を疑います。

1. プロジェクト側の.claude/settings.jsonや.claude/settings.local.jsonに書いていないか。ここは読まれません
2. より高い階層(管理設定や--settings)に別のspellcheckブロックがないか。あれば、ユーザー設定のブロックは丸ごと無効
3. enabledがtrueか、checkerの名前が正しいか
4. --restrictedで起動していないか。claude --help(v2.1.289)では、このモードはユーザー・プロジェクト・ローカルの設定ファイルを無視し、管理設定と--settingsだけが効くと説明されています

次にチェッカー側を疑います。Claude Codeは、チェッカーを維持できなくなると黙って下線を出さなくなります。

• チェッカーが未インストール、またはcheckerで指名したものが無い
• チェッカーが2回続けて失敗した。1回目は再起動しますが、2回目で以後の検査をやめ、Claude Codeを再起動するまで戻りません
• 応答に15秒を超えることが3回あった。3回目以降は検査をやめます

原因の特定には--debugが使えます。

claude --debug

スペルチェックを有効にした状態で単語を打つと、~/.claude/debug/<session-id>.txtに[spellcheck]で始まる行が出ます。起動したプログラム名、または探して見つからなかったプログラムの一覧が読めます。あとの行には、止まった理由が続きます。「辞書が無い」というエラーなら、languageで指定した辞書が入っていないか、languageを省略したのに既定の辞書が無い状態です。辞書を入れるか、手元にある辞書名をlanguageに書きます。

どの設定ファイルが読み込まれているかは、/statusのSetting sources行で確認できます。管理設定が適用されていれば、その経路も括弧書きで出ます。ただし、この行はキーごとの出所までは示しません。受理されなかった項目はclaude doctorで一覧できます。

Claudeに設定を書かせるときの頼み方

設定ファイルの編集をClaude Codeに任せるなら、書き込み先を指定します。「スペルチェックを有効にして」とだけ頼むと、書き込み先がClaudeの判断になります。プロジェクトの.claude/settings.jsonでは無視されるので、次のように場所まで指定すると確実です。

~/.claude/settings.json に spellcheck を追加して。enabled は true、
checker は hunspell、language は en_GB。書いたあとに aspell/hunspell の
--version を実行して、PATH にあることも確認して。

書き込み先を明示し、コマンドの実行結果まで読ませる形にしておけば、「書いたのに効かない」を後から探し回らずに済みます。.claude/settings.jsonにcommitされたspellcheckを見つけたら、それは効いていない設定です。ユーザー設定か管理設定へ移す候補になります。

「効く場所が限られるキー」は他にもある

spellcheckのように、プロジェクトの設定ファイルでは働かないキーは他にもあります。設定リファレンスでは、スコープが「User or managed」などと書かれたキーがその仲間です。どのキーがどこで効くかは、設定の索引にあるScope列で確認できます。

入力欄の補助機能でも、絵文字補完のemojiCompletionEnabledやpromptSuggestionEnabledのScopeは「Any file」で、プロジェクト設定にも書けます。絵文字補完は絵文字ショートコードの記事で扱っています。

機能の追加経緯はv2.1.235のリリースノートで読めます。

まとめ

リポジトリにコミットして配る方法はなく、個人ならユーザー設定、組織なら管理設定が置き場所です。上書きは一部のフィールドだけでは足りず、spellcheckのブロックごと書き直します。試すだけなら--settingsで1セッション分、続けて使うならユーザー設定です。日本語ロケールでは、languageに手元の辞書名を明示しておくと下線が出ない原因を1つ減らせます。