上手に使うコツ

Claude Code のコツの多くは、ひとつの制約から出ています。Claude の文脈ウィンドウ（context window）はすぐ埋まり、埋まるほど性能が落ちる、という点です。このページは、その制約を踏まえた使い方と、モノレポや大きなコードベースで文脈を絞る設定をまとめています。手順の例は よくある作業の進め方、仕組みは Claude Code の全体像 を見てください。

• 会話・読み込んだファイル・コマンド出力のすべてが文脈に入ります。デバッグや探索の1セッションだけで数万トークンを使うことがあります
• 文脈が埋まると、前の指示を「忘れる」ことや間違いが増えます。文脈は最も大切な資源です
• 文脈の使用量は ステータスライン で常に見られます。節約の方法は コストを抑える を見てください
• 後半では、大きなリポジトリで読み込みを絞る設定を扱います

Claude が自分で確かめられるようにする#

確認手段がないと、Claude は「できたように見える」ところで止まり、間違いに気づくのはあなたの役目になります。合否が返る手段があれば、実行・結果の確認・修正の繰り返しが自動で閉じます。手段は、会話の中で Claude が読める信号を返すものなら何でも構いません（テストスイート・ビルドの終了コード・リンター・出力を固定の期待値と比べるスクリプト・設計と比べるブラウザのスクリーンショット）。確認が通ったあと、動いているアプリに対する確認として、自分で /verify を実行できます（スキル）。

確認手段を決めたら、止まる条件にどこまで効かせるかを選びます。

手間をかけるほど注意が要らなくなります。プロンプトだけの方法は今すぐ誰でも使え、/goal と Stop フックは、見ていない実行を正しく終わらせます。

調べて、計画して、実装する#

いきなり実装させると、違う問題を解いたコードになることがあります。プランモード で、探索と実行を分けます。

1. 調べる：Shift+Tab でステータスバーに ⏸ plan mode on と出すか、claude --permission-mode plan で起動します。Claude はファイルを読み、質問に答え、変更はしません
2. 計画する：詳細な実装計画を作らせます。Ctrl+G で計画をテキストエディタで直接編集できます
3. 実装する：計画を承認するか Shift+Tab でプランモードを出て、計画に照らして確かめながら実装させます
4. コミットする：説明のあるメッセージでコミットし、PR を作らせます

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

プロンプトに具体的な文脈を入れる#

探索のあいだは、あいまいなプロンプトも有用です。what would you improve in this file? のように聞くと、思いつかなかった点が出ることがあります。

豊富な内容を渡す#

• @ でファイルを参照します（場所を説明する代わりに。Claude は返答の前に読みます）
• 画像を貼る（コピー＆ペーストかドラッグ＆ドロップ）
• ドキュメントや API リファレンスの URL を渡す。よく使うドメインは /permissions で許可リストに入れます
• データをパイプする（cat error.log | claude -p "explain this error"）
• Bash コマンド・MCP ツール・ファイルの読み込みで、必要なものを Claude 自身に取りに行かせる

環境を整える#

拡張機能の全体と使い分けは Claude Code の全体像 を見てください。

CLAUDE.md を書く#

CLAUDE.md は、毎回の会話の最初に読まれる特別なファイルです。Bash のコマンド・コードスタイル・作業ルールなど、コードから読み取れない永続的な文脈を書きます。決まった書式はなく、短く読みやすくします。

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

/context で読み込まれたか確認できます。毎回読み込まれるので、広く当てはまる内容だけにします。ときどきしか要らない知識や手順は スキル に置き、必要なときだけ読み込ませます。

各行について「これを消すと Claude が間違えるか」を自問し、そうでなければ消します。長すぎる CLAUDE.md は、本当の指示まで無視される原因になります。

• ルールがあるのに Claude が従わないなら、ファイルが長すぎてルールが埋もれている可能性があります。CLAUDE.md にある答えを Claude が質問してくるなら、書き方があいまいかもしれません
• コードのように扱います。問題が起きたら見直し、定期的に削り、変更後は Claude の振る舞いが変わるか観察します。チェックインした CLAUDE.md は /doctor で、コードから分かる内容の削減案を出させられます
• 1つの指示を飛ばされ続けるなら、その行だけに「IMPORTANT」のような強調を足します。多くの行を強調すると、どれも目立たなくなります
• チームが貢献できるよう git にチェックインします。時間とともに価値が増します
• @path/to/import の書き方で、ほかのファイルを取り込めます。置き場所や規則は CLAUDE.md とメモリ を見てください

権限を設定する#

