Claude Code セットアップフック

エンジニアリングチームの質は1つの数字に表れる。新入社員がプロジェクトを自分のマシンで動かすまでにかかる時間だ。

優れたチームはリンク1つ、ドキュメント1つ、数コマンドで済む。多くのチームは1〜2日をペアプログラミング、Slackのスレッド、古くなったWikiページ、そして何かが壊れた原因の追求に費やす。

エージェントはこれを解決できる。

コードベースを立ち上げる方法には、常に3つの悪い選択肢があった:

純粋なスクリプトは予測可能だが脆弱だ。毎回同じコマンドを実行し、現実が変わった瞬間に止まる。依存関係が欠けていたり、データベースが落ちていたりすると、スクリプトはただ失敗する。

純粋なエージェントは賢いが信頼性に欠ける。CI/CDパイプラインに組み込んで、毎回まったく同じ出力を期待することはできない。

純粋なドキュメントは柔軟だが人に依存する。誰も読まないし、数週間で古くなる。

3つを組み合わせることがうまくいく。スクリプトが実行を担う。エージェントが監視する。結果として実行できるリビングドキュメントができあがる。

セットアップフックは2026年1月25日に Claude Code に追加された。セッションが起動する前に実行される専用のフック型だ。次のコマンドを実行すると:

claude --init

セットアップフックが先に動き、その後 Claude が起動する。フックはパッケージのインストール、データベースのシード、環境の準備を行う。Claude が起動する頃には、何が起きたかをすでに把握している。

ここで面白くなる。initフラグにプロンプトを追加できる:

claude --init "/install"

フックが動き、続いて /install コマンドが実行される。エージェントはログファイルを読み込み、何が起きたかを把握し、平易な言葉でレポートする。

claude --init "/install true"

これで3つのセットアップモードが使えるようになる:

┌─────────────────────────────────────────────────────────┐
│  DETERMINISTIC          AGENTIC           INTERACTIVE   │
│  (hooks only)           (hooks + prompt)  (hooks + Qs)  │
│                                                         │
│  claude --init          /install          /install true │
│                                                         │
│  - Fast                 - Supervised      - Asks Qs     │
│  - Predictable          - Diagnostic      - Adapts      │
│  - CI-friendly          - Reports status  - Context-    │
│                                             aware       │
└─────────────────────────────────────────────────────────┘

決定論的モード: スクリプトのみ。高速で再現性があり、すべての実行が一致する必要があるCI/CDに最適だ。

エージェントモード: スクリプトが先に動き、エージェントが結果を読み込む。ログファイルをスキャンし、エラーを解析し、何がうまくいったか・何が失敗したかを平易な言葉で伝える。

インタラクティブモード: スクリプトが先に動き、エージェントが短いQ&Aに引き込む。「新しいデータベースを作成しますか、それとも既存のものを維持しますか？フルインストールか最小インストールか？前提条件を先に確認しますか？」

スクリプトは常に信頼の源だ。フックとプロンプトは毎回同じスクリプトを呼ぶ。変わるのはエージェントが監視するかどうか、そして事前に質問するかどうかだ。

Just は小さなコマンドランナーで、セットアップフックとの相性が良い。エンジニアリング作業のランチャーとして使える。フラグを覚えなくても just と入力すれば利用可能なコマンドが一覧で見える:

just          # See all commands
just cldi     # Deterministic setup
just cldii    # Agentic setup (with reporting)
just cldit    # Interactive setup (asks questions)

justfile 自体はシンプルに保てる:

# Deterministic codebase setup
cldi:
  claude --init
 
# Agentic codebase setup
cldii:
  claude --init "/install"
 
# Interactive setup (asks questions)
cldit:
  claude --init "/install true"
 
# Deterministic maintenance
cldm:
  claude --maintenance
 
# Agentic maintenance (with reporting)
cldmm:
  claude --maintenance "/maintenance"

チームメンバーもエージェントも、フラグを二度覚える必要がない。just cldii を実行すれば動く。

シナリオ	モード	コマンド
CI/CDパイプライン	決定論的	`claude --init-only`
クイックなローカルセットアップ	決定論的	`just cldi`
セットアップ失敗、診断が必要	エージェント	`just cldii`
新人エンジニア、コードベースに不慣れ	インタラクティブ	`just cldit`
週次の依存関係アップデート	エージェント	`just cldmm`

