Sonub Lab — Claude Code 実習

どんなものか

Claude Code は Anthropic が作ったエージェント型コーディングツール(agentic coding tool)です。やりたいことを言葉で頼むと、ファイルを読み、コードを直し、コマンドを実行します。その前に許可を求めます。ターミナルで動き、VS Code・JetBrains などのコードエディター、Claude デスクトップアプリ、ウェブでも使えます。

変更する前に計画を見せることができ、ファイルを編集したりコマンドを実行したりする前に許可を求めます。何をしてよいかは自分で決めます(権限)。プロジェクトのルールは CLAUDE.md に書いておけば、セッションの始めに毎回読みます。

必要なもの

• アカウント：Claude Pro・Max・Team・Enterprise プラン、または Console(API)アカウント。無料の claude.ai プランには Claude Code は含まれません。
• コンピューター：macOS 13 以上、Windows 10(1809)以上、Ubuntu 20.04 または Debian 10 以上、メモリー 4 GB 以上、インターネット接続。
• 作業するプロジェクトのフォルダー — すべての変更を見直して元に戻せるよう、Git リポジトリが理想です。

インストール

macOS・Linux・WSL では 1 行目を、Windows では PowerShell の行を実行してください。この方法でインストールすると、バックグラウンドで自動的に更新されます。Homebrew や WinGet でインストールした場合は自動では更新されません。

macOS · Linux · WSL

curl -fsSL https://claude.ai/install.sh | bash コピー

Windows PowerShell

irm https://claude.ai/install.ps1 | iex コピー

Homebrew

brew install --cask claude-code コピー

WinGet

winget install Anthropic.ClaudeCode コピー

npm (Node.js 22+)

npm install -g @anthropic-ai/claude-code コピー

インストールを確かめる

新しいターミナルウィンドウを開きます。claude --version でバージョン番号が表示され、claude doctor でインストールの状態がわかります。“command not found” と出たら、ターミナルを開き直して PATH を確認してください。

最初の実行 — 5 つのステップ

1. ターミナルを開き、cd <フォルダー> でプロジェクトのフォルダーに入ってから claude と入力して Enter を押します(デスクトップアプリではなく、ターミナルのツールが起動します)。初回はブラウザーが開いてログインします。
2. 「このプロジェクトには何がある?」と聞いて、プロジェクトを読ませます。
3. /init で CLAUDE.md を作り、テストのコマンドと守るべきルールを書き足します。
4. Shift+Tab でプランモードに切り替えて変更を頼みます。計画を読んで直し、承認します。
5. git diff で変わったところを読み、テストを自分で実行してからコミットします。

基礎の練習 — 最初から一度やってみる

1. 練習用フォルダーを作り(mkdir hello-ai && cd hello-ai)、git init で Git リポジトリにしてから claude を実行します。入力欄が見えれば成功です。
2. 「今日の日付を表示する 1 ページの Web ページ index.html を作って」と頼みます。ファイルを作る前に確認されたら、何をするかを読んで許可します。
3. できた index.html をブラウザーで開き、日付が表示されるか自分の目で確かめます。
4. git status で何が変わったかを見て、git add . と git commit -m "first page" で保存します。
5. もう一度「日付の文字を大きくして」と頼みます。結果が気に入らなければ git restore index.html で最後のコミットの状態に戻します。

困ったら: claude が起動しなければ claude doctor でインストールを確認し、ログイン画面が開かなければターミナルを閉じて開き直し、もう一度 claude を実行します。5 つとも終わりましたか? [中級] タブに進みましょう。

SONUB でもっと学ぶ

• Claude Code 1: プロジェクトを準備し、ずっと効く指示を与える
• Claude Code 2: 計画し、変更し、テストし、レビューする
• エージェントとサブエージェント: AIが一歩ずつ働くしくみ
• ゴールとRalph Loop: 本当に終わるまでエージェントに続けさせる
• claude-skill エージェントスキル — Claude Code を順を追って学び、新機能についていく

公式ドキュメント

• Claude Code — Overview
• Claude Code — Advanced setup
• Claude Code — Quickstart
• Claude Code — Common workflows
• Claude Code — Use Claude Code with Chrome

2026-10-19 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。

モデルと effort — どれを使う?(おすすめ: Opus 5.5、High)

2026年11月時点では、開発には Opus 5.5 を High の水準で使いましょう。標準の水準は medium なので、下のように設定するか、/model opus と /effort high を実行します。すべてのモデルと考える水準、いつ下げていつ上げるかは、ツールマスターの「おすすめの使い方」にあります。