Claude Code v2.1.283 以降では、auto モードが、対話のターミナルと VS Code のセッションで組み込みの開始モードです。別の分類器が、ほとんどの操作を代わりに確認し、危険に見えるものだけを止めます（権限の範囲の拡大・未知のインフラ・敵意のある内容に動かされた操作など）。それ以前の版では、Pro・Max・Team のプランだけが開始モードです。

Manual モードでは、システムを変えうる操作（ファイル書き込み・Bash コマンド・MCP ツール）の前に毎回確認します。安全ですが面倒で、10回目の承認では、確認でなくただ押すことになります。次の2つが、中断を減らします（auto モードでも効きます）。

• 権限の許可リスト：npm run lint や git commit のような、安全と分かっているツールを許可する
• サンドボックス：OS レベルの隔離でファイルとネットワークのアクセスを制限し、境界の中では自由に動かせる

詳しくは 権限モード、権限ルール、サンドボックス を見てください。

CLI ツールを使わせる#

CLI ツールは、外部サービスを扱うのに最も文脈を使わない方法です。GitHub なら gh CLI を入れると、Issue の作成・PR の作成・コメントの読み取りを Claude が行えます。gh が無くても GitHub API は使えますが、認証なしのリクエストはレート制限に当たりやすくなります。知らない CLI も学べるので、Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C. のように頼めます。

MCP サーバーをつなぐ#

MCP サーバーがあると、Issue トラッカーからの機能実装、データベースの照会、監視データの分析、Figma のデザインの取り込み、ワークフローの自動化を頼めます。詳しくは MCP サーバーをつなぐ を見てください。

フックを設定する#

フックは、Claude の作業の決まった時点でスクリプトを自動で動かします。助言にとどまる CLAUDE.md の指示と違い、決まって実行されます。Claude にフックを書かせることもできます（Write a hook that runs eslint after every file edit、Write a hook that blocks writes to the migrations folder）。手で設定するには .claude/settings.json を直接編集し、/hooks で設定済みの内容を見られます。詳しくは フックの使い方 を見てください。

スキルを作る#

スキルは、プロジェクト・チーム・分野に固有の情報で、Claude の知識を広げます。Claude は関連するときに自動で使い、/skill-name で直接呼ぶこともできます。

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

直接呼ぶ、繰り返しの手順も定義できます。副作用のある手順は、disable-model-invocation: true を付けて、手動でだけ起動するようにします。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

/fix-issue 1234 で呼びます。詳しくは スキル を見てください。

サブエージェントを作る#

サブエージェントは、自分の文脈で、許可されたツールだけを使って動きます。多くのファイルを読む作業や、メインの会話を散らかさずに集中させたい作業に向いています。

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

使わせるには明示します：Use a subagent to review this code for security issues. 詳しくは サブエージェント を見てください。

プラグインを入れる#

プラグインは、スキル・フック・サブエージェント・MCP サーバーを1つにまとめた、導入できる単位です。型のある言語なら、コードインテリジェンスのプラグインで、シンボルの移動と編集後のエラーの自動検出が正確になります。詳しくは プラグインを使う を見てください。

効果的に伝える#

先輩エンジニアに聞くような質問を Claude にします。大きな機能では、実装の前に Claude にインタビューさせて仕様を書かせます。

コードベースの質問をする#

新しいコードベースに入るとき、学習と探索に使えます。たとえば次のような質問です。

• How does logging work?
• How do I make a new API endpoint?
• What does async move { ... } do on line 134 of foo.rs?
• What edge cases does CustomerOnboardingFlowImpl handle?
• Why does this code call foo() instead of bar() on line 333?

特別な聞き方は要りません。そのまま質問します。立ち上がりが早まり、ほかのエンジニアの負担も減ります。

Claude にインタビューさせる#

考えていなかった点（技術的な実装・UI/UX・エッジケース・トレードオフ）を聞いてもらえます。[brief description] を機能の説明に置き換えて送ります。

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

仕様ができたら、新しいセッションで実行します。実装だけに集中した、きれいな文脈になり、参照できる仕様書も手元に残ります。いちばん役立つ仕様は自己完結していて、関係するファイルとインターフェースを挙げ、対象外を明記し、機能が動くことを示す通しの確認の手順で終わります。実装を眺めるより、仕様を正確にする時間のほうが報われます。

セッションを管理する#

会話は永続的で、元に戻せます。

早めに軌道修正する#

最初の試みで完璧に解けることもありますが、素早く直すほうが、たいてい良い解を早く得られます。

同じ問題で2回より多く直したなら、失敗した方法で文脈が散らかっています。/clear で、学んだことを盛り込んだより具体的なプロンプトから始めます。きれいなセッションと良いプロンプトは、たいてい、修正を重ねた長いセッションに勝ります。

文脈を積極的に管理する#