--init-only はパイプライン用フラグだ。フックを実行し、終了コードを返し、シャットダウンする。インタラクティブなセッションは付かない。

オンボーディングこそこの仕組みが輝く場面だ。新人エンジニアが just cldit と入力すると、エージェントがガイドしてくれる:

Agent: How should I handle the database?

┌─ Database Setup ─────────────────────────────────┐
│  ○ Fresh database (Recommended)                  │
│  ○ Keep existing                                 │
│  ○ Skip database setup                           │
└──────────────────────────────────────────────────┘

エージェントはインストールモード、環境変数、前提条件の確認有無について質問する。回答に応じて処理を調整し、該当するステップだけを実行する。

スクリプトにはこれができない。スクリプトは毎回同じテープを再生するだけだ。エージェントは途中で止まり、確認の質問をして、答えに応じて分岐できる。

セットアップフックはフックシステムにある12のライフサイクルイベントのひとつだ。設定は .claude/settings.json に記述する:

{
  "hooks": {
    "Setup": [
      {
        "matcher": "init",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_init.py",
            "timeout": 120
          }
        ]
      },
      {
        "matcher": "maintenance",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/setup_maintenance.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

フックスクリプトはコマンドを実行し、全体をログに記録する:

def main():
    # Install backend dependencies
    run(["uv", "sync"], cwd="apps/backend")
 
    # Install frontend dependencies
    run(["npm", "install"], cwd="apps/frontend")
 
    # Initialize database
    run(["uv", "run", "python", "init_db.py"], cwd="apps/backend")
 
    # Tell Claude what happened
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "Setup",
            "additionalContext": "Setup complete. Run 'just be' and 'just fe' to start."
        }
    }))

/install スラッシュコマンドはログを読み込み、結果をまとめる:

---
description: Run setup and report installation results
---
 
## Workflow
 
1. Run /prime to understand the codebase
2. Read the log file at .claude/hooks/setup.init.log
3. Analyze for successes and failures
4. Write results to app_docs/install_results.md
5. Report to user

何かが壊れたとき、エージェントにはすでに診断に必要なコンテキストがある。プロンプト内によくある失敗パターンを記述しておけば、エージェントが自ら修正の手順を追っていく。

チームの成長ペースに合わせて、オンボーディング時間を考えてみてほしい。1つのプロンプトが新入社員のセットアップとインストールを担えるだろうか？行動する前に質問することで各ステップを明確にできるだろうか？

どちらも「できる」だ。エージェントはそれに十分な水準にある。不足しているのは標準化だ。

決定論を保持: フックは毎回同じスクリプトを実行する。実行中のLLMのばらつきはゼロだ。エージェントが結果を確認するのは、決定論的な作業が完了した後だけだ。

CIと互換: GitHub Actions は claude --init-only を実行してクリーンな終了コードを受け取る。

必要なときだけインタラクティブ: 新入社員はセットアップを案内してもらえる。他の人は高速バージョンを実行する。

実行できるリビングドキュメント: インストールプロセスが自然言語でプロンプトに記述され、エージェントがそれに従う。更新はプロンプトを編集するだけで完了する。

シンプルに始めよう。依存関係をインストールする .claude/hooks/setup_init.py スクリプトを書き、.claude/settings.json に組み込み、ログを読んでレポートする /install コマンドを追加する。これ全体を justfile でラップすれば、チームが just install を実行するだけで済むようになる。

もっとシンプルなものが欲しい場合は、セッションタイプごとに異なるコンテキストを読み込みたいだけなら、スラッシュコマンドで十分なことが多い。インストールスクリプトは不要だ。

セットアップフックが最も効果を発揮するのは、環境を丸ごとインストールし、失敗を診断し、新入エンジニアを各ステップにガイドする1つのコマンドが欲しいときだ。スクリプトが確実性を提供し、エージェントが判断を提供する。チームがWindows、Linux、macOSを行き来する場合は、クロスプラットフォームのフックパターンを読んで、同じセットアップがすべてのOSで動くようにしてほしい。

Claude Code セットアップフック

On this page