{
  "model": "opus",
  "effortLevel": "high"
}

claude --model opus --effort high

# inside Claude Code
/model opus
/effort high

• おすすめのモデル ― ツールマスター

CLAUDE.md — セッションごとに読むプロジェクトの指示

CLAUDE.md は、Claude Code がセッションを始めるたびに読む Markdown ファイルです。毎回くり返し言うのが面倒なこと — ビルドやテストのコマンド、コードのルール、してはいけないこと — を書いておきます。/init を実行すると、プロジェクトを読んで最初の CLAUDE.md を書いてくれます。いくつかの場所にある CLAUDE.md は互いに上書きせず、すべて一緒に読まれます。

• ~/.claude/CLAUDE.md — すべてのプロジェクトで使う自分の指示
• ./CLAUDE.md または ./.claude/CLAUDE.md — チームで共有するプロジェクトの指示(Git にコミット)
• ./CLAUDE.local.md — このプロジェクトで自分だけが使う指示(.gitignore に入れます)。ただし、一つでもあると AGENTS.md は読まれません
• サブフォルダーの CLAUDE.md — Claude がそのフォルダーのファイルを読んだり編集したりするときにも読まれます。.claude/rules/ のルールファイルは paths で特定のファイルだけに適用できます

# My App

## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint

## Rules
- TypeScript strict mode. Do not use `any`.
- Put new API routes in src/routes/.
- Never edit files in vendor/.
- Run the tests before you say a task is done.

@docs/architecture.md

短く書きましょう(公式ドキュメントは 200 行以内をすすめています)。毎回読まれるので、長いファイルは場所をとり、大事なルールが埋もれてしまいます。/memory で読み込まれた指示ファイルを見て編集でき、@path(例: @docs/architecture.md)で別のファイルを取り込めます。いくつもの AI を一緒に使うなら、プロジェクトには CLAUDE.md ではなく AGENTS.md だけを置くのがいちばんです — すぐ下の節を見てください。

AGENTS.md だけを使う — すべての AI が同じ指示で働くように

なぜこうするのでしょう? 一つのプロジェクトで Claude Code と一緒に Codex・Cursor・Gemini などの別の AI も使うと、ツールごとに別々の指示ファイルはすぐに内容がずれていきます。AGENTS.md は多くのコーディングエージェントが読む公開フォーマットです。ルールを AGENTS.md に一度だけ書けば、どの AI で作業しても同じ指示に従います。下の方法はまさにそのため — 一つのプロジェクトで、たくさんの AI が AGENTS.md を通して同じ指示を使うためのものです。

Claude Code も AGENTS.md を直接読めます(v2.1.277 以降)が、CLAUDE.md とまったく同じではありません。

• 初期設定では、作業フォルダーやその上のどのフォルダーにも CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md がないときだけ AGENTS.md を読みます。個人メモ用に CLAUDE.local.md を一つ足しただけで、AGENTS.md は読まれなくなります(~/.claude/CLAUDE.md と .claude/rules/ はここでは数えません)。
• サブフォルダーの AGENTS.md は、Claude が Read ツールでそこのファイルを開いたときだけ読まれます。そのフォルダーに新しいファイルを直接書くときは、まだルールを知らないことがあります。サブフォルダーの CLAUDE.md は読むとき・書くとき・編集するときに読まれます。
• AGENTS.local.md・AGENTS.override.md・.agents/ フォルダーの中のファイルは読まれず、--add-dir で追加したフォルダーの AGENTS.md も読まれません。

いちばん良いのは、プロジェクトフォルダーでは CLAUDE.md をまったく使わず、AGENTS.md だけを使うことです。そうすれば、自分のグローバルな指示である ~/.claude/CLAUDE.md はこれまでどおり初期設定で読まれ、プロジェクトフォルダーでは AGENTS.md が使われます。Codex などの別の AI も同じ AGENTS.md を読むので、ルールを直すのは AGENTS.md の一か所だけです。

ただし、プロジェクトフォルダー・今のフォルダー・上のフォルダー・サブフォルダーのどこか一か所でも CLAUDE.md を使うなら、必ずすべてのフォルダーで CLAUDE.md を使わなければなりません。作業フォルダーやその上に CLAUDE.md が一つでもあると Claude Code は AGENTS.md を読まないので、混ぜて使うと、あるフォルダーのルールは読まれ、別のフォルダーのルールは抜け落ちます。その場合でも AGENTS.md を使いたいなら、各 CLAUDE.md に @AGENTS.md の 1 行を足すだけです。@path はその場所にファイルの内容を取り込む書き方で、公式ドキュメントによると、この取り込みで Claude が AGENTS.md を二度読むことはありません。

