Posted inAI

Claude Codeの設定：settings.jsonファイルの活用ガイド

AI tutorial - IT technology blog
AI tutorial - IT technology blog

デフォルト設定の不満点

Claude Codeを使い始めた最初の1時間は、ひたすら「y」キーを叩き続けていました。2,000以上のファイルと複雑なビルドパイプラインを持つレガシーなNode.jsプロジェクトを扱っていた時のことです。AnthropicのCLIツールを使ったことがあるなら、そのワークフローはご存知でしょう。ターミナル上で直接、関数のリファクタリング、テストの実行、バグ修正などを行えます。しかし、初期状態のままでは意外にも手間がかかるのです。

lsやgrepといった単純なコマンドの実行を依頼するたびに、Claudeは許可を求めて一時停止しました。また、Haikuなら0.25ドルで済むような些細なドキュメント作成タスクでも、デフォルトでは100万入力トークンあたり3.00ドルかかるClaude 3.5 Sonnetが使用されていました。毎回手動で --model claude-3-5-haiku や --yes と入力するのは、作業の勢いを削ぐ原因になります。

コマンドラインフラグだけでは不十分な理由

デフォルトでは、Claude Codeは厳格な「安全第一」の考え方で動作します。実行環境については何も想定しません。単発の修正であれば claude コマンドにフラグを渡すだけでも機能しますが、8時間の勤務時間中ずっとそれを行うのは効率的ではありません。

CLIフラグだけに頼ると、主に3つのボトルネックが生じます：

  • 不整合： 安全フラグを付け忘れ、AIが誤って .env ファイルを上書きしてしまうといったミスが起こりやすくなります。
  • 予算の浪費： 制限を設けていないと、シェルスクリプト内の再帰ループによって、コーヒーを飲み終える前にAPIクレジットを使い果たしてしまう可能性があります。
  • コンテキストの欠如： プロジェクトでタブインデントや特定のVitestパターンを使用していることを、毎回伝えない限りAIは覚えてくれません。

環境変数 vs. settings.json

CLIをカスタマイズするには主に2つの方法があります。1つは .zshrc や .bashrc に環境変数を追加することです。これはAPIキーの設定には適していますが、複雑な動作や除外ディレクトリを定義しようとすると管理が煩雑になります。

settings.json を使う方法はよりスマートです。構造化された設定が可能になり、プライベートリポジトリでの管理やマシン間での同期も容易になります。これにより、Claudeは単なる汎用チャットボットから、特定の技術スタックを理解した専用ツールへと進化します。私の経験では、これらの設定を専用ファイルに移し、.claude/ディレクトリでAIエージェントを制御することで、プロジェクトを切り替えるたびにかかっていたセットアップ時間を約15分短縮できました。

settings.jsonファイルの設定

macOSやLinuxでは、Claude Codeは ~/.claude.json （バージョンによって異なる場合があります）の設定を参照します。以下は、日々の作業スピードに直結するパラメータです。

1. モデルの選択とコスト管理

常にSonnetのような高性能モデルが必要なわけではありません。基本的なファイル名の変更やボイラープレートの生成なら、Haikuの方が12倍安く、かつ大幅に高速です。デフォルトモデルを設定することで、コストを予測可能な範囲に抑えられます。

{
  "model": "claude-3-5-haiku-20241022",
  "max_tokens_to_sample": 4000,
  "temperature": 0
}

コーディングの際、私は常に temperature を0に設定しています。これにより、出力の決定論（再現性）が確保されます。AIには「独創性」を発揮してプロダクションコードを書き換えてもらうのではなく、論理に従ってもらう必要があるからです。

2. 権限承認の合理化

絶え間なく続くY/Nのプロンプトは、CLIユーザーにとって最大の不満点です。AIに完全な制御権を与えることなく、このプロセスを自動化できます。最善の戦略は、読み取り専用のアクションを自動承認し、書き込みコマンドは手動のままにすることです。

{
  "auto_approve": {
    "read_files": true,
    "list_files": true,
    "run_commands": ["ls", "pwd", "git status", "npm test"]
  }
}

npm test をホワイトリストに登録することで、AIが自律型Pythonエージェントのようにバグ修正を繰り返せるようになります。テストを実行し、失敗を確認し、再度修正を試みるというサイクルを、ユーザーが20回も「許可」をクリックすることなく進められます。

3. カスタム指示（システムプロンプト）

ここでは、チームの「完了の定義（Definition of Done）」を定義します。関数型プログラミングや厳格なTypeScriptを使用している場合は、AIが古いパターンを提案しないよう、ここに要件を記載します。

{
  "custom_instructions": "TypeScriptのアロー関数を使用してください。可読性のために早期リターン（early returns）を優先してください。すべてのユニットテストにはVitestを使用してください。/legacy-backupフォルダは無視してください。"
}

ワークフローの整理

最も効果的なセットアップは、1つの巨大なグローバルファイルだけを使うことではありません。プロフェッショナルな環境では、階層的なアプローチが最適であることがわかりました。

グローバル設定 vs. ローカル設定

"theme": "dark" のようなUIの好みは、ホームディレクトリのグローバル設定に保持します。一方で、言語固有のルールについてはプロジェクトレベルの上書き設定を使用します。AIは、ReactのフロントエンドからGoのバックエンドに移動する際、それに応じた振る舞いを変える必要があるためです。

コンテキストウィンドウの保護

50MBもの縮小（minify）されたJavaScriptを読み込むと、Claude Codeは混乱してしまいます。 ignore_patterns 配列を使用して、 node_modules、 dist フォルダ、巨大なロックファイルを隠しましょう。これによりコンテキストウィンドウがクリーンに保たれ、AIは重要なソースコードだけに集中できるようになります。

実践的な設定例

以下は、私がモダンなTypeScriptプロジェクトで使用している設定です。スピードを優先し、巨大なディレクトリ内でのAIの「ハルシネーション（もっともらしい嘘）」を防ぎます。

{
  "model": "claude-3-5-sonnet-20241022",
  "max_history_limit": 20,
  "auto_approve": {
    "read_files": true,
    "list_files": true,
    "run_commands": [
      "npm test",
      "git diff",
      "ls -la"
    ]
  },
  "custom_instructions": "あなたはシニアエンジニアです。簡潔に回答してください。早期リターンを使用してください。バグを修正する際は、パッチを適用する前にアーキテクチャ上の欠陥がないか確認してください。",
  "ignore_patterns": [
    "**/node_modules/**",
    "**/dist/**",
    "package-lock.json"
  ]
}

最終調整

これを設定すると、ツールの使用感が全く変わります。マイクロマネジメントをやめ、タスクを委譲できるようになります。Claude Codeの自動化を活用し、 claude "認証バグを修正して" と実行して、少し席を外すことも可能です。AIはファイルを読み込み、既存のテストを実行し、完成した差分（diff）を提示してくれます。もしAIが間違いを犯したとしても、モデルのせいにするのではなく、 ignore_patterns を洗練させてください。多くの場合、AIの失敗は無関係なデータが多すぎることが原因です。

Share:
Tags: