6ヶ月間、Claude Code を毎日使う中で、10個の設定パターンにたどり着きました。これらがないと、エージェントが誤った方向に進んだ箇所を直すために、月に10〜15時間を失っていました。設定を入れてからは、その時間が目に見えて減っています。
これは「Claude Code とは何か」を説明するチュートリアルではありません。すでにこのツールを使っていて、そこからもっと引き出したい人のための設定集です。各セクションの最後にそのままコピーできる設定を置いているので、すぐに使ってください。
1. CLAUDE.md は8,000文字まで、残りは別ファイルへ
最初の数ヶ月で犯した最大のミスは、CLAUDE.md に何もかも詰め込むことでした。3月の時点で、私のファイルは4万文字に膨れ上がっていました。アーキテクチャの決定、スタイルガイド、テスト規約、プロンプト例、ドメインモデル、オンボーディング、変更履歴。コンテキストは多いほど結果が良くなると思い込んでいたのです。
そうではありませんでした。原因は attention の仕組みにあります。Transformer は長い文書の中盤にある情報を保持するのが苦手です。4万文字になると、Claude はファイル中盤のルールを「忘れる」ようになりました。無視するのではなく、文字通り見えていないのです。実験でも確認しました。エージェントに自分の CLAUDE.md の300行目のルールを再現するよう頼んだところ、できませんでした。
厳格な上限を設けます。メインファイルは8,000文字まで。残りは必要に応じて読み込む別ファイルへ切り出します。
私が使っている構成です:
.claude/
├── CLAUDE.md # 常駐コンテキスト、8,000文字まで
├── skills/
│ ├── nestjs.md # NestJS セッション用ルール
│ ├── migration.md # TS マイグレーション用ルール
│ ├── review.md # コードレビュー用ルール
│ └── testing.md # テスト戦略
└── specs/
├── domain-model.md # プロジェクトのドメインモデル
├── api-contracts.md # API コントラクト
└── infra.md # インフラとデプロイ
CLAUDE.md には、例外なく毎セッションで必要なものだけを置きます。スタック、重要な禁止事項、specs と skills へのリンク。それ以外はすべて必要なときに読み込みます。
リファクタリング後はメインファイルが6,000文字になり、回答は明らかに正確になりました。長いセッションでも中盤でコンテキストを失わなくなり、セッション初期化時のトークン消費は約35%減りました。
2. .claude/settings.json — プロセスを変える設定
多くの開発者は settings.json を一度も開きません。デフォルトで動くから、それで十分だと。私が最初の1ヶ月のあとすぐに追加した設定を紹介します。
読み取りとテストを確認なしで許可する:
{
"permissions": {
"allow": [
"Bash(git log:*)",
"Bash(git diff:*)",
"Bash(git status:*)",
"Bash(git show:*)",
"Bash(npm test:*)",
"Bash(npm run lint:*)",
"Bash(npm run typecheck:*)"
],
"deny": [
"Bash(git push:*)",
"Bash(git reset --hard:*)",
"Bash(rm -rf:*)"
]
}
}
読み取りと確認だけの操作はすべて一時停止なしで通ります。git に書き込むものや削除するものはすべて確認を要求します。セッションあたりの中断回数が15〜20回から2〜3回に減りました。体感ではセッションが1.5倍ほど快適になっています。
deny は allow より優先されるので、危険なコマンドを確実にブロックできます。破壊的なデータ操作も同じ仕組みで止められます:
{
"permissions": {
"deny": [
"Bash(rm -rf:*)",
"Bash(git push --force:*)",
"Bash(kubectl delete:*)"
]
}
}
これらは全部、プロジェクトルートの .claude/settings.json に置いてリポジトリにコミットします。チームの全員が同じガードレールを手に入れます。個人だけの設定はコミットしない .claude/settings.local.json に分けます(後述の9を参照)。
3. acceptEdits — 全体ではなく選択的に有効化
acceptEdits は、ファイル変更のたびに出る確認リクエストをなくします。時間の節約に聞こえますが、有効に働くのは特定の種類のタスクに限られます。
有効にする場面:
- 型のマイグレーション:JS → TS、
anyの修正、インターフェースの更新 - 機械的な修正:リネーム、import の置換、フォーマット
- すでに書かれたロジックに対するテスト生成
- ドキュメントやコメントの更新
有効にしない場面:
- 新しい機能
- 複雑さを問わず、アーキテクチャのリファクタリング
- auth、payment、data layer の修正
- 「完了」の基準を10秒で言語化できないタスク
実例です。「未使用の import を整理して」というタスクで acceptEdits を有効にしました。エージェントは import を整理したあと、「ファイルを見ているついでに」といくつかのサービスを作り直すことに決めました。形式的には正しいのですが、その判断は私たちのパターンより劣るものでした。予定になかった30分のレビューが発生しました。
導入したルール:acceptEdits は、ミスを捕まえる自動テストがある場合のみ。テストがなければ手動確認です。
4. ガードレールとしての Hooks — 効くもの3つ
Hooks は Claude Code でもっとも過小評価されている機能です。エージェントのツール実行の前後で動く shell スクリプトで、stdin から JSON でコンテキストを受け取ります。私のワークフローを変えた3つを紹介します。
Stop hook — セッションごとのログ
#!/bin/bash
# ~/.claude/hooks/stop.sh
TASK=$(cat /tmp/claude_current_task 2>/dev/null || echo "no task recorded")
echo "$(date '+%Y-%m-%d %H:%M') | $TASK" >> ~/.claude/session_history.log
セッションが終わるたびに、時刻とタスクがログに落ちます。1ヶ月後には正直なレポートが手に入りました。平均で1日2時間15分、エージェントと作業し、4〜5セッション。それまでは Claude Code を「たまに」使っていると思っていました。データは違うことを示していました。
PreToolUse hook — 危険なコマンドのブロック
PreToolUse hook は stdin から JSON でツール入力を受け取ります。exit 2 を返すと実行がブロックされ、stderr の内容がエージェントに渡ります:
#!/bin/bash
# ~/.claude/hooks/pre_tool.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
DANGEROUS="(rm -rf|DROP TABLE|truncate|DELETE FROM.*WHERE 1=1|git reset --hard|kubectl delete)"
if echo "$COMMAND" | grep -qiE "$DANGEROUS"; then
echo "BLOCKED: potentially dangerous command: $COMMAND" >&2
exit 2
fi
exit 0
最初の3ヶ月でこの hook は7回作動しました。うち5回はエージェントが妥当な操作を提案していて、確認後に手動で実行しました。残り2回は、止めてくれて助かったと思いました。
Notification hook — 完了したら通知
#!/bin/bash
# macOS
osascript -e 'display notification "Claude Code がタスクを完了しました" with title "Claude Code"'
# Linux
# notify-send "Claude Code" "タスク完了"
ごく単純なものですが、習慣を変えました。30秒ごとにターミナルを覗くのをやめ、エージェントが動いている間に他のタスクへ実際に切り替えるようになりました。並行作業の生産性が上がりました。
settings.json での接続:
{
"hooks": {
"Stop": [{
"matcher": "",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/stop.sh" }]
}],
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/pre_tool.sh" }]
}]
}
}
5. アーキテクチャ決定のためのマルチモデル会議
Claude Code では、同じタスクに対して異なるモデルで並行セッションを走らせ、その結果を統合できます。時間の無駄に聞こえますが、実際には3〜4時間のチーム議論を置き換えます。
ロールバックが難しい決定に使います。モジュール構成、データスキーマ、サービス間のコントラクト、システムの中核部分のパターン選択など。
異なるモデルへの3つのリクエスト:
Opus: 「[X] を設計して。優先度: 信頼性とコントラクトの明示性」
Sonnet: 「[X] を設計して。優先度: 開発速度」
Haiku: 「[X] を設計して。最小の複雑さ、最小の抽象」
トレードオフの異なる3つの提案が得られます。そのあと4つ目のセッションを Opus で開き、私たちのコンテキストを踏まえて3つの良い部分を統合するよう頼みます。
所要時間は20〜25分。直近の大きなリファクタリング(イベント駆動部分の作り直し)では、これが1週間分のチーム議論を置き換えました。2〜3人で議論するよりもクリーンな解にたどり着きました。
チームに技術レビューをしてくれる2人目のシニアがいないときに、特によく効きます。
6. 「効果レベル」 — タスクに応じた深さ
エージェントの作業の深さは、タスクと期待するプロセスをどれだけ詳しく記述するかで変わります。私はこれを4つのレベルを持つ自作 skill として形式化しました(/effort は組み込みコマンドではなく、私が定義した skill です。組み込みでは think / ultrathink といったキーワードで思考の深さを上げられます)。
# skill: effort-levels
/effort low
速いドラフト。説明なし、計画なし。ただコードを書く。
用途: 小さなユーティリティ、スクリプト、使い捨てのタスク。
/effort medium
通常のタスク。短い計画、それから実装。
用途: 標準的な機能、修正、リファクタリング。
/effort high
複雑なタスク。詳細な計画、それから実装。
用途: 新しいコンポーネント、公開 API の変更。
/effort max
クリティカルなタスク。分析、計画、承認、実装、レポート。
エージェントは各ステップのあとで停止し、明示的な OK を待つ。
用途: システム中核の変更、auth、スキーマのマイグレーション。
/effort max では、半年でフルロールバックが必要になったケースはゼロでした。レベルを明示しなかったタスクでは、エージェントが誤った方向へ進み、最後になって気づいたケースが3〜4回ありました。
おまけの効果もあります。/effort max と書いてみて、このタスクには大げさだと感じたら、それはタスクが思ったより簡単だというサインです。逆もまた然りです。
7. Context Rot — 早めに見抜いて再起動する
Context Rot とは、長いセッションでコンテキストが蓄積するにつれて回答品質が劣化する現象です。エージェントは自己矛盾を起こし、決定済みのことを「忘れ」、すでに却下した案を提案し始めます。
3つの兆候:
- 同じセッション内ですでに議論して却下した案を、エージェントが再び提案する
- たった今書いたばかりのコードを変更するよう勧めてくる
- 10メッセージ前に与えたタスクに対して「コンテキストを明確にしましょう」と返してくる
兆候が出たら続けないこと。続行は悪化させるだけです。短い要約とともに新しいセッションを始めます。
新しいセッションへの引き継ぎテンプレート:
# 続行のためのコンテキスト
**タスク:** [何をしたいか1文で]
**完了済み:**
- [ファイル/関数]: [具体的に何をしたか]
- [ファイル/関数]: [具体的に何をしたか]
**やらないこと(議論済み):**
- [案 X]: [理由]
- [案 Y]: [理由]
**次のステップ:** [具体的に、1項目]
このテンプレートの記入は3〜5分。劣化したセッションを続けるより5〜10倍速いです。
私個人のトリガー:3メッセージ連続でタスクが前に進まなければ、問答無用で再起動。
8. 2回修正ルール
同じ論点について1セッション内で2回エージェントを修正したら、止まること。これはエージェントの頑固さではありません。タスクの設定かコンテキストに何か問題があるというサインです。
このルールの前は、「頑固な」タスクに1.5〜2時間を費やしていました。補足を与え、エージェントが作り直し、それでも違う、さらに補足を与える。堂々巡りです。
2回修正ルールを導入してからは、2回目の修正で止まり、タスクをゼロから組み立て直します。方法は3つ:
1. より小さく分割する。 エージェントが X を2回正しくできないなら、X が大きすぎる可能性があります。X1 と X2 に分けて順に解きます。
2. 期待する結果の例を与える。 「正しくやって」の代わりに「最終的にこう見えるべき」を具体例で示します。結果の精度の差は歴然です。
3. 雛形を書く。 構造やシグネチャを私が下書きし、エージェントが中身を埋めます。アーキテクチャ系のタスクで特によく効きます。「これがサービスのインターフェース、実装を書いて」は、単に「X 用のサービスを書いて」よりずっと正確に動きます。
半年で、2回修正ルールは私の見積もりで15〜20時間を節約しました。以前は無に消えていた時間です。
9. 環境ごとに設定を分ける
Claude Code の設定は階層的にマージされます。チーム共有の .claude/settings.json、個人用でコミットしない .claude/settings.local.json、そしてユーザー全体の ~/.claude/settings.json。これを使って、共有のガードレールと個人の作業速度を両立させます。
.claude/settings.json(チーム共有・厳格、リポジトリにコミット):
{
"permissions": {
"deny": [
"Bash(kubectl delete:*)",
"Bash(terraform destroy:*)",
"Bash(rm -rf:*)"
]
}
}
.claude/settings.local.json(個人・ローカル、.gitignore に入れる):
{
"permissions": {
"allow": [
"Bash(docker compose down:*)",
"Bash(docker compose up --build:*)",
"Bash(npm run db:reset:*)"
]
}
}
ローカル環境では速く動けます。docker やデータベースの操作のたびに止まりません。一方で、deny に入れた本番に関わる破壊的操作はチーム設定で確実にブロックされたままです。deny は allow より優先されるので、ローカルの allow が共有のガードレールを上書きしてしまう心配もありません。
権限モード自体も --permission-mode plan のように起動時に切り替えられるので、調査だけしたいときは plan モード、機械的な作業のときは acceptEdits、という使い分けも合わせて効きます。
10. 固有コンテキストを遅延読み込みする Skills
Skills は .claude/skills/ に置く Markdown ファイルで、必要なときに読み込みます。エージェントはそのファイルの内容を追加コンテキストとして受け取ります。
狙いは、固有のコンテキストを常時エージェントのメモリに保持しないこと。必要なときだけ読み込みます。
私の構成:
.claude/skills/
├── nestjs-conventions.md # NestJS モジュールの規約
├── clean-arch.md # プロジェクトでの CA 原則と例
├── typescript-strict.md # 使っている TypeScript strict ルール
├── git-workflow.md # git flow とコミット規約
├── testing-strategy.md # テスト戦略とパターン
├── migration-playbook.md # TS マイグレーションのプレイブック
└── code-review-checklist.md # コードレビュー用チェックリスト
各 skill は特定の種類のタスク用のコンテキストです:
- 新しい NestJS モジュールを書く →
nestjs-conventions - アーキテクチャをリファクタリングする →
clean-arch - コードレビューをする →
code-review-checklist
nestjs-conventions.md の一部の例:
# このプロジェクトでの NestJS 規約
## モジュール構成
各モジュールは domain/、application/、infrastructure/、presentation/ を含む
禁止: domain 層でのモジュール間の直接依存
## 禁止事項
- class-validator はビジネスバリデーションに使わない。入力 DTO のみ
- DB 操作にはすべて Repository パターンが必須
- NestJS のライフサイクルフックは Application 層でのみ使う
## 例
[コードベースからの実例]
skills に移行した後の結果:
- メインの CLAUDE.md が4万文字から6,000文字に縮小
- 固有のコンテキストは必要なときに読み込まれる
- 標準セッションのトークン消費が30〜40%減少
- エージェントが異なるドメインのルールを混同しなくなった
まとめ
この10個の設定は、6ヶ月の反復の結果です。一部はドキュメントから自明ではなく、一部は何かがうまくいかなかったときの直接的な痛みから来ています。
この期間で一番わかったこと。Claude Code は、箱から出してそのままよく動くツールではありません。ワークフローを設定するためのプラットフォームです。デフォルトは「十分」のレベルで動きます。正しい設定は「本気で速くなる」レベルへ引き上げます。
私の見積もりでは、この10個の設定は最初の半年で合計50〜60時間を節約しました。およそ1週間分の労働時間です。
リストに入らなかった自分の設定があれば、ぜひコメントで教えてください。特に hooks については、まだ見つけていないパターンが確実にあるはずです。
余談: 複数モデルを並行で走らせ始める(セクション5)と、次に出てくる問いが「どのワークフローがどのモデルにいくら使っているのか」です。私たちは EvoLink で、プロバイダーをまたいだワークフロー単位のコスト可視化に取り組んでいます。興味があれば覗いてみてください。