1. 共通のルール(インストールとテストのコマンド、コードのルール、してはいけないこと)をプロジェクトの一番上の AGENTS.md に書きます。Codex の /init で作ることもできます。
2. プロジェクトの中(今のフォルダー・上のフォルダー・サブフォルダーのどこにも)に CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md を作りません。
3. すべてのプロジェクトで使う自分の個人的な指示は ~/.claude/CLAUDE.md に置きます — AGENTS.md と一緒にいつも読まれます。
4. サブフォルダーに独自のルールがあるなら(例: api/)、そこにも AGENTS.md を置きます。
5. Claude Code で /memory を開き、AGENTS.md が読み込まれたか確かめます。CLAUDE.md を使うことにしたなら、すべてのフォルダーの CLAUDE.md に @AGENTS.md の 1 行があるかも確かめます。

~/.claude/CLAUDE.md    ← your personal rules (still loaded by default)

my-project/
├── AGENTS.md          ← shared rules for every AI (Claude Code, Codex, Cursor, Gemini …)
└── api/
    └── AGENTS.md      ← rules only for api/

(no CLAUDE.md anywhere in the project)

my-project/
├── AGENTS.md
├── CLAUDE.md          ← @AGENTS.md
└── api/
    ├── AGENTS.md
    └── CLAUDE.md      ← @AGENTS.md

@AGENTS.md

知っておきたいことと、ほかの方法。① AGENTS.md だけを使うとき、サブフォルダーの AGENTS.md は Claude がそのフォルダーのファイルを Read で開いたときに読まれます。② /config で Project instructions を claude-md-and-agents-md にすると、各フォルダーの AGENTS.md がその CLAUDE.md のすぐ後に読まれます。③ シンボリックリンク(ln -s AGENTS.md CLAUDE.md)でもできますが、Windows が混じるなら @AGENTS.md の 1 行のほうが安全です。

• Codex が AGENTS.md を読む順番 — Codex 中級

権限とモード — 聞かずにしてよいことを決める

Claude Code はファイルを編集したりコマンドを実行したりする前に確認を求めます。同じことを毎回承認するのが面倒なら、それをルールにし、作業に合わせてモードを切り替えましょう。

• Shift+Tab — モードを切り替える: default(毎回聞く)→ acceptEdits(ファイル編集は聞かない)→ plan(読むだけで計画を見せる)。auto モードで始めた場合は、最初に押すと default になります。
• /permissions — allow・ask・deny のルールと、それぞれがどのファイルから来たかを見て編集します。
• .claude/settings.json はチームで共有するルール(コミットする)、.claude/settings.local.json は自分だけが使うルール、~/.claude/settings.json はすべてのプロジェクトのルールです。
• ルールは deny → ask → allow の順に確かめられます。どこかで deny されたものはほかの場所で許可できないので、.env のような秘密のファイルは deny でふさぎましょう。

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

bypassPermissions(--dangerously-skip-permissions)はすべての確認をオフにします。インターネットにつながらないコンテナーや仮想マシンのように、壊れても困らない場所でだけ使ってください。

コンテキストの管理 — 会話が長くなったら

Claude が一度に見られる量(コンテキストウィンドウ)は決まっています。会話、読んだファイル、コマンドの出力がすべてそこにたまり、いっぱいになると前の部分が要約されます。長くなるほど前の指示がぼやけるので、整理する習慣をつけましょう。

• /context — 何がコンテキストをどれだけ使っているかを、色付きのブロックで見ます。
• /compact — これまでの会話を要約して空きを作ります。残してほしいことも伝えられます(例: /compact focus on the login bug fix)。
• /clear — 関係のない作業を始めるときは、新しい会話にします。
• claude -c はこのフォルダーの最後の会話を続け、claude -r または /resume は前の会話を選んで続けます。
• Esc を 2 回(または /rewind)— チェックポイントの一覧から前の時点を選び、会話とコードを巻き戻します。Bash で削除・移動したファイルは戻らないので、Git のコミットの代わりにはなりません。

一つの会話に一つの作業。作業が変わったら /clear で新しく始めるのが、いちばん簡単な整理です。

コンテキストを節約 — SONUB の基準：約 400k で自動要約、基本コンテキストは 6% 以下