文脈の上限に近づくと、Claude Code は会話の履歴を自動で圧縮し、重要なコードと判断を残して空きを作ります。長いセッションでは、無関係な会話・ファイルの内容・コマンドで文脈が埋まり、性能が落ちたり Claude が気を取られたりします。

• /clear を作業のあいだに頻繁に使い、文脈を完全にリセットする
• 自動圧縮では、コードのパターン・ファイルの状態・重要な判断など、大事なことが要約される
• より細かく制御するには /compact <instructions> を使う（例：/compact Focus on the API changes）
• 会話の一部だけ圧縮するには、Esc を2回か /rewind で、メッセージのチェックポイントを選び「Summarize from here」か「Summarize up to here」を選ぶ。前者はそこから先を、後者はそれより前を要約し、残りはそのまま保つ（チェックポイントと巻き戻し）
• CLAUDE.md に「When compacting, always preserve the full list of modified files and any test commands」のような指示を書き、圧縮されても大事な文脈を残す
• 文脈に残す必要のない質問には /btw を使う。答えは会話の履歴に入らないので、文脈を増やさずに細部を確かめられる（対話モードの操作）

調査はサブエージェントに任せる#

文脈が根本の制約なので、調査を文脈の外へ出します。コードベースを調べると、多くのファイルを読んで文脈を使います。サブエージェントは別の文脈ウィンドウで動き、要約を返します。

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

実装のあとの検証にも使えます（後述の「敵対的なレビュー」）。

チェックポイントで巻き戻す#

Claude は変更の前に自動でファイルのスナップショットを取ります。Esc を2回押すか /rewind で、巻き戻しのメニューを開きます。会話だけ・コードだけ・両方を戻す、または選んだメッセージから要約する、が選べます。詳しくは チェックポイントと巻き戻し を見てください。

細かく計画する代わりに、危険な方法を試させて、だめなら戻して別の方法を試せます。チェックポイントは会話と一緒に保存されるので、ターミナルを閉じて、あとでセッションを再開しても巻き戻せます。

会話を再開する#

会話はローカルに保存されるので、複数回にまたがる作業でも文脈を説明し直さずに済みます。claude --continue で続きから、claude --resume で一覧から選びます。後で見つけやすいよう、oauth-migration のような説明的な名前を付けます。再開・分岐・名前の操作は セッションの再開と管理 を見てください。

自動化と規模の拡大#

1つの Claude を使いこなせたら、並列セッション・非対話モード・ファンアウトで成果を増やします。

非対話モードで動かす#

claude -p "your prompt" で、対話のプロンプトなしに Claude を動かせます。--no-session-persistence を付けない限り、再開できるセッションができます。出力形式は、プレーンテキスト・JSON・ストリーミング JSON から選べます。

# 単発の質問
claude -p "Explain what this project does"

# スクリプト向けの構造化出力
claude -p "List all API endpoints" --output-format json

# リアルタイム処理向けのストリーミング
claude -p "Analyze this log file" --output-format stream-json --verbose

1つ目はプレーンテキストを出力します。json は、result フィールドを持つ単一の JSON オブジェクトを返します。stream-json は、init イベントから始まり、1行に1つの JSON オブジェクトを出力します。詳しくは ヘッドレス実行（-p） を見てください。

複数の Claude を並列に動かす#

どれだけ自分で調整するかに合わせて選び、セッション同士が発見を渡す必要があるときはメッセージの仕組みを足します。

並列化のほかに、品質を狙う使い方もあります。新しい文脈でのコードレビューは、直前に自分が書いたコードに偏らないので、改善します。たとえば、Writer と Reviewer のパターンです。

テストでも似たことができます。1つの Claude にテストを書かせ、別の Claude にそれを通すコードを書かせます。

ファイルにファンアウトする#

大きな移行や分析は、多数の並列な Claude の呼び出しに分散できます。/batch <instruction> を実行すると、Claude が変更を5〜30のサブエージェントに分け、それぞれが自分の worktree で動きます。自分のスクリプトで動かすなら、claude -p をループします。

1. タスクの一覧を作ります：移行が要るファイルの一覧をファイルに書かせます（例：list all 2,000 Python files that need migrating and save the list to files.txt）
2. 一覧を回すスクリプトを書きます
3. 数ファイルで試してから、全体で実行します。最初の2〜3ファイルで起きた問題に合わせてプロンプトを直します。--allowedTools は移行に要るツールを事前承認し、--permission-mode dontAsk は、それ以外で承認が要るものを拒否するので、無人で動かすときに重要です

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

既存のデータ処理のパイプラインにも組み込めます。

claude -p "<your prompt>" --output-format json | your_command

auto モードで自律的に動かす#

