Claude Code の運用 — 結局どうすればいいか
16本を統合する。**機能の一覧ではなく、「いつ何を足すか」と「日々どう回すか」**を書く。
1. 最初に理解すること: ループとその割り込み方
Claude Code は gather context → take action → verify results を回す harness である。
Claude Code serves as the agentic harness around Claude: it provides the tools, context management, and execution environment. Claude Code は Claude を包む agentic harness として機能する。ツール、context 管理、実行環境を提供する。
自分もループの一部であり、割り込み方が2つある。この2つの区別が日々の効率を大きく変える。
| 操作 | 挙動 |
|---|---|
Esc | **即座に停止。**実行中のツール呼び出しをキャンセルして次の指示を待つ |
訂正を打って Enter | **実行中のツールは止めない。**現在の操作が終わり次第 Claude が読み、次の判断の前に調整する |
やり直さずに直すのが基本。
When the first attempt isn’t right, you don’t start over. You iterate. 最初の試行が正しくなかったとき、やり直すのではない。反復するのだ。
2. 何もない状態から何を足すか（順序がある）
最初から全部設定しない。 それぞれに分かりやすい引き金がある。
| 引き金 | 足すもの |
|---|---|
| 規約やコマンドを 2回間違えた | CLAUDE.md |
| 同じプロンプトを毎回打っている | user-invocable な skill |
| 同じ手順書を 3回目チャットに貼った | skill |
| 見られないブラウザタブからデータをコピーし続けている | MCP server |
| シンボルを探すのに大量のファイルを読んでいる | code intelligence プラグイン |
| 二度と参照しない出力で会話が溢れる | subagent |
| 頼まなくても毎回起きてほしい | hook |
| 2つ目のリポジトリで同じ設定が要る | plugin |
同じ引き金は更新のタイミングでもある。繰り返す間違いやレビュー指摘は、チャットでの一度きりの訂正ではなく CLAUDE.md の編集である。
この表は「何を足すか」までで、どこに置くか（プロジェクト直下か ~/.claude か）は別の判断になる。個人スコープに置いたときだけ起きることは user-config を見る。
最も重要な区別（features-overview と memory が繰り返す）:
An instruction like “never edit
.env” in CLAUDE.md or a skill is a request, not a guarantee. APreToolUsehook that blocks the edit is enforcement. CLAUDE.md や skill に書いた「.envは絶対に編集するな」という指示はお願いであって、保証ではない。編集を止めるPreToolUsehook が強制である。
CLAUDE.md も skill も「context」であって「設定」ではない。 必ず守らせたいものは hook にするしかない。
3. CLAUDE.md の書き方
200行以内。 超えたら移す。
| 書くもの | 書かないもの |
|---|---|
| ビルド・テストのコマンド | 多段の手順（→ skill へ） |
| 規約、プロジェクト構成 | コードベースの一部にしか関係しないもの（→ path-scoped rule へ） |
| 「常に X せよ」 | コードから導出できるもの（ディレクトリ構成、依存一覧） |
具体性がすべて:
| ❌ | ✅ |
|---|---|
| Format code properly コードを適切にフォーマットせよ | Use 2-space indentation インデントは半角スペース2つ |
| Test your changes 変更をテストせよ | Run npm test before committingコミット前に npm test を実行せよ |
| Keep files organized ファイルを整理せよ | API handlers live in src/api/handlers/API ハンドラは src/api/handlers/ に置く |
矛盾に注意: 矛盾する2つのルールがあると Claude はどちらかを恣意的に選ぶ。定期的に見直す。
大規模リポジトリでは階層化する（large-codebases）。ただし重要な非対称性がある。
CLAUDE.md は階層的に継承されるが、
.claude/settings.jsonは継承されない（起動ディレクトリからしかロードされない）。
/doctor が trim を提案してくれる — コードベースから導出できる内容を削り、落とし穴・理由・ツール既定と異なる規約を残す。
4. 日々の回し方
プロンプトの型
common-workflows と prompt-library に共通する4段。
広く聞く → 絞る → 適用する → 検証するgive me an overview of this codebase
explain the main architecture patterns used here
how is authentication handled?具体的に書くほど直しが減る
❌ Fix the login bug
✅ The checkout flow is broken for users with expired cards.
Check src/payments/ for the issue, especially token refresh.
Write a failing test first, then fix it.検証対象を与える
これが最も効く単一の習慣。
Implement validateEmail. Test cases: 'user@example.com' → true,
'invalid' → false, 'user@.com' → false. Run the tests after.視覚的な作業ならスクリーンショットを貼って比較させる。
探索と実装を分ける
Shift+Tab を2回で plan mode。計画をレビュー・洗練してから実装させる。
This two-phase approach produces better results than jumping straight to code. この2段構え（調査してから計画する）は、いきなりコードに入るより良い結果を生む。
高価なやり直しを防ぐのが目的なので、複雑な作業ほど効く。
軌道修正の3型（prompt-library）
that is not right: {feedback}. try a different approach
that is too much. keep only the changes to {scope} and undo your other edits
you keep {mistake}. add a rule to CLAUDE.md so this stops happening3つ目が重要。 訂正をその場で終わらせず、仕組みに変える。
5. context を保つ日常操作
| 操作 | いつ |
|---|---|
/clear | 無関係な作業に移るとき。コストゼロ |
/compact <focus> | 継続したいが context が重いとき |
/context | 何が食っているか分からないとき |
/usage | skill / subagent / plugin / MCP 別の内訳を見たいとき |
| subagent に委譲 | 調査で大量のファイルを読むとき |
/clear と /compact のコストが違う。 /compact は要約対象を読むので大きなリクエストになる。継続が不要なら /clear。
6. 権限とモード
モードの選び方
| モード | 確認なしに走るもの | 向く場面 |
|---|---|---|
default（Manual） | 読み取りのみ | 使い始め、機微な作業 |
acceptEdits | 読み取り + ファイル編集 + mkdir / mv など | レビューしながら反復 |
plan | 読み取り + 分類器承認のコマンド | 変更前の探索 |
auto | すべて（分類器の審査付き） | 長いタスク、プロンプト疲れの軽減 |
dontAsk | 事前承認したツールのみ | ロックダウンした CI |
bypassPermissions | すべて | 隔離コンテナ / VM のみ |
Shift+Tab で default → acceptEdits → plan を巡回。
ルールの落とし穴
deny → ask → allow の順。最初に一致したものが決める。具体性は順序を変えない。 → 広い deny に狭い allow の例外は作れない。
抜け道は1つだけ: PreToolUse hook の exit code 2 は permission ルールの評価より前に止まる。
→ 「Bash を全許可して、危険なものだけ hook で止める」構成が成立する。
踏みやすい罠:
Bash(ls *)はlsofにマッチしないが、Bash(ls*)（空白なし）はマッチする- 複合コマンドは各サブコマンドが独立にマッチする必要がある
devbox run/npx/docker execはラッパー剥がしの対象外 →Bash(devbox run *)はdevbox run rm -rf .まで通すpermissions.allowは protected paths（.git、.claude、.env系）を事前承認しない
7. 何を hook にするか
判断基準は「毎回必ず起きてほしいか」の一点。
| hook | skill | |
|---|---|---|
| 決定性 | 必ず発火する | Claude が解釈する。結果はぶれる |
| context コスト | 出力を返さない限りゼロ | description は毎セッション |
| 向く用途 | lint、危険コマンドのブロック、ログ、通知 | 推論が要るワークフロー、参照資料 |
hook の応用で効果が大きいもの:
- 出力の前処理 — 1万行のログを grep して該当行だけ返す（数万トークン → 数百）
Stophook で完了判定 — 「本当に全部終わったか」を LLM に判定させる（prompt型）Stophook で CLAUDE.md 更新を提案 — transcript のパスを受け取れるので、ギャップが新鮮なうちに提案できるSessionStarthook で context 注入 — stdout が最初のプロンプトの前に context へ入る
注意: 複数の hook が同じイベントにマッチすると全部並列に走る。1つが deny を返しても他は止まらないので、副作用の抑制を deny に頼らない。
8. 大規模コードベース
最初に決めるのは「どこで claude を起動するか」。 それによってロードされる CLAUDE.md も、適用される設定も変わる。
| 起動場所 | ロードされる CLAUDE.md | 使うとき |
|---|---|---|
| リポジトリルート | ルートのみ（サブは読んだときオンデマンド） | 複数パッケージにまたがる |
| サブディレクトリ | そのディレクトリと全祖先 | 1パッケージに閉じている |
効く設定（層をなす）:
ディレクトリごとの CLAUDE.md 触っているコードの規約だけロード
claudeMdExcludes 触らないパッケージを除外
permissions.deny の Read 生成物・vendored を開かせない
code intelligence プラグイン ファイル走査を language server に置き換え
worktree.sparsePaths 必要なディレクトリだけ checkout
ディレクトリごとの skill 関連するときだけロードworktree の落とし穴: sparsePaths に .claude を入れないと、ルートの設定が worktree 内で使えない。
9. CI とスクリプト
--bare を付ける。
Add
--bareto reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md.--bareを付けると、hook・skill・plugin・MCP サーバ・auto memory・CLAUDE.md の自動探索を省略して起動時間を短縮できる。
理由は速度ではなく再現性: 同僚の ~/.claude の hook やプロジェクトの .mcp.json が走らないので、どのマシンでも同じ結果になる。
認証の注意: bare mode は OAuth も keychain も読まない。ANTHROPIC_API_KEY が要る。
CI で失敗を検知する:
system/init の plugin_errors / mcp_server_errors が非空なら落とす
（エラーがなければキー自体が省略されるので、非空配列で gate できる）便利な型:
# diff をパイプすると Bash 権限が不要になる
git diff main | claude -p "you are a typo linter. ..."
# 構造化出力
claude -p "..." --output-format json --json-schema '{...}' | jq '.structured_output'10. 実践者が実際にやっていること
how-anthropic-teams-use-claude-code の10チームから、運用に効くもの。
checkpoint を刻む。ダメなら捨てる
Starting over often has a higher success rate than trying to fix Claude’s mistakes. やり直すほうが、Claude の間違いを直そうとするより成功率が高いことが多い。
「スロットマシン」— 状態をコミットし、30分走らせ、受け入れるか最初からやり直すか。
一発で通るのは約3分の1（RL Engineering チーム）。だから まず one-shot を試し、通らなければ協調モードへ。
簡単にさせる割り込み
why are you doing this? Try something simpler. なぜこれをやっているのか。もっと単純な方法を試してくれ。
The model tends toward more complex solutions by default but responds well to requests for simpler approaches. モデルは既定でより複雑な解に傾くが、単純な方法を求められればよく応じる。
CLAUDE.md にツール呼び出しのミスを書く
run pytest not run and don't cd unnecessarily - just use the right path非技術者は2段階で
1. Claude.ai で実装・UX・エッジケース・トレードオフを検討
2. 「step-by-step の実装プロンプトにまとめて」と頼む
3. Claude Code に渡し、「1ステップずつやって」と指示チームで使い方を見せ合う — 自分では気づかない使い方が広がる。
11. 日々のチェックリスト
作業を始める前
□ 無関係な前の作業が残っていないか → /clear
□ 複雑なら plan mode から → Shift+Tab ×2
□ 検証手段を渡したか → テストケース、スクショ、期待出力
作業中
□ 方向が違う → Esc で止める / 訂正を打つ
□ 複雑にしすぎている → 「Try something simpler」
□ 同じ訂正が2回目 → CLAUDE.md に書く
作業の後
□ 調査で context が膨らんだ → 次は subagent に回す
□ 同じ手順を3回貼った → skill にする
□ 毎回必ず起きてほしい → hook にする
ときどき
□ /context と /usage で消費を見る
□ CLAUDE.md が 200行を超えていないか（/doctor が trim を提案する）
□ 使っていない MCP サーバを /mcp で無効化