Claude は頼まれるたびに今のコンテキスト全体を読み直します。コンテキストが大きいほど 1 回の依頼にかかるトークンが増えます。そこで auto compact(自動要約)で、1M まるごとではなく約 400k トークンで作業し、会話を始める前から場所を取る基本コンテキスト(基本のシステムプロンプト・スキル・MCP など)を 6% 以下に保ちます。こうすると使用量を大きく減らせます。 約 400k・6% は SONUB が決めた目安で、公式の推奨値ではありません — 公式ドキュメントは設定方法だけを説明しています。

• /autocompact 444k — コンテキストが 444k トークンに達したら自動で要約します。今のモデルのユーザー設定に保存され、/autocompact auto で元に戻します。
• すべてのモデルに使うなら ~/.claude/settings.json に "autoCompactWindow": 444000 を入れます(下の例)。1 回だけなら claude --autocompact 444k で起動します。
• 新しい会話を開いたらすぐ /context を見ます。まだ何も頼んでいないのに取られている分 — システムプロンプト・システムツール・MCP ツール・スキル・メモリファイル(CLAUDE.md・AGENTS.md)— が基本コンテキストで、合計 6% 以下にします。
• 6% を超えたら減らします — 使わない MCP サーバーは /mcp で切り、使わないスキル・プラグインは消し、CLAUDE.md・AGENTS.md には本当に必要なルールだけ残します。

{
  "autoCompactWindow": 444000
}

基本コンテキストは依頼のたびに一緒に送られるので、数 % 減らすだけでも会話全体で積み重なり、使用量が大きく減ります。要約される前でも、仕事が変わったら /clear で新しく始めるのがいちばんの節約です。

• ツールのコンテキスト ― 1M ではなく約 400k

上手な頼み方 — どこで・何を・どう確かめるか

よい頼み方には 3 つの部分があります。どこで(ファイルとフォルダー)、何を(望む動き)、どう確かめるか(テスト・コマンド・画面)。この 3 つがはっきりしているほど、Claude は迷わず、自分の結果をよく確かめます。

• あいまいな頼み方:「ログインを直して」
• はっきりした頼み方:「@app/Http/Controllers/LoginController.php で、パスワードが違うと 500 エラーになります。エラーメッセージ付きで 422 を返すようにし、tests/Feature/LoginTest.php にテストを足して、通ることを確かめてください。」

• @ を入力するとファイルを選んで頼みごとに添付できます(@src/login.ts)。
• エラー画面やデザインの見本は、スクリーンショットを貼り付けるかドラッグして入れます。
• 大きな作業は「まず読んで計画だけ見せて — まだ何も変えないで」から始めるか、/plan でプランモードに入ります。
• 難しい問題は /model でモデルと effort のレベルを上げるか、頼みごとに ultrathink を入れると、そのターンだけ深く考えます。
• /goal <ゴールライン> — 次の依頼がなくても、それを満たすまでClaudeがターンを続けて働きます(例: /goal tests/ のテストがすべて通る, or stop after 20 turns)。/goal だけで状態を見て、/goal clear で消します。

ベストプラクティス — Anthropic がすすめる Claude Code の使い方

要点は ― Claude が自分で確かめる方法を渡し、難しい作業は先に計画し、具体的に頼み、CLAUDE.md は短く保ち、作業の合間にコンテキストを空にします。2つの公式ガイドにある6つの良い習慣と、Claude Code・Codex のコマンドは「おすすめの使い方」にあります。

• 6つの良い習慣 ― ツールマスター

よくある失敗 — 直し方

公式ガイドは5つの失敗パターンを警告しています ― 何でも詰め込んだセッション、何度も直し続けること、長すぎる CLAUDE.md、確認せずに信じること、終わらない調べもの。2つのガイドにある10個のよくある失敗と直し方は「おすすめの使い方」にあります。

• よくある10個の失敗 ― ツールマスター

中級の練習 — 自分のプロジェクトでやってみる

1. プロジェクトの一番上にテストコマンドと 3 つのルールを書いた AGENTS.md を作り、プロジェクトに CLAUDE.md がないことを確かめます。
2. /memory を開き、AGENTS.md と ~/.claude/CLAUDE.md が読み込まれたか確かめます。
3. .claude/settings.json でテストコマンドを一つ allow し、.env を deny して、/permissions で確かめます。
4. プランモードで小さな機能を一つ頼み、計画を読んで直してから承認します。
5. /context で使用量を見て、/compact で減らし、もう一度見ます。

5 つとも終わりましたか? [上級] タブに進みましょう。

公式ドキュメント

• Use Claude Code with Chrome
• Memory — CLAUDE.md · AGENTS.md
• Permissions
• Settings
• Checkpointing
• Model configuration — auto-compact window
• Best practices
• Best practices — common failure patterns