バックグラウンドの安全確認つきで中断なく動かすには、auto モードを使います。分類器が実行前にコマンドを確認し、権限の範囲の拡大・未知のインフラ・敵意のある内容に動かされた操作を止め、通常の作業は確認なしで進めます。

claude --permission-mode auto -p "fix all lint errors"

-p の非対話の実行で分類器が何度も操作を止めても、Claude Code は実行を止めません。代わりに何が起きるかとしきい値は 権限モード を見てください。

敵対的なレビューを足す#

無人で長く動くほど、完了と数える前の独立した確認が重要になります。新しいサブエージェントの文脈で動くレビュアーは、差分と与えた基準だけを見て、変更を生んだ推論は見ません。結果を、それ自身の基準で評価できます。

正しさの確認なら、組み込みの /code-review スキルが、新しいサブエージェントで現在の差分のバグを見て、結果をセッションへ返します（コードレビューと ultrareview）。計画に照らして差分を確認したいなら、レビューのプロンプトを自分で書きます。確認する作業・照らす計画・何を指摘とするかを書きます。

Use a subagent to review the rate limiter diff against PLAN.md. Check that
every requirement is implemented, the listed edge cases have tests, and
nothing outside the task's scope changed. Report gaps, not style preferences.

レビュアーはサブエージェントなので、実装側のセッションが指摘を直接受け取り、あなたが結果を写さずに、直して再レビューできます。

よくある失敗パターン#

直感を育てる#

このページのパターンは固定の決まりではなく、一般にうまくいく出発点です。状況によっては最適とは限りません。

• 1つの複雑な問題に深く入っていて履歴に価値があるときは、文脈をためるべきです
• 探索的な作業では、計画を飛ばして Claude に任せるほうがよいことがあります
• 制約する前に Claude が問題をどう解釈するか見たいなら、あいまいなプロンプトが適しています

何がうまくいったか注意します。良い出力が出たとき、プロンプトの構成・渡した文脈・使ったモードを覚えておきます。苦戦したときは理由を考えます（文脈がノイズだらけか、プロンプトがあいまいか、1回で済ますには作業が大きすぎたか）。

大規模リポジトリ・モノレポの設定#

数百万行の単一リポジトリでも、多数のパッケージを持つモノレポでも、Claude Code は動きます。ただし規模が大きくなると、小さなプロジェクト向けの既定値では、作業と無関係な指示とファイルの読み込みが文脈を埋め、トークンを使い、性能を落とします。ここでは、作業が触る部分に Claude を絞る方法を扱います。各設定は、自分のマシンだけのものか、リポジトリにコミットするものかを併記しています。

設定の一覧#

各設定は独立で、重ねて使えます。リポジトリに合うものを選びます。

以降の例は、3つのパッケージを持つモノレポを前提にします。

monorepo/
  CLAUDE.md                     # ルートの指示
  packages/
    api/
      CLAUDE.md                 # API 固有の指示
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # フロントエンド固有の指示
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # 共有ライブラリの指示
      src/

大きな単一ツリーでも同じパターンが使えます。packages/api/ は、src/backend/ や lib/core/ のような自分のサブシステムのディレクトリに読み替えます。

Claude を起動する場所を選ぶ#

claude を起動する場所が、追加の許可なしに読み書きできるファイル・起動時に読み込まれる CLAUDE.md・適用されるプロジェクト設定を決めます。

.claude/settings.json のプロジェクト設定は、CLAUDE.md と違って、親ディレクトリから継承されません。どのディレクトリの .claude/settings.json を読むかは 設定ファイルの仕組み を見てください。

ディレクトリごとに CLAUDE.md を重ねる#

大きなコードベースで、ルートに CLAUDE.md を1つだけ置くと、全サブシステムの規約を抱えて無関係な指示に文脈を使うか、汎用的すぎて役に立たなくなりがちです。ディレクトリごとに分けると、Claude はリポジトリ全体のルールに加えて、作業中のコードの規約だけを読み込みます。

Claude Code は、起動時に作業ディレクトリとすべての親ディレクトリの CLAUDE.md を読み込み、サブディレクトリのものは、そこのファイルを読んだときに必要に応じて読み込みます。ふつうは2段に分けます。

• ルートの CLAUDE.md：どこでも当てはまる指示（コーディング規約・コミットの規約など）
• サブディレクトリの CLAUDE.md：その領域のスタック固有の規約（モノレポならパッケージごと、単一ツリーなら src/db/ や src/api/ のようなサブシステムごと）

チームメイトが引き継げるよう、リポジトリにコミットします。各ディレクトリの持ち主が、ふつうそのファイルを管理します。すでにチェックインされたファイルを削るには /doctor を使います。

Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example `api: add rate limiting`.
Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.

