Claude Code設定カスタマイズ

claude-code-syncのログを眺めていて、Claude Codeの設定周りを掘り下げた。ステータスラインの使用率表示を仕込み、settings.jsonの「unrecognized」問題を追いかけ、自動アップデートを止めてバージョンを固定するまでの記録。

ステータスライン設定（Braille Dotsパターン）

Claude Codeにはターミナルのステータスラインにカスタム情報を表示する機能がある。Braille Dots（点字パターン）を使って、トークン使用率をプログレスバー風に表示する設定を入れた。

設定例

settings.json の statusLine フィールドに、シェルコマンドの出力をそのまま表示できる。Braille Dotsの ⣿（full）と ⣀（empty）を組み合わせると、ターミナル上で省スペースな使用率バーが作れる。

⣿⣿⣿⣿⣿⣀⣀⣀⣀⣀  50%

ポイントは、Braille Dotsは等幅フォントでも幅が安定しているため、ターミナルのステータスバーに向いているという点。普通のブロック文字（█）だと環境によって幅がずれることがある。

settings.jsonフィールドの「unrecognized」問題

症状

settings.json に以下のフィールドを設定したところ、Claude Codeが「unrecognized field」と警告を出した。

{
  "statusLine": "...",
  "enabledPlugins": [],
  "language": "ja",
  "alwaysThinkingEnabled": true,
  "effortLevel": "high",
  "voiceEnabled": false
}

画面上に黄色い警告テキストが並び、「設定が効いていないのでは？」と手が止まった。

調査プロセス

まず疑ったのは、これらがまだ実験的な機能で、安定版には含まれていないケースだ。CLIの --help やドキュメントを読み直したが、明確な記載がない。

次に試したのは、フィールドを1つずつ消して再起動する方法。statusLine を消すとステータス表示が消え、language を消すと英語に戻った。つまり、警告が出ていても設定自体は読み込まれて適用されていた。

結論: 警告は出るが、実際には有効

Claude Codeの設定バリデーションは、公式に定義されたスキーマに含まれないフィールドを「unrecognized」と表示する。しかし内部的にはそれらのフィールドを読み取って動作に反映している。

つまり、スキーマ定義と実装の間にギャップがある状態だった。警告を見て設定を消してしまうと、むしろ意図した動作が失われる。

教訓: 警告が出たら消すのではなく、実際の動作を確認する。フィールドを1つずつトグルして挙動の変化を見るのが確実だった。

自動アップデートの停止

Claude Codeはデフォルトで自動アップデートが有効になっている。作業中に突然バージョンが上がると、挙動が変わって困ることがある。特にプロンプトの効き方やツールの振る舞いが変わると、再調整に時間を取られる。

設定方法

settings.json に autoUpdate を追加する。

{
  "autoUpdaterStatus": "disabled"
}

これで自動アップデートが止まる。アップデートしたくなったら手動で claude update を実行すればよい。

バージョンロールバック

アップデート後に問題が出た場合、特定のバージョンに戻す方法も確認した。

手順

# 現在のバージョン確認
claude --version

# 特定バージョンをインストール
npm install -g @anthropic-ai/[email protected]

npmのグローバルインストールで任意のバージョンを指定すれば、そのバージョンに固定できる。autoUpdaterStatus: "disabled" と組み合わせることで、意図しないバージョンアップを防げる。

今日の設定まとめ

最終的な settings.json の構成。

{
  "statusLine": "(Braille Dots使用率表示)",
  "language": "ja",
  "alwaysThinkingEnabled": true,
  "effortLevel": "high",
  "autoUpdaterStatus": "disabled"
}

「unrecognized」の警告は出続けるが、全て動作している。警告に惑わされて設定を消してしまわないよう、このログを残しておく。

振り返り

settings.jsonの警告テキストを見て「壊れているのでは」と焦ったが、フィールドを1つずつ外して再起動を繰り返すうちに、警告と実動作が一致しないことに気づいた。公式ドキュメントに載っていない設定でも、ソースコード側では対応済みというケースがClaude Codeには散見される。「動かして確かめる」が最も信頼できるデバッグ手法だと、改めて手を動かして確認できた一日だった。