2026-10-19 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。

エージェントスキル — くり返す作業を教える

スキルは SKILL.md が入ったフォルダーです。ふだん Claude は各スキルの名前と説明だけを知っていて、作業が説明に合うと本文を読んでそのとおりにします。だからスキルがたくさんあってもほとんど場所をとりません。以前のカスタムコマンド(.claude/commands/)は今はスキルに統合されました。

• .claude/skills/<名前>/SKILL.md はこのプロジェクト用、~/.claude/skills/<名前>/SKILL.md はすべてのプロジェクト用です。
• description に、何をするのか、いつ使うのかをはっきり書くと、Claude が自分で選びます。
• /<スキル名> で直接呼ぶこともでき、/skills で一覧が見られます。
• スクリプトや参考ドキュメントは同じフォルダーに置き、SKILL.md から案内します。SKILL.md は 500 行以内に短く保ちます。

---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes, a changelog or "what changed since the last tag".
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed.
4. Write plain sentences a user can understand. Skip internal refactors.

• エージェントスキルを学ぶ — 作る・インストールする・SONUB のスキル

スキルは公開された標準 — でも Claude Code は独自のやり方で動く

スキルは Claude を作った会社 Anthropic が最初に作り、無料で公開しました。今は Agent Skills という公開された標準として agentskills.io で管理されています。Codex・Cursor・Gemini CLI・GitHub Copilot など多くの AI ツールが同じ SKILL.md フォルダーを読みます。

ただし注意してください。標準が決めているのはスキルフォルダーの中に何を入れるかだけです。スキルをどこで探すか、名前が重なったときにどれを使うかはツールごとに任されていて、Claude Code は agentskills.io がすすめる方法とは違う動きをします。そのため、別のツールでうまく動いたスキルが Claude Code では違う動きをすることがあります。

• フォルダー: agentskills.io は多くのツールが共有する .agents/skills/ をすすめていますが、Claude Code が読むのは .claude/skills/(プロジェクト)と ~/.claude/skills/(個人)です。.agents/skills/ は読みません。
• 同じ名前のとき: 標準の一般的なルールでは、プロジェクトのスキルが個人のスキルに勝ちます。Claude Code では逆です — エンタープライズが個人に勝ち、個人(~/.claude/skills/)がプロジェクトに勝ちます。
• 親フォルダーと子フォルダー: 標準は決めていません。Claude Code は起動したフォルダーと、その上の git リポジトリのルートまでのすべての親フォルダーを読みます。子フォルダーはそこで作業するときだけ読みます(次の節)。
• frontmatter: 標準のフィールドは name・description・license・compatibility・metadata・allowed-tools の 6 つです。Claude Code は disable-model-invocation・context: fork・paths などのフィールドを追加しています。ほかのツールはこれらを無視し、claude.ai へのアップロードと Skills API はエラーで止まります。

ほかの AI ツールと共有するスキルは、frontmatter を標準の 6 つのフィールドだけで書きましょう。そうすれば Claude Code でもほかのツールでも、変更なしでそのまま読み込まれます。

Claude Code がスキルを探す場所 — 今のフォルダーと親フォルダーをいっしょに

今いるフォルダーに .claude/skills フォルダーがあり、親フォルダーにもあれば、Claude Code は両方のスキルをいっしょに使います。上へさかのぼるのは git リポジトリのルートまでです。

• claude を起動したフォルダーと、リポジトリのルートまでのすべての親フォルダーの .claude/skills/ を読みます。apps/web/ で起動しても、ルートのスキルもいっしょに使えます。
• リポジトリのルートより上にある .claude/skills/ は読みません。すべてのプロジェクトで使うスキルは ~/.claude/skills/ に置きましょう。git worktree では worktree のルートまでしかさかのぼりません。
• 起動したフォルダーより下のフォルダーにあるスキルは、最初は読まれません。Claude がそのフォルダーのファイルを初めて読むか編集したときに読み込まれ、セッションが終わるまで残ります — それまでは / メニューにも出ません。先に読み込むには、そのフォルダーを指定して /add-dir を実行します。
• ルートと apps/web/ の両方に deploy という名前のスキルがあれば、どちらも使えます。/deploy はルートのスキルを、/apps/web:deploy は子フォルダーのスキルを実行します。Claude には、作業中のファイルがあるフォルダーのスキルを使うよう指示が伝えられます。
• プラグインのスキルは /<プラグイン名>:<スキル名> として別に呼ばれるので、自分のスキルと重なることはありません。