Copy `.env.example` to `.env` before running anything. Tests and the dev server fail without it.
Write database queries with the Knex query builder. Never put raw SQL strings in route handlers.
Never edit a migration after it has merged. Add a new migration instead.

1つ目がルートの CLAUDE.md、2つ目が packages/api/CLAUDE.md の例です。packages/api/ から起動すると、packages/api/CLAUDE.md とルートの CLAUDE.md の両方が読み込まれ、packages/web/ の指示は文脈に入りません。読み込まれたファイルは、/context の「Memory files」の一覧で確認できます。

ファイルを最新に保つ方法です。

• PR でレビューする：CLAUDE.md の編集もほかのドキュメントの変更と同じに扱い、規約がコードに追随するようにする
• 大きなモデルのリリースのあとに見直す：古いモデルの限界を回避するための指示は、新しいモデルでは負担になることがある（例：単一ファイルのリファクタリングを強いるルール）
• 更新を提案する Stop フックを足す：Stop フックは、Claude が応答を終えたときにセッションのトランスクリプトのパスを受け取るので、スクリプトがセッションを見直し、露呈した不足が新しいうちに CLAUDE.md の更新を提案できる

ディレクトリごとの CLAUDE.md とパス指定のルール#

どちらも、ツリーの一部に指示を絞れます。置き場所と読み込まれる時点が違います。

スキルも含めた比較は Claude Code の全体像 を見てください。

無関係な CLAUDE.md を除外する#

ルートから起動すると、Claude がそのディレクトリのファイルを読んだ時点で、各サブディレクトリの CLAUDE.md が読み込まれます。claudeMdExcludes は、パスや glob で指定したファイルを読み込まないようにします。

作業しないディレクトリ（ほかのチームのパッケージ・レガシーコード・ベンダーのサブツリー）に使います。除外の一覧は固定で、作業ごとの切り替えではありません。今日はこのパッケージ、明日は別のパッケージ、という場合は、除外を編集せず、そのパッケージのディレクトリから起動します。

自分だけの除外なら .claude/settings.local.json に書きます。Claude Code は、その場所に設定を保存するとき、そのファイルをグローバルの gitignore に足します。手で作る場合は、自分で gitignore に足します。パターンは絶対パスに対する glob で、相対的な書き方の先頭には **/ を付けます。

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

これで、そのパッケージの下のすべての CLAUDE.md とルールのファイルが読み込まれなくなります。ルートの CLAUDE.md と作業するパッケージのものは、通常どおり読み込まれます。

• 管理ポリシーの CLAUDE.md は除外できません。組織全体の指示は常に適用されます
• claudeMdExcludes は、ユーザー・プロジェクト・ローカル・管理のどのスコープにも設定できます。配列はスコープをまたいで統合されるので、チームがプロジェクトの既定を決め、個人がローカルで足せます

Claude の読み込みを減らす#

指示は、文脈に入るもののごく一部です。ファイルの読み込みも、コードベースに応じて増えるコストです。

生成物とベンダーのコードの読み込みを止める#

Claude の内容検索は、既定で .gitignore に従います。すでに載っているパス（node_modules/・dist/・build/ など）は、追加の設定なしで検索結果に出ません。ベンダーの SDK やコミットされた生成コードのようなチェックイン済みのパスは、permissions.deny の Read の拒否ルールで、開くのを止めます。

拒否ルールが及ぶ範囲は、置く設定ファイルで決まります。

• リポジトリで作業する全員：.claude/settings.json にコミットする（ルートから起動するならルート、サブディレクトリから起動するならパッケージごとの .claude/）。この設定は、親ディレクトリから継承されません
• 自分だけ：リポジトリのルートの .claude/settings.local.json。起動ディレクトリに関わらず、リポジトリ内のすべての CLI セッションで読み込まれます（Windows のように Claude Code がリポジトリのルートを使わない場合を除く）。Read(./**/vendor/**/*) のような相対パターンは、リポジトリのルートでなくセッションの現在の作業ディレクトリを基準にするので、サブディレクトリから起動するなら、このファイルのルールは // で始まる絶対パスで書きます
• 全員に、すべてのセッションで強制：管理設定にルールを置く。ユーザーとプロジェクトの設定では上書きできません

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)",
      "Read(./**/*.generated.*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

ディレクトリのパターンは /** でなく /**/* で終わらせます。ディレクトリの中身はすべて対象で、ディレクトリ自体は対象外になるので、ls dist や cd build はできます。

