Claude Codeの運用で最初に知っておきたい9のこと — 読み込み・hook・sandbox・worktree

このTipsでできること

Claude Codeを3ヶ月ほど本格運用すると、「最初にこれを知っていれば回り道しなかった」と感じやすい場面が9つあります。感覚だけで書くと「個人の好み」で終わるので、各項目を公式の仕様に当てて、なぜそう動くのか、どこまでが仕様でどこからが運用の工夫なのかを分けています。

対象は、導入を検討している人と、使い始めて1ヶ月ほどの人です。コマンドと設定の例はv2.1.287の挙動に基づきます。

9のこと

1. CLAUDE.mdは最初に書く価値が大きい

CLAUDE.mdは、毎セッションの冒頭で読み込まれる文脈です。コミット規約やテストコマンドを毎回伝える手間は、書いた時点から消えます。

ただし、強制される設定ではありません。守らせる強さは書き方で変わり、具体的で短い指示ほど従われやすくなります。目安は1ファイル200行未満で、長くなると文脈を食って遵守率が下がります。

# コミット
- メッセージは日本語、`fix:` `add:` などのプレフィックスを付ける
 
# テスト
- 変更後は `npm test` を実行し、失敗したままコミットしない

複数の手順にまたがる作業や、特定のディレクトリでしか関係しない指示は、CLAUDE.mdではなくskillやパス限定ルールに回します。「毎回必要な事実」だけを置く場所と割り切ると、肥大しません。

自動メモリーの MEMORY.md にも似た上限があり、読み込まれるのは先頭200行または25KBまでです。それ以降は、次のセッションで落ちます。

そして「書いても守られないことがある」という性質が、次の項目につながります。止めたい操作は、CLAUDE.mdではなくhookで止めます。

2. Hookは「1つから始める」が王道

PostToolUse に整形コマンドを1本だけ置く構成が、最初の一歩として扱いやすい形です。PostToolUse はツール呼び出しが成功した後に走ります。失敗した呼び出しは PostToolUseFailure が別に受けるので、整形のような後処理は成功した編集にだけ掛かります。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

いきなり5つ入れると壊れ方が見えなくなります。commandフックの既定タイムアウトは600秒で、止まったフックはその間セッションを待たせます。UserPromptSubmit は、毎回のプロンプトの前に走ってモデルの処理を止めるので、既定が30秒に短縮されています。

3. Skillsは「自分が同じ依頼を3回繰り返したら」作る

Skillを作る基準は「同じ依頼を3回した」です。1度や2度の依頼でSkill化すると、テンプレ化の手間が回収できません。3回目に「これはパターンになる」と気づいたときが、作りどきです。

Skillは、呼び出したときか、Claudeが関連すると判断したときに読み込まれます。常に文脈に載るCLAUDE.mdとは性質が違うので、手順書の置き場所に向いています。

見落としやすい仕様が2つあります。一覧に載る description と when_to_use の合計は1,536文字で切られるため、主な用途は先頭に書きます。もう1つは、デプロイのように人が実行を決めたい作業です。frontmatterに disable-model-invocation: true を付けると、Claudeが自分では起動しなくなります。

---
name: release-notes
description: リリースノートの下書きを作る。コミット履歴から変更点を拾うときに使う
disable-model-invocation: true
---

4. サブエージェントは「contextを温存する」のが本質的価値

サブエージェントは並列化(時短)で説明されがちです。運用で効いてくるのは、「contextを温存する効果のほうが大きい」という点です。重い調査をメインで直接やると、読んだファイルがすべてcontextに積まれて、後の作業が劣化します。サブエージェントは自分のcontext windowで動き、メインに戻るのは要約だけです。

仕様上の注意が2点あります。サブエージェントは、メインの会話履歴と自動メモリーを持たずに始まります。CLAUDE.mdとMCP・skillの設定は読み込むので、依頼文には「何を調べ、何を返してほしいか」を単体で通じる形で書きます。

もう1つは、サブエージェントも自分のリクエストを送り、使用量上限はメインと同じ枠で数えられる点です。温存できるのはcontextであって、利用枠ではありません。

ツール名にも変遷があります。以前の Task ツールはv2.1.63で Agent に改名されましたが、設定やエージェント定義の Task(...) は別名として今も通ります。詳細はサブエージェント完全活用にあります。

5. /clear は「劣化を感じてから」より「フェーズ切れ目」で

応答が劣化したと感じてから /clear するのでは遅い。フェーズが切り替わるとき(調査終了、実装完了、レビュー開始)に、計画的に /clear します。直前の状態はgit logと作業メモファイルで引き継ぎます。同じ件で2回を超えて(3回目以降)訂正したときも同じで、失敗した試行がcontextに溜まっているため、学んだことを入れた具体的な指示で新しく始めたほうが早く片づきます。