~/projects/                    ← above the repository root
├── .claude/skills/            ← not loaded (put shared skills in ~/.claude/skills/)
└── repo/                      ← git repository root
    ├── .claude/skills/        ← loaded
    └── apps/web/              ← run claude here
        ├── .claude/skills/    ← loaded (used together with the root)
        └── src/
            └── .claude/skills/  ← not at start — loads when Claude first reads or edits a file in src/

repo/
├── .claude/skills/deploy/SKILL.md            → /deploy
└── apps/web/.claude/skills/deploy/SKILL.md   → /apps/web:deploy

今どのスキルが読み込まれているかは /skills で確認できます。親フォルダーと子フォルダーにスキルがたくさんあると、あまり使わないスキルから説明が削られていくので、ときどき /skill-doctor で確認しましょう。

サブエージェント — 作業の一部を任せる

サブエージェントは、自分専用のコンテキストウィンドウ・指示・ツールを持つ助っ人です。大きな検索やレビューを任せましょう。いくつファイルを読んでも、メインの会話には結果だけが戻るので、すっきりしたままです。

• .claude/agents/<名前>.md はプロジェクト用(コミットしてチームと共有)、~/.claude/agents/ は自分だけ用です。必須なのは name と description だけです。
• tools で使えるツールを絞るとより安全です — レビュー役には読むことだけを許しましょう。
• 「この変更を code-reviewer サブエージェントでレビューして」のように呼ぶか、description が合えば Claude が自分で任せます。
• 新しいサブエージェントを作るには、Claude に作ってと頼むか、上のフォルダーに自分でファイルを書きます。Explore や Plan のような組み込みのものは最初からあります。

---
name: code-reviewer
description: Reviews code changes for bugs, security problems and missing tests. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a careful senior reviewer.
Run `git diff` to see the changes, then report:
1. Bugs (with file and line)
2. Security problems
3. Missing tests
Do not edit files.

フック — 決まったタイミングで必ず動くコマンド

CLAUDE.md はお願いなので忘れられることもありますが、フックは Claude Code が決まったタイミングで必ず実行するシェルコマンドです。ファイル編集の後にフォーマッターを動かす、危険なコマンドや秘密のファイルの編集を止める、作業が終わったら通知を受ける、といったことにフックを使います。

• PreToolUse — ツールを使う前(止められる)、PostToolUse — ツールを使った後
• UserPromptSubmit — 頼みごとを送ったとき、Stop — Claude が答えを終えたとき、SessionStart — セッションが始まったとき、Notification — あなたの確認が必要なとき
• matcher で、フックをどのツールに適用するかを選びます(例: Edit|Write、Bash)。
• フックのコマンドが終了コード 2 で終わると、その動作は止められ、stderr に書いた理由が Claude に伝わります。
• /hooks で設定されているフックが見られます。上の例は、編集したファイルをすべて Prettier で整えます(jq が必要)。

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

フックはあなたのコンピューターで、あなたの権限で動きます。ほかの人のフックは、コマンドを読んで理解してから追加しましょう。

MCP — 外部ツールをつなぐ

MCP(Model Context Protocol)は、AI ツールが外部サービス(課題管理ツール、データベース、ブラウザー、ドキュメントツール)を使えるようにする公開標準です。MCP サーバーを追加すると、Claude はそのサーバーが提供するツールを使えます。

• claude mcp add --transport http <名前> <url> — インターネット上のリモートサーバーを追加します。
• claude mcp add <名前> -- <コマンド> — 自分のコンピューターで動くサーバー(stdio)を追加します。-- の後ろはすべてそのままサーバーに渡されます。
• --scope project で追加すると、リポジトリの一番上の .mcp.json に保存され、チームと共有されます(初めて使うときに承認を求められます)。
• /mcp で接続状態を見てログイン(OAuth)します。claude mcp list で一覧が見られます。

# A remote server (HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that runs on your computer (stdio)
claude mcp add playwright -- npx @playwright/mcp@latest

# Share it with the team — saved in .mcp.json
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

claude mcp list

信頼できる MCP サーバーだけを追加しましょう。外部の文章を取ってくるサーバーは、その文章に隠された指示を持ち込むことがあります(プロンプトインジェクション)。

ヘッドレス — チャット画面なしのスクリプト

claude -p "…" はチャット画面なしで一度だけ動き、結果を出力して終わります。シェルスクリプト・cron・CI の部品として Claude を使えます。