• 拒否ルールが覆うのは、Claude の組み込みのファイルツールです。Bash では、拒否されたパスが引数に出てくる cat・head・grep・find など Claude Code が認識するファイルのコマンドと、< file のようなリダイレクトの対象を覆います
• 組み込みの Grep と Glob の結果からも、拒否されたパスを除くよう努めます。拒否されたファイルを含むディレクトリへの、Bash の grep -r や find の検索には、それらが出力に含まれます
• ファイルを自分で開くサブプロセスは覆いません。パターンの書き方は 権限ルール を見てください

コードインテリジェンスでファイルの読み込みを減らす#

大きなコードベースでは、シンボルの定義や使用箇所を探すのに、多くのファイル読み込みと grep が要ります。コードインテリジェンスのプラグインは、Claude を言語サーバーにつなぎ、ツリーを走査せずに、定義へのジャンプ・参照の検索・型エラーの表示を行わせます。公式マーケットプレイスには TypeScript・Python・Go・Rust などのプラグインがあります。VS Code 拡張とデスクトップアプリでは、プラグインを使うの入れ方に従います。端末では claude で Claude Code を起動し、そのプロンプトに次を入力して TypeScript のプラグインを入れます。

/plugin install typescript-lsp@claude-plugins-official

インストールが失敗したときは、Claude Code が出すメッセージに合わせます。

• Marketplace "claude-plugins-official" not found：/plugin marketplace add anthropics/claude-plugins-official でマーケットプレイスを足して、再試行する
• マーケットプレイスにプラグインが見つからない：プラグイン名を確認する

リポジトリの全員に有効にするには、自分で入れる代わりに、プロジェクト設定の enabledPlugins に足します。コードインテリジェンスのプラグインは、各開発者のマシンに、その言語の言語サーバーのバイナリが要ります（言語ごとのバイナリは プラグインを使う）。公式マーケットプレイスは GitHub でホストされているので、入れるには GitHub へのネットワークアクセスが要ります。制限されたネットワークでは、社内の Git ホストかローカルのパスからマーケットプレイスを足します。

これは、上の claudeMdExcludes と Read の拒否ルールと相性が良いです。それらが無関係な内容を文脈から外し、コードインテリジェンスが、残りを読み通して定義を探すことを避けさせます。

worktree とファイルのアクセスを絞る#

必要なディレクトリだけをチェックアウトする#

--worktree フラグは、新しい git worktree でセッションを始め、メインのチェックアウトから変更を隔離します。既定ではリポジトリ全体をチェックアウトします。大きなリポジトリでは、worktree.sparsePaths が git の sparse-checkout で、列挙したディレクトリとルート直下のファイルだけをディスクに書き、worktree の立ち上がりが速く、容量も小さくなります。

このディレクトリで作業する全員が同じパスを要するなら、.claude/settings.json にコミットします。自分用に足すなら .claude/settings.local.json を使います。一覧はスコープをまたいで統合されるので、ローカルのファイルはコミットされた一覧にパスを足せますが、消せません。

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

Claude が worktree を作るとき、全体でなく .claude/・packages/api/・packages/shared/ だけをチェックアウトします。sparsePaths のパスは、どのサブディレクトリから起動しても、リポジトリのルートからの相対です。パッケージのルートに限らず、任意のディレクトリのパスが使えます。

• サブエージェントの worktree による隔離で特に役立ちます。worktree で動く各サブエージェントが、全体でなく軽いチェックアウトを得ます。セッション内のすべての worktree が同じ sparsePaths を共有するので、あるサブエージェントが packages/api/、別のが packages/web/ を要するなら、両方を列挙します
• 個々のファイルでなくディレクトリを書きます。package.json・tsconfig.base.json・ロックファイルなどのルート直下のファイルは、列挙したディレクトリと一緒に常にチェックアウトされます。ルート直下のディレクトリはそうならないので、リポジトリのルートの .claude/settings.json や .claude/rules/ を worktree で使うなら .claude を入れます。プロジェクトのスキル・エージェント・コマンドは worktree で並行作業 を見てください
• sparse checkout は、sparse な worktree が存在するあいだ、リポジトリ共有の .git/config で git が extensions.worktreeConfig を有効にすることを要します。Claude Code は、最後の worktree を消したあとにその項目を消しますが、Claude Code が足した場合だけです。自分で設定した値は消しません。v2.1.207 より前は、最後の worktree を消しても項目が残り、tea など go-git ベースのツールがリポジトリを開けませんでした（git config --unset extensions.worktreeConfig を実行するまで）
• node_modules のような大きなディレクトリを worktree ごとに複製しないよう、同じ .claude/settings.json で sparsePaths と symlinkDirectories を組み合わせます。各 worktree の node_modules/ から、メインのリポジトリのものへのシンボリックリンクが作られます

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

パッケージやリポジトリをまたいでアクセスを許す#

