株式会社TIMEWELLの濱本です。
Claude Codeの.claudeフォルダ、中を開いたことはありますか。実はこのフォルダの設計が、AIとの協業の質をほぼ決めてしまいます。この記事は2026年7月時点の公式ドキュメントを一通り読み直し、初版に混じっていた誤りを一次情報で直したうえで、CLAUDE.mdからサブエージェント、hooks、オートメモリ、MCP、他ツールとの互換まで、.claudeエコシステムを丸ごと解剖する「決定版リファレンス」を目指したものです。半年前の常識がすでに古くなっている箇所もあるので、以前この手の記事を読んだ方こそ確認してみてください。
Claude Codeに「記憶」はない。だから.claudeを設計する
Claude Codeを使い始めて最初に戸惑うのが、セッションをまたいだ記憶が残らないという事実です。昨日「このプロジェクトはTypeScriptで、テストはVitest」と伝えたのに、翌日の新しいセッションは何も覚えていない。毎朝記憶がリセットされる同僚と組んでいるようなものです。
この空白を埋めるために設計されたのが.claudeフォルダであり、その中核がCLAUDE.mdです。Claudeはセッションを開始するたびにこれらを読み込みます。ここに書いた情報が、実質的にClaudeの「長期記憶」になります。
記憶の仕組みは大きく2系統に分かれます。ひとつは開発者が自分で書くCLAUDE.mdで、Claudeの行動を意図的にガイドするためのもの。もうひとつはClaude自身が学びを書き留める「オートメモリ」で、あなたの修正や好みから自動でパターンを拾っていくものです。前者が能動的な指示、後者が受動的な学習、と役割が分かれています。この2つが噛み合うと、セッションが変わっても一貫した開発体験が生まれます。
私たちTIMEWELLでも、社内のリポジトリはほぼ毎日Claude Codeで開くため、CLAUDE.mdとオートメモリの整備には手をかけています。地味な作業ですが、ここを丁寧にやるかどうかで手戻りの量がまるで違います。最先端のプロンプト技術より、この「環境設定」のほうが効くというのが正直な実感です。
.claudeフォルダの全体像。何がどこにあるのか
まず全体の見取り図です。ここで初版から直したい誤りが2つあります。ひとつはMCP設定ファイルの位置、もうひとつは個人用のCLAUDE.local.mdの存在です。順に見ていきます。
プロジェクトルート/
├── CLAUDE.md # プロジェクト全体への指示書（プロジェクトルートが基本）
├── CLAUDE.local.md # 自分専用のプロジェクト指示（gitignore対象）
├── .mcp.json # プロジェクトスコープのMCP設定（チーム共有・ここが正しい位置）
└── .claude/
├── settings.json # チーム共有の設定（Git管理）
├── settings.local.json # 個人設定（gitignore）
├── rules/ # トピック別の指示ファイル群
├── skills/ # 再利用可能なワークフロー定義
│ └── deploy/SKILL.md
├── agents/ # 専門特化型サブエージェント
└── commands/ # カスタムコマンド（skillsに統合。既存も動作する）
~/.claude/ # ユーザー個人（全プロジェクト共通）
├── CLAUDE.md
├── settings.json
└── keybindings.json
~/.claude.json # local / user スコープのMCP設定（.claudeフォルダの中ではない）
プロジェクトスコープのMCP設定は、.claude/の中ではなく**プロジェクトルート直下の.mcp.json**に置くのが正式な場所です。チームで共有したいMCPサーバーはここに書きます。一方、自分だけで使うlocalスコープや全体で使うuserスコープの設定は~/.claude.jsonに入り、こちらも.claude/フォルダの中には置きません。初版ではここを.claude/.mcp.jsonと書いていましたが、これは誤りでした。お詫びして訂正します。
もうひとつ、プロジェクト個人用の./CLAUDE.local.mdも押さえておきたいファイルです。チーム共有のCLAUDE.mdとは別に、自分だけのメモや一時的な指示を書く場所で、gitignoreの対象です。「チーム全体には出したくないが、このリポジトリでは自分に効かせたい」指示はここに書きます。
.claudeは「プロジェクト内」と「ユーザーのホーム（~/.claude/）」の2箇所に存在し得ます。プロジェクト内のものはチーム全員に、ホームのものは自分だけに効きます。ここを混同すると、意図せずチームの挙動を変えてしまうので注意してください。
AI駆動開発を、実務で使えるところまで
トレンドを追うだけで終わらせないための実践プログラムがWARPです。元大手DX・データ戦略の専門家が、現場で動かすところまで伴走します。
CLAUDE.md。指示書としての設計と、200行の本当の意味
CLAUDE.mdは.claudeエコシステムで最も重要なファイルです。ここに書いた内容は毎セッションの冒頭でコンテキストに読み込まれ、その後の応答すべてに影響します。配置場所によって効く範囲が変わるので、まず整理しておきます。
| スコープ | 配置場所 | 影響範囲 | 共有 |
|---|---|---|---|
| 組織（マネージド） | managed-settings.jsonのclaudeMdキーに直接埋め込み |
組織全体 | IT管理者が配布 |
| プロジェクト | ./CLAUDE.md（.claude/CLAUDE.mdも可） |
リポジトリ全体 | Gitで共有 |
| 個人（プロジェクト内） | ./CLAUDE.local.md |
このリポジトリの自分だけ | gitignore |
| ユーザー | ~/.claude/CLAUDE.md |
全プロジェクト（個人） | 自分だけ |
さて、ここで初版最大の誤りを正します。初版には「3,000トークンを超えると指示の遵守率が下がる」と書きましたが、この数値は公式ドキュメントに載っていません。裏取りできない数字だったので削除します。公式が言っているのは「200行以内を目安にする（target under 200 lines）。長いほどコンテキストを消費し、遵守率も下がる」というところまでです。
そしてもうひとつ大事な事実。行数の上限を気にする必要があるのは、実はCLAUDE.mdではありません。CLAUDE.mdは長さに関わらず全文が読み込まれます。行数や容量で「読み込まれない部分」が出るのは、後述するオートメモリのMEMORY.mdのほうだけです。つまり200行はあくまで「短く保ったほうがClaudeが賢く動く」という設計上の指針であって、超えたら読まれなくなる、という話ではないのです。ここは混同しやすいので、はっきり分けて覚えておいてください。
効果的な書き方の勘所は3つです。第一に、具体的に書くこと。「適切にフォーマットして」ではなく「インデントはスペース2つ、セミコロンは省略、シングルクォート」と書きます。検証できる指示ほど守られます。第二に、構造化すること。見出しと箇条書きで関連する指示をまとめます。第三に、矛盾を残さないこと。複数のファイルに相反する指示があると、Claudeはどちらかを勝手に選びます。
@インポートで外部ファイルを参照できるのも便利です。
プロジェクト概要は @README.md を参照。
利用可能なnpmスクリプトは @package.json を確認。
Gitワークフローの詳細は @docs/git-instructions.md に従うこと。
地味に効くテクニックとして、CLAUDE.md内のブロックHTMLコメント（<!-- ... -->）はコンテキストに注入される前に除去されます。トークンを消費せずにメンテナ向けのメモを残せるので、「なぜこのルールがあるか」の背景をコメントで書いておくと、後任が助かります。
モノレポで複数チームのCLAUDE.mdが混ざる場合は、claudeMdExcludes設定で他チームのCLAUDE.mdをロード対象から外せます。逆に、追加の作業ディレクトリのCLAUDE.mdも読み込ませたいときは環境変数CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1を使います。CLAUDE.mdが膨らんできたら/doctorが頼りになります。v2.1.206以降、/doctorはCLAUDE.mdのトリム（贅肉落とし）を提案してくれるようになりました。方針は明快で、ディレクトリ構成や依存一覧、アーキテクチャ概要のようにコードベースから導ける情報は削り、落とし穴や判断の根拠、ツールの既定とは違う独自ルールを残す、というものです。
他ツールから移ってきた方に朗報です。Claude CodeはAGENTS.mdを直接は読みませんが、@AGENTS.mdとしてインポートするか、シンボリックリンクを張れば共用できます。しかも/initはAGENTS.mdだけでなく.cursorrulesや.devin/rules/、.windsurfrulesまで読み取って取り込んでくれます。複数のAIコーディングツールを行き来しているチームには、地味にありがたい配慮です。
スキルとカスタムコマンド。「必要なときだけ」呼ぶ指示
CLAUDE.mdやrulesが「常に載っている指示」なのに対して、スキルは必要なときだけ呼び出される指示です。.claude/skills/にワークフローをパッケージ化しておきます。
---
name: deploy
description: 本番環境へのデプロイを実行する
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---
本番デプロイの手順:
1. テストスイートを実行する
2. アプリケーションをビルドする
3. デプロイターゲットにプッシュする
4. デプロイが成功したことを確認する
disable-model-invocation: trueにすると、Claudeが自動でこのスキルを呼ぶのを止め、/deployと明示的に打ったときだけ動くようになります。逆に自動起動させたいならwhen_to_use（最大1,536字）に発火条件を書きます。スキルのfrontmatterには他にもname、description、user-invocable、allowed-tools、disallowed-tools、context、agentといった項目があります。
ここも初版から訂正が必要な箇所です。初版では.claude/commands/を「レガシー」と表現しましたが、正確ではありませんでした。公式の言い方は「カスタムコマンドはskillsにマージされた。既存の.claude/commands/は引き続き動作し、同名frontmatterもサポートする」です。廃止でも非推奨でもありません。同名のスキルとコマンドが両方あるときはスキルが優先されます。既存のcommands/を慌てて捨てる必要はない、と覚えておいてください。
スキルの優先順位は、enterprise（組織）が最も強く、次にpersonal（個人）、最後にproject（プロジェクト）の順です。モノレポでサブディレクトリごとにスキルを分けるネストskillは、v2.1.203以降で使えます。
そもそもスキルは、Claude Code独自の仕組みではなく、Agent Skillsというオープン標準（agentskills.io）に準拠しています。複数のAIツールをまたいで同じスキルを使い回せる、というのが標準化の狙いです。Claude Codeには最初から/doctor、/code-review、/batch、/debug、/loop、/claude-apiといったバンドルスキルが同梱されています。不要ならdisableBundledSkillsで丸ごと無効化できます。
繰り返す作業をスキルにするのは、私が最も投資対効果が高いと感じているカスタマイズです。PRレビュー、デプロイ、DBマイグレーションのように手順が決まった作業は、まずスキル化を検討してみてください。
サブエージェント。専門家チームをAIで再現する
サブエージェントは、メインのセッションとは独立した別のClaudeインスタンスを立ち上げ、特定のタスクを任せる仕組みです。たとえばテスト実行のログは数百行になることもありますが、それをメインのコンテキストに載せると他の文脈を圧迫します。サブエージェントに走らせれば、メインには要約だけが返ってきます。
---
name: code-reviewer
description: コード品質とセキュリティをレビューする専門家
tools: Read, Grep, Glob, Bash
model: inherit
memory: project
---
あなたはシニアコードレビュワーです。呼び出されたら、
最近の変更をgit diffで確認し、品質・セキュリティ・
保守性の観点からフィードバックを提供してください。
初版では組み込みのサブエージェントをExplore、Plan、general-purposeの3種と書きましたが、これも古くなっていました。現在は5種です。探索用のExplore、プランモード中の調査を担うPlan、汎用のgeneral-purposeに加えて、/statusline用のstatusline-setup（Sonnet）と、Claude Code自体の機能をQ&Aするclaude-code-guide（Haiku）があります。ExploreとPlanは、探索を速く安く保つために、あえてCLAUDE.mdと親のgit statusを読み飛ばして動きます。
もうひとつ大きな訂正です。初版はExploreを「Haikuモデル」と断定していましたが、v2.1.198以降、Exploreは常時Haikuではなくなりました。Claude APIではメイン会話のモデルを継承し、上限はOpusです。BedrockやGoogle Cloud Agent Platform、Microsoft Foundry、Claude Platform on AWSでは、メインのモデルをそのまま継承します。もし探索を安く抑えたいなら、model: haikuを指定した自作のExploreを用意する、という運用になります。「Exploreは軽いモデルだから安い」という思い込みは、いったん捨ててください。
modelに指定できる値も広がりました。sonnetだけでなくopus、haiku、fable、あるいはclaude-opus-4-8やclaude-sonnet-5のようなフルID、そしてinherit（親のモデルを継承。これが既定）が使えます。権限はpermissionModeで制御でき、default、acceptEdits、plan、bypassPermissionsなどを指定します（v2.1.200でmanualも追加されました）。ツールはtoolsで許可リスト、disallowedToolsで拒否リストを作れ、mcp__<サーバー名>単位でのMCP制御も可能です。memory: projectのように書けば、サブエージェントにセッションをまたぐ永続的な知識を持たせられます。
使い方の幅も広がっています。--agent <名前>でセッション全体を特定のサブエージェントとして起動できますし、forkで親会話とシステムプロンプトを引き継いで分岐させることもできます。複数を並行して走らせたいときは、agent teamsやバックグラウンドエージェント（agent-view）で束ねます。挙動を止めたいときのために環境変数も用意されていて、CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1（v2.1.198以降）でExplore/Planを、ヘッドレスやSDK環境ではCLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1で組み込みエージェントを無効化できます。
settings.jsonとhooks。「文脈」と「強制」を切り分ける
.claude/settings.jsonは、Claudeの設定と行動範囲を定めるファイルです。permissionsだけでなく、環境変数、サンドボックス、ログイン方式、disableBundledSkillsなど、挙動全体をここで管理します。スコープは3層です。
| スコープ | ファイル | 影響範囲 | チーム共有 |
|---|---|---|---|
| ユーザー | ~/.claude/settings.json |
自分の全プロジェクト | いいえ |
| プロジェクト | .claude/settings.json |
このリポジトリの全員 | はい（Git管理） |
| ローカル | .claude/settings.local.json |
自分だけ | いいえ（gitignore） |
{
"permissions": {
"allow": ["Bash(npm test)", "Bash(npm run build)", "Read", "Grep"],
"deny": ["Bash(rm *)", "Agent(Explore)"]
}
}
ここで初版の表現を精密化しておきます。初版はsettings.jsonを「法的拘束力のあるルール」と書きました。方向としては正しいのですが、公式の枠組みを補うともっと正確になります。公式はこう言っています。CLAUDE.mdやオートメモリはあくまで文脈（context）であって、強制される設定ではない。ある操作を確実にブロックしたいなら、PreToolUseフックかpermissions.denyを使え、と。つまり「お願い」と「強制」はレイヤーが違うのです。「rm -rfは絶対にやらないで」とCLAUDE.mdに100回書いても、それは強い願いにすぎません。本当に止めたいならpermissions.denyに入れるか、フックで弾く。これが正しい設計です。
そのフック（hooks）は、初版で触れられていなかった重要な仕組みです。PreToolUseはツール実行の前に割り込んで許可や拒否を判定でき、PostToolUseは実行後に検証やフォーマットをかけられます。InstructionsLoadedは、どの指示ファイルが読み込まれたかをログに残すのに使えます。CLAUDE.mdが「守ってほしい方針」を伝える層だとすれば、hooksとpermissionsは「絶対に守らせる」層です。この2層を意識して設計すると、AIに任せる範囲を安全に広げられます。
外部ツール連携のMCPも、settingsと並んで押さえておきたい要素です。スコープは3種類あります。localスコープ（~/.claude.json、旧称project）は自分だけ、projectスコープ（プロジェクトルートの.mcp.json）はチーム共有、userスコープ（~/.claude.json、旧称global）は全プロジェクト向けです。トランスポートでstreamable-httpと書いても、これはhttpのエイリアスなので同じものです。名称が過去に変わっている点だけ、古い記事を読むときに注意してください。
オートメモリ。Claudeが自分で学びをためる仕組み
オートメモリは、開発者が何も書かなくても、Claudeが学んだことをメモとして保存する機能です。保存先は~/.claude/projects/<プロジェクト>/memory/で、入口となるMEMORY.mdと、トピック別の詳細ファイルで構成されます。
~/.claude/projects/<プロジェクト>/memory/
├── MEMORY.md # インデックス（毎セッション冒頭で読み込み）
├── debugging.md # デバッグパターンのメモ
└── api-conventions.md # API設計上の判断メモ
ここも初版の説明が不完全でした。初版は「MEMORY.mdの先頭200行が読み込まれる」と書きましたが、正しくは「先頭200行、または25KBのいずれか早い方」です。25KBの容量上限が抜けていました。どちらかの閾値に達した時点で、それ以降はセッション開始時に読み込まれません。だからClaudeはMEMORY.mdを短く保ち、詳細は別ファイルに逃がす設計になっています。
この上限まわりは、2026年に入って挙動が細かく整いました。v2.1.210では、MEMORY.mdが上限に近い、あるいは超えると、Claude Codeが短縮を促すようになりました。上限を超えた状態で書き込むと、書き込み自体は成功するものの「インデックスを書き直せ」というエラーが返ります。超過分は次回ロードで欠落してしまうためです。さらにv2.1.211では、MEMORY.mdのYAMLフロントマターとブロックHTMLコメントが200行・25KBの計測対象から外れ、実際に読み込まれる本文だけが計測されるようになりました。メタ情報のせいで本文が押し出される、という無駄がなくなったわけです。
オートメモリは制御もできます。丸ごと止めたいなら環境変数CLAUDE_CODE_DISABLE_AUTO_MEMORY=1、設定で切り替えるならautoMemoryEnabled、保存先を変えたいならautoMemoryDirectoryを使います。サブエージェントのmemoryは親とは分離できるので、レビュー専用エージェントの学びが本体を汚さないように設計できます。中身は普通のMarkdownなので、人間がいつでも読んで直せます。セッション中に/memoryと打てば、一覧の確認や編集、オン・オフの切り替えができます。
運用でつまずかないために。/context・/memory・/doctorと、/compactの落とし穴
ここまでは設定の話でしたが、実務では「設定したものが本当に効いているか」を確かめる運用のほうが大事です。初版はこの視点が薄かったので、最後に運用コマンドを整理します。
/contextは、いま何が読み込まれているかを確認するコマンドです。CLAUDE.md、rules、スキル、メモリのうち、どれが実際にコンテキストに載っているかが見えます。/memoryはオートメモリの一覧・編集・オンオフに使い、/doctorは前述のとおりCLAUDE.mdのトリムまで面倒を見てくれます。InstructionsLoadedフックを仕込めば、どの指示が読み込まれたかをログとして残せます。「書いたはずのルールが効かない」というトラブルの多くは、そもそも読み込まれていないのが原因なので、まず/contextで確認する癖をつけるとよいです。
もうひとつ、長い作業で必ず出会うのが/compactの挙動です。会話が長くなって圧縮（compact）がかかると、その会話の中だけで口頭で与えた指示は失われます。ただしプロジェクトルートのCLAUDE.mdはディスクから再読込・再注入されるので消えません。ネストされたCLAUDE.mdも、そのサブディレクトリのファイルを再び読むときに再ロードされます。つまり「セッション内で言った一時的なお願い」は消えるが「ファイルに書いた指示」は残る、という線引きです。ここを理解しておくと、長時間のセッションで指示が抜け落ちても慌てずにすみます。守らせ続けたい指示は、必ずファイルに落とす。これが鉄則です。
初めて.claudeを整える方への導入手順も、あらためて示します。まずセッション内で/initを実行します。コードベースを分析して、ビルドコマンド、テスト手順、慣習を反映した初期のCLAUDE.mdを自動生成してくれます（新しい対話型initを試すなら環境変数CLAUDE_CODE_NEW_INIT=1）。次に、生成物をレビューして、Claudeが自力では気づけない情報を足します。アーキテクチャ上の判断理由、チーム固有のワークフロー、外部サービス連携のルールなどです。その後、繰り返す作業をスキル化し、最後にsettings.jsonのpermissionsとhooksで危険な操作を封じます。
2026年後半に定着した周辺要素にも触れておきます。.claude/workflows/は、複数のサブエージェントをスクリプトで決定的にオーケストレーションするDynamic Workflowsの保存先で、定型フローを名前で呼び出して再実行できます。詳しくはDynamic Workflowsの解説記事をどうぞ。あわせて、~/.claude/keybindings.jsonによるキーバインドの管理、.claude/worktrees/を使ったGitワークツリーでの隔離作業（バージョン管理からは除外が定石）も、環境の再現性と並列作業の安全性を高めてくれます。plugins・マーケットプレイスやoutput styles、status lineといった拡張も、この.claudeエコシステムの一部として広がってきました。
.claudeの設定は一度作って終わりではありません。プロジェクトの成長に合わせて更新し続けるものです。月に一度でいいので、/doctorでCLAUDE.mdを点検し、/contextで読み込み状況を確かめる時間を取ってみてください。半年前の私自身が誤った数字を書いていたように、この領域は動きが速く、昨日の正解が今日は不正解になります。だからこそ、公式ドキュメントの一次情報に当たり続けることが、いちばん確実なプロンプトエンジニアリングなのだと思います [1] [2] [3] [4] [5] [6] [7]。
参考文献
[1] Claude Code Docs. "How Claude remembers your project (CLAUDE.md & auto memory)." https://code.claude.com/docs/en/memory （2026-07）
[2] Claude Code Docs. "Extend Claude with skills." https://code.claude.com/docs/en/skills （2026-07）
[3] Claude Code Docs. "Create custom subagents." https://code.claude.com/docs/en/sub-agents （2026-07）
[4] Claude Code Docs. "Connect Claude Code to tools via MCP." https://code.claude.com/docs/en/mcp （2026-07）
[5] Claude Code Docs. "Claude Code settings." https://code.claude.com/docs/en/settings （2026-07）
[6] Claude Code Docs. "Documentation index (llms.txt)." https://code.claude.com/docs/llms.txt （2026-07）
[7] Agent Skills open standard. https://agentskills.io （2026-07）