• パイプで入力を渡します(cat error.log | claude -p "…")。
• --output-format json は結果・セッション id・費用を JSON で返し、stream-json は進み具合を 1 行ずつ送ります。
• --allowedTools はこの実行で許すツールを、--max-turns は最大のターン数を決めます。
• claude -p --continue は前回の実行を続け、--resume <セッション id> はそのセッションを続けます。

# One question, one answer
claude -p "Explain what src/auth.ts does in 5 lines"

# Pipe input in
cat build-error.log | claude -p "Find the cause and suggest a fix"

# JSON output for scripts (result, session_id, total_cost_usd)
claude -p "List the TODO comments in src/" --output-format json

# Limit what it may do and how long it runs
claude -p "Run the tests and fix failures" \
  --allowedTools "Read,Edit,Bash(npm test *)" --max-turns 10

スクリプトでは --bare を付けると、CLAUDE.md・フック・プラグイン・MCP を読まずにすばやく始まります(公式ドキュメントによると、いずれ -p の初期設定になります)。プロジェクトの指示が必要なら付けないでください。

上級の練習

1. よくする作業を一つ(リリースノート、コミットメッセージ)を .claude/skills/ のスキルにして、/skill-name で呼びます。
2. 読むだけの code-reviewer サブエージェントを作り、今の変更をレビューさせます。
3. PostToolUse フックで、ファイルを編集するたびにフォーマッターかリンターが動くようにします。
4. MCP サーバーを一つ追加し、/mcp で接続を確かめます。
5. claude -p でエラーログを要約する 1 行のシェルスクリプトを書きます。

5 つとも終わりましたか? [マスター] タブに進みましょう。

公式ドキュメント

• Skills
• Subagents
• Hooks
• MCP
• Headless (-p)

2026-10-19 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。

Git worktree — いくつものセッションを同時に

二つのセッションが一つのフォルダーで同じファイルを編集すると、互いに上書きしてしまいます。git worktree は同じリポジトリを別のフォルダーに別のブランチで取り出すので、フォルダーごとに Claude を一つずつ動かし、いくつもの作業を同時に進められます。

• claude --worktree <名前>(-w)は .claude/worktrees/<名前>/ に worktree とブランチを作ってそこで始めます。変更なしで終えると自動で消されます。
• .claude/worktrees/ を .gitignore に入れ、.env のように Git が無視するファイルは .worktreeinclude に書いておくと、新しい worktree にコピーされます。
• worktree ごとに依存関係のインストール(npm install など)が必要なことがあります。
• 別々のファイルを触る独立した作業に分け、終わったら PR でマージします。

# Claude Code makes the worktree for you (.claude/worktrees/<name>/)
claude --worktree feature-login
claude -w bugfix-cart

# Or with plain git
git worktree add ../myapp-search -b feature-search
cd ../myapp-search && claude

git worktree list
git worktree remove ../myapp-search

GitHub Actions — issue と PR で @claude

Claude Code GitHub Actions をインストールすると、issue や PR のコメントに @claude と書くだけで、Claude がリポジトリを読んで直し、PR を作ったりレビューを残したりします。GitHub のランナーで動くので、自分のコンピューターは切っていてもかまいません。

1. ターミナルの Claude Code で /install-github-app を実行します。GitHub アプリのインストールとシークレット(ANTHROPIC_API_KEY または claude setup-token で作ったトークン)の追加を案内してくれます — gh とリポジトリの管理者権限が必要です。
2. 上のようなワークフローファイルが .github/workflows/ にできます。
3. issue や PR に「@claude このバグを直して」のようにコメントします。
4. Claude が作った PR は、人がレビューしてテストしてからマージします。

name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Actions の Claude も、リポジトリの指示ファイル(AGENTS.md、または CLAUDE.md)を読みます。ルールを守らせるいちばん簡単な方法は、よく書かれた指示ファイルです。

プラグインとマーケットプレイス — 設定をまとめて共有する

プラグインはスキル・サブエージェント・フック・MCP サーバーを一つにまとめたものです。マーケットプレイスはプラグインの一覧を持つリポジトリです。チームは一つのコマンドで同じ道具箱をインストールし、一緒に更新します。

• /plugin — プラグインを探す、インストールする、オン・オフにする。
• /plugin marketplace add <owner/repo> でマーケットプレイスを追加し、/plugin install <プラグイン>@<マーケットプレイス> でインストールします。
• プラグインフォルダーの .claude-plugin/ には plugin.json だけを入れます。skills/・agents/・hooks/ はフォルダーの一番上に置きます。claude --plugin-dir ./my-plugin でテストします。
• スキルだけを共有するなら npx skills add でもかまいません — SONUB のスキルはこの方法で共有しています。