この節は、サブディレクトリから起動するとき、または作業が複数のチェックアウトにまたがるときの話です。単一の大きなツリーのルートから起動するなら、すでにすべてのファイルにアクセスできるので、飛ばせます。

packages/api/ から起動すると、Claude はそのディレクトリ内のファイルを読み書きできます。api と web の両方が取り込む共有の型を更新するように、パッケージをまたぐ変更では、兄弟ディレクトリへのアクセスを許す必要があります。別にチェックアウトしたリポジトリにも、同じ仕組みを使います。

.claude/settings.json の additionalDirectories が、作業ディレクトリの外のディレクトリへのアクセスを許します。相対パスは、起動したディレクトリを基準にします。

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

設定を編集せず、実行時に許すには、起動時に --add-dir を渡します。

claude --add-dir ../shared

どの方法で足しても、そのディレクトリのファイルを読み書きできます。そのディレクトリの CLAUDE.md・.claude/rules/・スキルが読み込まれるかは、足し方で変わります。

--add-dir や /add-dir で足したディレクトリの CLAUDE.md とルールを読み込むには、環境変数 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD を設定します。additionalDirectories 設定に挙げたディレクトリには効きません（CLAUDE.md とメモリ）。

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

この領域の全員が要る兄弟ディレクトリは、.claude/settings.json に additionalDirectories をコミットします。個人の選択や一度きりのアクセスは、.claude/settings.local.json か、起動時の --add-dir を使います。

ディレクトリごとのスキルを足す#

どのサブディレクトリにも、そのスタック専用のスキルを定義できます。スキルは、Claude が関連すると判断したときに読み込まれるので、フロントエンドの作業中に、API 固有のツールが文脈を使うことはありません。スキルは、ディレクトリの中の .claude/skills/ に置き、その領域のコードと一緒にコミットします。モノレポならパッケージごと、単一ツリーなら src/db/.claude/skills/ のようなサブシステムごとです。

mkdir -p packages/api/.claude/skills/api-testing

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test structure
Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.