/clear と /compact は、混同しやすい別物です。

/compact には落とし穴があります。パス限定ルールと、サブディレクトリのCLAUDE.mdは、対象ファイルを読んだときに会話履歴へ読み込まれるため、要約で消えます。該当ファイルをもう一度読めば再び読み込まれます。圧縮をまたいで効かせたい指示は、プロジェクト直下のCLAUDE.mdに置きます。

長時間運用で応答劣化を防ぐ具体策は、セッションを快適に保つ5つの習慣にまとめています。

6. AIにレビューさせる構造的価値は「独立した目」

実装エージェントにセルフレビューさせるより、別のサブエージェントで立てたレビュアーに見せるほうが見落としが減ります。別セッションは異なるcontextで見るので、自分が書いたコードに引きずられません。公式のベストプラクティスにもWriter/Reviewerの二役に分ける型があり、人間のpair reviewと同じ発想です。

注意点は、レビュアー側が会話履歴を持たない点です(項目4)。何を基準に見るのかが文面に無いと、一般論の指摘しか返りません。判定基準まで明示するレビュー型プロンプトの構造パターンを併せて押さえると、見落としがさらに減ります。

7. 危険コマンドのブロックは「ブラックリスト」より「sandbox」が堅い

PreToolUse Hookや権限ルールで rm -rf を止める発想は分かりやすいものの、バイパスの余地が常に残ります。権限の解説も、引数を絞るBashルールは壊れやすいと警告しています。たとえば Bash(curl http://github.com/ *) は、プロトコルや引数の並びを変えた呼び出しに一致しません。denyルールも、同じプログラムを絶対パスで呼んだ場合や sh -c の中では一致しません。

sandboxにも範囲の限界があります。囲むのはシェルコマンドだけで、Claudeのファイルツール、MCPサーバー、hookはその外側で動きます。したがって「sandboxを入れたから権限ルールは不要」にはなりません。コンテナやVMまで含めて境界を強くしたいときは、DevContainer / Docker sandboxを使う選択肢があります。詳細はDevContainer / Sandbox完全実装にあります。

8. Worktreeは「個人開発でも価値がある」

「Worktreeはチーム開発の機能」と思われがちですが、個人開発でも「リファクタを別worktreeで試す」用途で使えます。本流を止めずに実験できる安心感は、大きな試行をする段階で効いてくる典型機能です。

起動はフラグ1つです。claude --help の出力(v2.1.287、抜粋)は次のとおりです。

claude --help
#   -w, --worktree [name]   Create a new git worktree for this
#                           session (optionally specify a name)
#   --tmux                  Create a tmux session for the worktree
#                           (requires --worktree).

名前を付けて起動すると、リポジトリ直下の .claude/worktrees/<名前>/ に、worktree-<名前> という新しいブランチでチェックアウトされます。.claude/worktrees/ は .gitignore に入れておかないと、メインの作業ツリーで未追跡ファイルとして見えます。

作りたてのworktreeは、gitで管理されたファイルだけのまっさらなチェックアウトです。依存関係のインストールは、worktreeごとにやり直します。.env のようなgit管理外のファイルを毎回持ち込みたいときは、.worktreeinclude ファイルに書いておきます。

終了時、作業が残っていればClaudeが残すか消すかを尋ねます。残した場合は、終了時に表示される claude --worktree <名前> --resume で戻れます。消すと、ディレクトリとブランチが作業ごと消えます。サブエージェントを並列に走らせるときは、サブエージェントの定義に isolation: worktree を書くと、それぞれ別のworktreeで動きます。

9. Auto-merge botは「人間の眠っている時間」を活かす

個人運営や小チームでauto-merge botを入れると、非同期性が出ます。夜間や週末に自動実行されたタスクが、朝にはマージ済みになります。CIゲートをすべて通ったPRだけを自動マージする設計にすると、品質を保ちながら稼働時間を実質24時間にできます。

ここはClaude Codeの機能ではなく、GitHub側の設計です。Claude Code GitHub Actionsは、PRやissueの @claude メンションに応じて分析・実装・コミットのpushを行います。任意のGitHubイベントにプロンプトを渡して、自動実行もできます。マージを止めるのは、リポジトリのブランチ保護で必須にしたチェックです。Claudeが書いたPRも、人間のPRと同じゲートを通る構成にしておくと、止める基準が1か所に集まります。

9知見の体系化

効き始めるまでの時間で並べ直すと、次のようになります。

まとめ

Claude Codeは、使い始めの1ヶ月で大体の機能に触れられます。使い方が固まるのは、「守らせたいことはCLAUDE.md、止めたいことはhookとsandbox、重い調査はサブエージェント」と役割を分け終えた頃です。

学ぶ順序はClaudeを学ぶ1週間ロードマップが参考になります。業務導入の進め方は業務導入9ステップチェックリストにあります。