my-plugin/
├── .claude-plugin/
│   └── plugin.json        ← name, description, version
├── skills/
│   └── release-notes/SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

/plugin marketplace add my-team/claude-plugins
/plugin install my-plugin@claude-plugins
/plugin

• SONUB のエージェントスキルをインストールする

チームの設定を運用する — ルールが増えてもはっきり保つ

一つのリポジトリでたくさんの人とたくさんの AI が働くと、設定はすぐに増えていきます。何を共有し何を個人にするか、何をお願いにし何を強制するかを決めましょう。

• 共有(コミットする): AGENTS.md、.claude/settings.json、.claude/skills/、.claude/agents/、.mcp.json(CLAUDE.md を使うなら、すべてのフォルダーの CLAUDE.md も)
• 個人(コミットしない): .claude/settings.local.json、~/.claude/ — 個人的な指示は ~/.claude/CLAUDE.md に置きます(プロジェクトに CLAUDE.local.md は置きません。AGENTS.md が読まれなくなるからです)
• 指示ファイルは短く保ちます。同じ失敗がくり返されたときだけルールを足し、間違ったルールや役に立たなくなったルールは消します。
• 必ず守るべきことは、指示ではなく権限(deny)とフックで強制します。
• 会社全体のルールは管理設定(managed settings)で配ります — ほかの設定では上書きできません。

長い作業 — 終わるまで自分の作業を確かめさせる

マスターは Claude に「完了の定義」を渡し、それを自分で確かめさせます。テスト・lint・ビルドのように機械が判断できる確認があれば、誰も見ていなくても長い時間働けます。

• 完了の定義はコマンドで渡します —「npm test と npm run lint がどちらも通るまで」。
• 終わったことと残っていることを PROGRESS.md のようなファイルに書かせると、コンテキストが要約されたりセッションが変わったりしても続けられます。
• 小さなステップごとにコミットさせると、いつでも巻き戻せます。
• 3 回試して失敗したら止まって理由を書かせ、空回りするループを防ぎます。
• すべて終わったら、別の AI(例: codex review)やサブエージェントにクロスレビューを任せます。

• ゴールとRalph Loop: 本当に終わるまでエージェントに続けさせる
• VPSとtmux: エージェントを1日24時間働かせる

マスターの練習 — 複数のセッションと自動化

1. git worktree add ../my-project-b -b try-b で作業フォルダーをもう 1 つ作り、両方のフォルダーで claude を 1 つずつ起動して別々の小さな仕事を任せます。2 つのフォルダーの git status が別々に変われば成功です。
2. git diff | claude -p "List bugs in this diff" で 1 行のレビューコマンドを作ります。わざとバグを 1 つ入れて、それを見つけるか確かめます。
3. チームのルールを 1 つ(例: コミット前にテストを実行)AGENTS.md に書き、フックでも強制します。わざとルールを破り、フックが止めるか確かめます。
4. 自分のスキル 1 つとサブエージェント 1 つを上のプラグインの節のとおりにプラグインにまとめてインストールし、別のプロジェクトでも読み込まれるか確かめます。
5. 完了の基準をコマンドで書いて(例: npm test が通る)長い仕事を任せ、終わったと言われたら diff とテスト結果を自分で確かめます。

困ったら: worktree は git worktree list で見て git worktree remove で消します。フックが止めすぎるなら settings.json からいったん外し、/hooks で確認します。5 つとも終わりましたか? 下のチェックリストで自分を点検しましょう。

マスターのチェックリスト

• プロジェクトには AGENTS.md だけ — すべての AI が同じ指示で働く(CLAUDE.md を使うなら、すべてのフォルダーに置き、@AGENTS.md の 1 行を書く)
• 権限のルールで安全なコマンドは聞かずに動かし、秘密のファイルは deny でふさぐ
• くり返す作業はスキルに、大きな検索やレビューはサブエージェントに
• 必ず守るべきことはフックで強制する
• 並行作業は worktree で動かし、くり返す作業は claude -p と GitHub Actions で自動化する
• 完了の定義をコマンドで渡し、結果は diff とテストで自分で確かめる

ツールはよく変わります。新しい機能は claude-skill スキルの /claude-skill update や公式の変更履歴(CHANGELOG)で追いかけましょう。

公式ドキュメント

• Worktrees
• GitHub Actions
• Plugins
• Settings

2026-10-19 に公式ドキュメントで確認しました。これらのツールはよく変わるので、コマンドが動かないときは公式ドキュメントを見てください。