Claude Code の運用 — いつ何を足すか — 結局どうすればいいか
31本を統合する。機能の一覧ではなく、「いつ何を足すか」と「日々どう回すか」を書く。
1. 最初に理解すること: ループとその割り込み方
Claude Code は gather context → take action → verify results を回す harness である。
Claude Code is the layer around the model that provides the tools and manages the context the model sees. This surrounding layer is what the term agentic harness refers to.
Claude Code は、モデルを包む層であり、ツールを提供し、モデルが見る context を管理する。agentic harness という言葉が指すのは、この包む層である。 — how-claude-code-works
自分もループの一部であり、割り込み方が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 |
| 並行して走らせたい（片方が機能、片方がバグ修正） | worktree（claude --worktree <name>） |
1つのプロジェクトか自分だけのためなら、単体の構成のままにする。 plugin にするのは、チームメイトと共有する・いくつものプロジェクトに入れる・バージョン付きで公開するとき（plugins-create）。有効な plugin は、Claude が自分で呼べる skill・agent・command の名前と説明を使わないセッションでも毎ターン context に載せる（plugins）。移すときは skill と agent に plugin 名の接頭辞が付く（/deploy → /my-plugin:deploy）が、hook には付かないので、元の設定を消すまで同じ hook が2回走る。
セッションを跨ぐときは「戻らないもの」を先に知る。 再開で会話・agent は戻り、モデルもたいてい戻るが、
起動時に --model や ANTHROPIC_MODEL 系の環境変数で指定したとき、退役・availableModels 外のとき、
Bedrock / Agent Platform / Foundry のようにデプロイ ID を使うときは戻らない。
--mcp-config / --settings / --plugin-dir / --fallback-model / --add-dir は渡し直しが要る。
permission mode はさらに厳しく、bypassPermissions と plan はターミナル再開でも復元されない
（危険な側に倒れないための設計）。セッションピッカーから選んだ場合と /resume での切り替えは、
そもそも保存されたモードを使わない。 — sessions
⚠️ フォークせずに同じセッションを2つのターミナルで再開すると、両方のメッセージが1つの
transcript に混ざる。 分岐するなら /branch（同じプロセス。承認を引き継ぐ）か
--fork-session（別プロセス。承認は取り直し）。
同じ引き金は更新のタイミングでもある。繰り返す間違いやレビュー指摘は、チャットでの一度きりの訂正ではなく 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 にするしかない。
並行実行の隔離も「お願い」ではない
worktree を使うと、Claude Code が4つの検査でメインのチェックアウトへの到達を拒否する —— ファイル編集、コマンドの作業ディレクトリ、git のリダイレクト（git -C / GIT_DIR / 事前の cd）、そしてコマンドの形。最後のものは git を一切使わないコマンドにも及び、追跡できない構文（brace 展開、引用符無しの heredoc）を拒否する。
You can’t turn this check off.
この検査は切れない。 — worktrees
同じ強制は、そのセッションが起こす subagent 全部に及ぶ。 subagent 側を恒久的に隔離したいなら frontmatter に isolation: worktree を書く。
⚠️ hook のパスは worktree に付いてこない。 ${CLAUDE_PROJECT_DIR} はセッションが始まった場所を指したままで、worktree のパスが要る hook は入力 JSON の cwd を読む。
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 は継承されない（親ディレクトリから引き継がれない。どのディレクトリのものを読むかは settings）。
/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?具体的に書くほど直しが減る
症状・ありそうな場所・「直った」とは何かを書く（claude-code-best-practices）:
❌ fix the login bug
✅ users report that login fails after session timeout. check the auth flow
in src/auth/, especially token refresh. write a failing test that
reproduces the issue, then fix it検証対象を与える
これが最も効く単一の習慣。
write a validateEmail function. example test cases: user@example.com is true,
invalid is false, user@.com is false. run the tests after implementing視覚的な作業ならスクリーンショットを貼って比較させる。
探索と実装を分ける
ステータスバーに ⏸ plan mode on が出るまで Shift+Tab を押す（または claude --permission-mode plan で始める）。計画をレビュー・洗練してから実装させる。押す回数は決め打ちしない —— 開始時の permission mode によって、何回で plan mode に着くかが変わる。
高価なやり直しを防ぐのが目的なので、複雑な作業ほど効く。
軌道修正の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。
セッションの請求額を決めるもの
同じ修正でも、回し方で値段が変わる。 決めるのは3つ —— いくつのトークンが context に入るか、それが何ターン居座るか、同時にいくつの context を走らせているか。
One long session costs more than the same work spread over a few short ones, and by more than you’d think, because turn 40 is also re-reading the 39 turns before it.
1本の長いセッションは、同じ作業を短いセッション数本に分けた場合より高くつく。しかも思っている以上に高い。40ターン目は、その前の39ターンも読み直しているからだ。 — maximizing-session-value
prompt cache を捨てる操作は、安い瞬間に寄せる。 キャッシュはリクエストの先頭から一致していなければならず、順序は tool definitions → system prompt → 会話（先頭に CLAUDE.md）で固定されている。前方が変われば、その後ろは全部 prefill し直しになる。
| 捨てる操作 | 補足 |
|---|---|
/model | モデルごとに別のキャッシュ。opusplan は plan mode の出入りで毎回替わる |
/effort | キーの一部。/model と /effort が会話の途中で確認を求めるのはこれが理由。ただし Opus 5.5 を API キーか購読で使うなら、変えてもキャッシュは保たれる（Bedrock・Agent Platform・Claude apps gateway では壊れる。what-a-task-costs-on-opus-5-5。Fable 5.1 も「Opus 5.5 や Fable 5.1 のような新しいモデル」として挙がるが、提供経路の条件は書かれていない —— opus-5-5-for-longer-coding-sessions。食い違いは OVERVIEW §5） |
| Fast mode | キーの一部。しかも再 prefill が fast mode の価格で走るので、使うなら最初に入れる |
/compact | 会話が置き換わる。古い会話がまだキャッシュに載っているうちなら、要約を書く処理自体は安い |
| 1時間の放置 | サブスクは1時間（usage credits を使い始めたら5分）、API キーとクラウドプロバイダは既定で5分で失効（どちらも1時間を設定できる —— opus-5-5-for-longer-coding-sessions）。古いセッションの再開はほぼ必ず prefill し直し |
None of this means you should never switch models or effort. It means there are cheap moments to do it, the start of a session or right after a /clear, and expensive ones, the middle of a long conversation.
これはモデルや effort を切り替えるなという意味ではない。切り替えるのに安い瞬間（セッションの開始直後や
/clearの直後）と、高い瞬間（長い会話の途中）があるということだ。 — maximizing-session-value
日々の操作に落ちるもの:
- ファイルは名前を書かずに @メンションする。 送信前に添付されるので Read 呼び出しが消える。1会話につき1回でよい（あとのターンで再び @メンションすると2つ目のコピーが付く）
- うるさいコマンドは quiet フラグか subagent へ。 30,000文字を超える出力はファイルに逃げてパスだけが残るので実は安全で、問題はその閾値の下（400件の通過テストを1行ずつ出すランナーは、丸ごと残り全ターンに乗る）
- 直近の数ターンを捨てたいだけなら
/compactではなく/rewind。 末尾を切り落とすだけなので、その前はキャッシュに載ったままで費用がかからない /loopは仕掛けたセッションの中で1つの完全なターンとして発火し、毎回その会話全体を連れていく。 別のターミナルで新しいセッションを立て、そこから回す
6. 権限とモード
モードの選び方
| モード | 確認なしに走るもの | 向く場面 |
|---|---|---|
default（Manual） | 読み取りのみ | 使い始め、機微な作業 |
acceptEdits | 読み取り + ファイル編集 + mkdir / mv など | レビューしながら反復 |
plan | 読み取り + 分類器承認のコマンド | 変更前の探索 |
auto | すべて（分類器の審査付き） | 長いタスク、プロンプト疲れの軽減 |
dontAsk | 事前承認したツールのみ | ロックダウンした CI |
bypassPermissions | すべて | 隔離コンテナ / VM のみ |
Shift+Tab で default → acceptEdits → plan を巡回。
ルールの落とし穴
deny → ask → allow の順。最初に一致したものが決める。具体性は順序を変えない。 → 広い deny に狭い allow の例外は作れない。
抜け道は2つ: PreToolUse hook の exit code 2 は permission ルールの評価より前に止まる。
→ 「Bash を全許可して、危険なものだけ hook で止める」構成が成立する。
もう1つはパスのルール（Read / Edit）限定で、同じ設定ファイルの deny / ask に ! を並べる方法（permissions）。Bash のルールには効かない。
踏みやすい罠:
Bash(ls *)はlsofにマッチしないが、Bash(ls*)（空白なし）はマッチする- 複合コマンドは各サブコマンドが独立にマッチする必要がある
devbox run/npx/docker execはラッパー剥がしの対象外 →Bash(devbox run *)はdevbox run rm -rf .まで通すpermissions.allowは protected paths（.git、.claude、.env系）を事前承認しない
熟練するとどう変わるか（実測）
measuring-agent-autonomy が数百万件の実データで測っている。自動承認も割り込みも両方増える。
| 新規（〜50セッション） | 熟練（750セッション） | |
|---|---|---|
| 完全自動承認 | 約 20% | 40% 超 |
| ターンあたり割り込み率 | 約 5% | 約 9% |
New users are more likely to approve each action before it’s taken, and therefore rarely need to interrupt Claude mid-execution. Experienced users are more likely to let Claude work autonomously, stepping in when something goes wrong or needs redirection. —
measuring-agent-autonomy新規ユーザーは各行動を実行前に承認しがちなので、実行中に割り込む必要がめったにない。熟練ユーザーは Claude を自律的に働かせ、何かがおかしくなったときや方向転換が要るときに入る。
つまり下げるのは承認の粒度だけで、監視の密度はむしろ上げる。両方下げると監督ではなく放置になる。原典の言葉では:
effective oversight doesn’t require approving every action but being in a position to intervene when it matters —
measuring-agent-autonomy有効な監督とは、すべての行動を承認することではなく、重要なときに介入できる位置にいることである。
Claude 側も止まる。最も複雑なタスクでは、Claude が確認のために止まる頻度が人間の割り込みの2倍以上。止まる理由の最多は「提案した複数の方針から選ばせるため」(35%)、人間が割り込む理由の最多は「欠けている技術的文脈や訂正を与えるため」(32%)。
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 内で使えない。
大規模での投資順序（harness はモデルと同じくらい効く）
the ecosystem built around the model—the harness—determines how Claude Code performs more than the model alone —
how-claude-code-works-in-large-codebasesモデルの周りに構築されたエコシステム —— harness —— の方が、モデル単体よりも Claude Code の性能を決めている。
同じ原典が挙げるよくある取り違えが、§2 の順序と正面から噛み合う。
| 構成要素 | 取り違え |
|---|---|
| CLAUDE.md | skill に属する再利用可能な専門知識をここに入れる |
| Hooks | 自動で走るべきものを prompt でやろうとする |
| Skills | 代わりに全部を CLAUDE.md へ入れる |
| Plugins | 良い設定が属人的なまま留まる |
| MCP servers | 基礎が動く前に MCP 接続を作る |
| Subagents | 探索と編集を同じセッションでやる |
そして CLAUDE.md は積むだけでなく削る対象である。
As models evolve, instructions written for your current model can work against a future one. —
how-claude-code-works-in-large-codebasesモデルが進化すると、現在のモデル向けに書いた指示が将来のモデルに対して逆に働きうる。
例として「すべてのリファクタを1ファイル単位に分割せよ」が挙がる。旧モデルを軌道に乗せる役には立ったが、新しいモデルが得意なファイル横断編集を妨げる。推奨される見直し周期は 3〜6ヶ月、加えて大きなモデルリリース後に性能が頭打ちに感じたとき。
もう一つ、大規模で効くのが LSP。grep はありふれた関数名で数千件を返し、Claude はどれが重要かを判断するためにファイルを開いて context を燃やす。LSP は同じシンボルを指す参照だけを返すので、絞り込みが読み込みの前に済む。
ループを直す（個々の失敗を直すのではなく）
ai-code-migration は大規模な機械的作業でこのループを回した実践記で、一文に凝縮されている。
The core insight is that you don’t fix the code. You fix the process (loop) that produced the code. —
ai-code-migration中核的な洞察は、コードを直すのではないということだ。そのコードを生んだプロセス（ループ）を直す。
具体形は「レビュアーが複数ファイルで同じ間違いを捕まえ続けたら、ルールブックに1文足してバッチを再生成する。コードには手を当てない」。§4 の回し方をそのまま大規模に伸ばした形になる。
持ちこたえた実践のうち、日常の規模でも効くもの:
Don’t focus on individual failures. Individual failures are the loop’s job. Fixer agents burn those down. Your attention belongs on the patterns. —
ai-code-migration個々の失敗に注目するな。個々の失敗はループの仕事だ。（略）見るべきはパターンである。
Make the work queue mechanical and resumable. Done should mean “the output file exists on disk.” —
ai-code-migration作業キューは機械的かつ再開可能にせよ。「完了」は「出力ファイルがディスク上に存在する」を意味すべきである。
9. CI とスクリプト
--bare を付ける。
Add
--bareto reduce startup time by skipping auto-discovery of hooks, skills, custom commands, subagents, plugins, MCP servers, auto memory, and CLAUDE.md.
--bareを付けると、hook・skill・カスタムコマンド・subagent・plugin・MCP サーバ・auto memory・CLAUDE.md の自動探索を省略して起動時間を短縮できる。
理由は速度ではなく再現性: 同僚の ~/.claude の hook やプロジェクトの .mcp.json が走らないので、どのマシンでも同じ結果になる。逆に --bare を付けなければ、一度も信頼していないフォルダでも、プロジェクトの .claude/settings.json の hook が走り .mcp.json のサーバに接続する —— -p には workspace trust のダイアログもサーバごとの承認プロンプトも出ない（headless）。
認証の注意: 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段階で
- Claude.ai で実装・UX・エッジケース・トレードオフを検討
- 「step-by-step の実装プロンプトにまとめて」と頼む
- Claude Code に渡し、「1ステップずつやって」と指示
チームで使い方を見せ合う — 自分では気づかない使い方が広がる。
effort と費用の回し方
effort は検証とエッジケースの試験、自分の判断をどれだけ使うかを変えるので、隠れたエッジケースの多い作業ほど効き、取り組み方の誤りは直さない（spending-your-effort）。著者の機能開発のループは「仕様を渡してインタビューさせる → low で実装 → 要点を確認 → high で検証」。
費用の側から見ても順序は同じで、effort を上げる前に、モデルに自分の作業を確かめる手段（テスト、ビルド、エンドポイントを叩くスクリプト）があるかを確かめる —— テストは1ターン分、effort はすべてのターンに thinking を足す（what-a-task-costs-on-opus-5-5）。タスクの値段はトークン単価よりターン数とキャッシュの割合で決まり、API キーで Claude Code を使うとキャッシュは既定で5分なので、6分の休憩で次の読み取りが書き込みに変わる。/compact はキャッシュが温かいうちに、休憩の前に。
Opus 5.5 では完了の条件を言って丸ごと任せ、「よく考えて」を消し、どこで止まって聞くかを CLAUDE.md に書く。続けさせる規則は止まる回数を減らすので、破壊的な操作の前の確認と permission の確認は残す（getting-the-most-out-of-opus-5-5）。
自分専用の UI と見張りは mod で
status line や hook では足りない、ペイン・帯・独自コマンド・イベントの書き換えが欲しくなったら mod。API を覚えなくても、見たいものを説明すれば Claude が書き、hot reload で即座に動く（getting-started-with-claude-code-mods、mods-create）。Claude が書いた mod は承認するまで動かず、作ったセッションでしか読まれないので、残すならフォルダをコピーして --plugin-dir か marketplace で読む。
11. 日々のチェックリスト
作業を始める前
| 見るもの | 打つ手 |
|---|---|
| 無関係な前の作業が残っていないか | /clear |
| 複雑なら plan mode から | ⏸ plan mode on が出るまで Shift+Tab |
| 検証手段を渡したか | テストケース、スクショ、期待出力 |
作業中
| 気づいたこと | 打つ手 |
|---|---|
| 方向が違う | Esc で止める / 訂正を打つ |
| 複雑にしすぎている | 「Try something simpler」 |
| 同じ訂正が2回目 | CLAUDE.md に書く |
作業の後
| 起きたこと | 次に効かせる形 |
|---|---|
| 調査で context が膨らんだ | 次は subagent に回す |
| 同じ手順を3回貼った | skill にする |
| 毎回必ず起きてほしい | hook にする |
ときどき
/contextと/usageで消費を見るCLAUDE.mdが 200行を超えていないか（/doctorが trim を提案する）- 使っていない MCP サーバを
/mcpで無効化