## Running tests
- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`

## Test utilities
- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

## Patterns
- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

上は packages/api/.claude/skills/api-testing/SKILL.md の例です。別のサブディレクトリには、同じ要領で別のスキルを置きます（packages/web/.claude/skills/component-patterns/ は、テストでなくフロントエンドのコンポーネントの規約を説明します）。packages/api/ のファイルで作業するときは api-testing が、packages/web/ では component-patterns が読み込まれ、互いの作業中には読み込まれません。

置き場所でなくファイルのパターンで絞ることもできます。paths の frontmatter フィールドは glob を取り、Claude が一致するファイルを扱うときだけ、そのスキルを自動で読み込みます。リポジトリのルートの .claude/skills/ に置きつつ、特定のファイルにだけ当てはまるスキル（たとえば **/migrations/** に絞ったデータベース移行のスキル）に使います。作り方と整理は スキル を見てください。

スキルを見つけやすく保つ#

スキルが多くのディレクトリに散らばると、Claude が選ぶ一覧が大きくなります。Claude は、見つけたすべてのスキルの名前と説明を読んで選び、選ばれたスキルの全文だけが文脈に読み込まれます。範囲に入るスキルは、起動する場所で変わります。

• packages/api/ のようなサブディレクトリから：そのディレクトリ・リポジトリのルートまでのすべての親・ユーザーと企業のレベルのスキル
• リポジトリのルートから：ルートのスキルと、セッション中に Claude が触れたすべてのサブディレクトリのスキル。数百に積み上がることがある
• --add-dir で兄弟を足したあと：その兄弟のスキルも読み込まれる。additionalDirectories 設定はファイルのアクセスだけを許し、スキルは読み込まない

名前は常に読み込まれますが、数が多いと、一部のスキルは説明が完全に省かれ、Claude が当てはまるか判断するためのキーワードが失われることがあります。説明は短くし、依頼に含まれる言葉から始めます（例：「writing or modifying tests in packages/api/」）。

PR の規約やデプロイのチェックリストのように、多くのディレクトリで共有するスキルは、どの起動ディレクトリからも読み込まれるよう、リポジトリのルートの .claude/skills/ に置きます。共有するスキルに独自のバージョン履歴が要る、またはリポジトリをまたいで使うなら、代わりに プラグイン にまとめます。プラグインのスキルは plugin-name:skill-name の名前空間なので、ディレクトリごとのスキルと衝突せず、プラットフォームチームが1か所でバージョン管理と更新をできます。

使われていないスキルを知るには、OpenTelemetry の logs exporter を有効にし、OTEL_LOG_TOOL_DETAILS=1 を設定して、スキル名が伏せられずそのまま記録されるようにします。skill_activated イベントは、すべての呼び出しを skill.name 属性に記録し、invocation_trigger は、コマンド・Claude・入れ子のスキルのどれが呼んだかを記録します。統合や廃止の判断に使えます（利用状況の計測）。

重ねるのが限界になったら規約を集中させる#

ディレクトリごとの CLAUDE.md は、コードベースの成長で統治が難しくなることがあります。規約がずれ、ファイルが古くなり、ルートの持ち主がいなくなります。これを解くのは、各開発者でなく、リポジトリの Claude Code の設定を管理するチームの役目になるのがふつうです。

規約と参照内容を、常時読み込まれる CLAUDE.md から、必要なときに読み込まれる仕組みへ移します。

• スキル：作業に関連するときだけ読み込まれる参照資料
• プラグインを作って配る：プラットフォームチームが集中して持つ、スキル・フック・コマンドのバージョン付きの束
• MCP サーバーをつなぐ：組織がすでにリポジトリのコード検索や RAG の索引を運用しているなら、MCP ツールとして公開し、Claude がファイルを直接読まずに照会するようにする

プラットフォームチームが集中して強制する方法は 組織への導入と管理設定 を見てください。

セッションの開始時に適切なプラグインを勧める#

規約がプラグインに移ると、見慣れない領域で Claude を起動したチームメイトには、その領域の持ち主がどのプラグインを管理しているかの手がかりがありません。SessionStart フックがこれを埋められます。フックが標準出力へ出したプレーンテキストは、最初のプロンプトの前に、Claude Code が Claude の文脈に足します。

たとえば、フックの入力から起動ディレクトリを読み、リポジトリにコミットしたパスとプラグインの対応表で引き、推奨を出力して、Claude が最初の返答で伝えるようにするスクリプトを書けます。フックの書き方と登録は フックの使い方 を見てください。

全部を組み合わせる#

モノレポの配置での組み合わせた設定です。単一ツリーの任意のサブディレクトリにも、同じファイルが使えます。各サブディレクトリの .claude/settings.json は、ルートのファイルに重ねるのでなく、自己完結にします。

packages/api/ で作業する全員が、同じ兄弟へのアクセス・sparse パス・除外を得るよう、worktree・additionalDirectories・Read の拒否ルールを .claude/settings.json にコミットします。次が packages/api/.claude/settings.json です。

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

このセッションは packages/api/ から始まるので、兄弟パッケージの CLAUDE.md はもう範囲の外で、claudeMdExcludes は要りません。ルートからもセッションを始めるなら、リポジトリのルートの .claude/settings.local.json に足します。

additionalDirectories は、packages/api/ から直接起動したときに効きます。このセッションから作った worktree の中では、作業ディレクトリが worktree のルートなので、この設定ファイルは読み込まれません。兄弟パッケージは、これがなくても worktree の中で到達できますが、拒否ルールは、worktree のセッションが拾えるよう、リポジトリのルートの .claude/settings.json にもう1部要ります。

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

設定後のリポジトリの配置です。

monorepo/
  CLAUDE.md
  .claude/settings.json                           # worktree のセッション用の拒否ルール
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree、additionalDirectories、拒否ルール
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

この設定で packages/api/ から Claude を起動すると、次のようになります。

• ルートの CLAUDE.md と packages/api/CLAUDE.md を読み込み、packages/web/CLAUDE.md は読み込まない
• packages/api/ と packages/shared/ のファイルを読み書きできる
• packages/api/ の dist/ と build/ の下のビルド出力の読み込みを避ける
• api-testing のスキルを、必要なときに使える
• .claude/・packages/api/・packages/shared/・ルート直下のファイルを含む worktree を作る。拒否ルールは、ルートの設定ファイルから worktree 全体に適用される

パッケージをまたぐ変更の範囲と計画#

上の設定は、Claude が何を見るかを制御します。共有の型と、それを使うすべての呼び出し箇所を更新するように、1つの変更が複数のパッケージに触れるときは、作業の範囲と順序の付け方も結果に影響します。

• 変更の全体を1つのセッションで渡す：共有の編集と呼び出し箇所を一緒に渡すと、各編集の背後の判断が揃い、パッケージごとに導き直さずに済みます
• 編集の前に計画する：プランモード で先に計画すると、Claude が計画をファイルに書きます。パッケージをまたぐ長いセッションは途中で文脈が圧縮されます（コンテキストとプロンプトキャッシュ）。Claude Code は、圧縮のたびに計画のファイルを入れ直すので、会話の履歴が残らなくても計画は残ります

設定したあとの改善として、フックでディレクトリごとのリンターや型チェッカーを編集後に動かす、コストの節約で規模がトークン使用量に与える影響を確かめる（コストを抑える）、といった方法があります。