【入門】.claudeフォルダの構造と使い方 Claude Codeを思い通りに動かそう：Deep Insider AI Practice
Claude Codeを使い始めたものの、プロジェクト内に生成される「.claude」フォルダをそのままにしていませんか？ 実はこのフォルダこそが、Claude Codeの振る舞いを決定づける重要なポイントです。このフォルダの構造と役割を整理し、初心者の方でも理解できるように解説します。
この記事は会員限定です。会員登録（無料）すると全てご覧いただけます。
Claude Codeを使い始めると、多くの人がすぐにプロンプトを書き始めます。.claudeフォルダの存在を知らないまま、あるいは後回しにしたまま使い続けてしまうのです。その結果、「毎回同じ指示を繰り返す」「プロジェクトに合わせた動きをしてくれない」といった非効率に陥りがちです。
こうした非効率に心当たりがあるなら、.claudeフォルダを使い倒すのがお勧めです。多くのユーザーはこのフォルダを「何となく存在は知っているが、触ったことがない」場所として見過ごしがちです。しかし実はそれこそが、Claude Codeの挙動を決定する司令塔なのです。
このフォルダには、Claude Codeの動きを細かくコントロールするための仕組みが詰まっています。これらを正しく構成することで、Claude Codeは単なるAIコーディングツールではなく、プロジェクトのルールや背景を理解したチームメンバーのような存在として機能するようになります。
本稿では、.claudeフォルダを十分に活用できていない方に向けて、その構成を「指示書」「権限管理＋設定」「コマンド」「ルール」「スキル」「エージェント」という6つの役割に分けて解説します。この記事を読み終える頃には、「まず何から設定すればよいか」が明確になっているはずです。
図1 .claudeフォルダの全体構造イメージプロジェクト単位の設定例です。この他にPC全体で共有できるグローバル設定も存在します。
※この画像は、Akshay（アクシャイ）氏（@akshay_pachaar）のXポストに掲載された図を引用して加工したものです。
なぜ「.claude」フォルダが重要なのか
通常、Claude Codeに何かを頼むときは、「変数名はキャメルケース（単語の先頭を大文字にする書き方）で」「テストは必ず実装前に書いて」といった指示を毎回プロンプトに含める必要があります。しかし、これでは非効率で、指示を忘れるとコードの品質や進め方がバラバラになってしまいます。
.claudeフォルダの中にルールや指示のファイルを置いておけば、Claude Codeはそれらを必要なタイミングで自動的に読み込みます。毎回プロンプトに書かなくても、プロジェクトのルールや作業の進め方をClaude Codeがあらかじめ把握している状態になります。つまり、「言わなくても分かっている状態」を作り出せるのです。
ここで押さえておきたいのが、.claudeフォルダには2種類の置き場所があるという点です。
- .claude/（プロジェクト内）： チーム全員で共有するルールや指示。Git（ソースコードの変更履歴管理システム）にコミットして全員で使います。
- ~/.claude/（ホームディレクトリ）： 自分だけのルールや指示。どのプロジェクトを開いても適用される「自分流の作法」をまとめておけます。
今回はプロジェクト内の.claudeフォルダに絞って解説します。なお、後述するCLAUDE.mdファイルは、.claudeフォルダ内ではなく基本的にプロジェクトルート直下に配置しますが、関連ファイルとして併せて解説します。
「.claude」フォルダ内の中身と「CLAUDE.md」ファイルを理解しよう
それでは、フォルダの中身とCLAUDE.mdファイルを具体的に見ていきましょう。
1. メイン指示書： CLAUDE.mdファイル
プロジェクトのルートに置く、プロジェクト全体に関する指示書です。Claude Codeがセッションを開始すると、自動的に読み込まれます。つまり、会話の最初から内容が反映された状態でやりとりが始まります。
ここには「ビルド方法」「テストの実行コマンド」「絶対守ってほしい設計ルール」などを書きます。書いた内容はClaude Codeが必ず守るため、毎回同じ指示をプロンプトに書く手間がなくなります。リスト1はMarkdown（マークダウン）形式で記述するCLAUDE.mdファイルの例です。
# プロジェクト： サンプルAPI
## コマンド
uv run uvicorn main:app --reload
uv run pytest
uv run python -m build
## アーキテクチャ
- Python（FastAPIフレームワーク）を使用
- `src/` ディレクトリにアプリ本体
- `tests/` ディレクトリにテストコード
## 基本ルール
- 型ヒントを必ず付ける
- エラーハンドリングは例外で統一
- ログは`logging`モジュールを使用
CLAUDE.mdは複数の場所に置くことができ、以下の順番で読み込まれます。
- Managed Policy（管理ポリシー）： 組織全体に適用されるポリシー。IT管理者が設定するもので、他の設定で上書きすることはできません。
- ~/.claude/CLAUDE.md： 個人用のグローバル指示書。全てのプロジェクトに共通して適用される指示をまとめます。
- プロジェクトルートのCLAUDE.md： チーム用のプロジェクト指示書。そのプロジェクト全体に適用され、Gitで管理してチームで共有します。
- CLAUDE.local.md： 個人用のプロジェクト指示書。個人専用の設定を追加／カスタマイズできます。Claude CodeによりGit管理から自動的に除外されます。
優先度は下にいくほど高く（Managed Policyを除く）、内容が競合した場合は上位のファイルの指示が優先されます。これらはセッション開始時に自動で読み込まれ、Claude Codeに渡されます。
なお、~/はユーザーのホームディレクトリを指します。Windowsの場合はエクスプローラーのアドレスバーに%USERPROFILE%と入力すると開けます。
2. 権限管理＋設定： settings.jsonファイル
Claude Codeが「できること・できないこと」を定義する、つまりAIの行動範囲を制御するためのファイルです。具体的には、ファイルの読み書きやコマンド実行など、許可する操作と禁止する操作をリストで指定できます。
設定は大きく、
- allow（許可する操作）
- deny（禁止する操作）
- ask（確認を求める操作）、または未指定（どのルールにも一致しない操作）
の3つに分かれます。例えば、日常的に使うnpm run *やgit statusは許可しつつ、rm -rf *のような危険なコマンドや、.envのような機密ファイルの読み取りは拒否するといった形です。askや未指定の操作については、実行前にClaude Codeが確認を求めてきます。リスト2はその構成例です。
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git status)",
"Bash(git diff *)",
"Read",
"Write",
"Edit"
],
"deny": [
"Bash(rm -rf *)",
"Read(./.env)",
"Read(./.env.*)"
]
}
}
明示的に指定した場合の評価はdeny→ask→allowの順に行われ、最初にマッチしたルールが適用されます。どのルールにも該当しない未指定の操作は、デフォルトの動作として確認を求めてきます。
ここで重要なのは、「何をさせるか」よりも「何をさせないか」を決めるという考え方です。AIは強力な分、誤った操作をすると影響も大きくなります。逆に、適切に制限しておけば、安心して自動化を任せられるようになります。
また、チームで共有する.claude/settings.jsonファイルの他に、個人用の.claude/settings.local.jsonファイルも用意されています。後者の個人用はClaude CodeによりGit管理から自動的に除外されるため、自分だけの権限設定や実験的な変更を安全に試すことができます。
まずは、.envなどの機密ファイルを"deny"に入れる、危険なコマンドを禁止する、といった最低限の設定から始めてみてください。それだけでも、Claude Codeが「より安心して使える」ようになります。
3. カスタムコマンド： commands/
独自のスラッシュコマンド（/で始まる命令）を作るためのフォルダです。ただし、commands/フォルダは非推奨（旧形式）となっており、後述するskills/フォルダの利用が推奨されています。スキルも同様にスラッシュコマンドとして呼び出せるため、新規作成にはskills/を使ってください。ここでは互換性のために紹介します。
.claude/commands/内にMarkdownファイル（.mdファイル）を置くだけで、そのファイル名がコマンド名になります。例えばcode-review.mdというファイルを作ると、/code-reviewというコマンドが使えるようになります。内容には、レビューの観点やチェック項目、実行したい処理などをあらかじめ定義しておくことで、同じ処理をコマンド1つで実行できるようになります。
なお、コマンド用のMarkdownファイル（例：code-review.mdファイル）の作り方は、後述のSKILL.mdファイルと基本的に共通するため、ここでは説明を割愛します。
4. ルール集： rules/
メイン指示書（CLAUDE.mdファイル）の内容が増えてきたときに、そのファイル内容（ルールや実行手順、注意書きなど）を役割ごとに分割して管理できるフォルダです。.claude/rules/フォルダ内のMarkdownファイルは、CLAUDE.mdと同様に自動的に読み込まれます。
例えば、
- code-style.mdファイルにコーディング規約
- testing.mdファイルにテストのルール
- api-conventions.mdファイルにAPI設計のルール
といった形で分割できます。ファイルごとに担当を分けて個別に編集できるようになるため、チームでも分担して管理しやすくなります。実際の記述例はリスト3の通りです。
# コーディング規約
- 変数名はスネークケース（snake_case）で統一する
- 未使用の変数は許可しない
- ログ出力はloggingモジュールを使用する
- エラーハンドリングは例外で統一する
さらに、特定のフォルダ内のファイルを編集しているときだけ有効になるルールも設定できます。具体的には、ファイルの先頭に条件（対象パス）を指定することで、適用範囲を限定できます（リスト4）。
---
paths:
- "src/api/**/*.py"
- "src/handlers/**/*.py"
---
# API設計ルール
- レスポンスは必要に応じてPydanticライブラリのモデルで定義する
- リクエストの入力値は必ずバリデーションを行う
- 内部エラーの詳細は外部に公開しない
- エンドポイントでは型ヒントを付ける
---で囲まれた部分はYAML形式で記述されており、ルールの適用対象となるパスを指定しています。
このようにルールを分割して管理することで、必要なときに必要なルールだけが適用されるようになります。プロジェクトが大きくなっても、ルールの追加や変更に対応しやすくなります。
5. 自動呼び出しスキル： skills/
カスタムコマンドと似ていますが、ユーザーが命令しなくてもClaude Codeが状況を判断して自動的に呼び出すワークフローです。また、/から始まるスラッシュコマンドとして明示的に呼び出すこともできます。各スキルは、それぞれ専用のフォルダ（例：.claude/skills/code-review/）にSKILL.mdという名前のファイルとして定義します。
SKILL.mdには、そのスキルをいつ使うべきかと何をするかを書きます。例えば「コードレビューが必要なとき」と書いておけば、ユーザーがレビューを依頼したり、変更内容の確認を求めたりした際に、Claude Codeが自動でそのスキルを呼び出します。スキルの基本的な定義は、リスト5のように書きます。
---
name: code-review
description: コードレビューを行う。変更内容の確認や品質チェックが必要なときに使用する。
allowed-tools: Read, Grep, Glob
---
# コードレビュー
以下の観点で変更内容をレビューしてください。
## チェック項目
- バグや不具合の可能性はないか
- 可読性や命名に問題はないか
- 不要な処理や重複はないか
- エラーハンドリングは適切か
## 出力形式
- 問題点
- 修正案
- 総評
allowed-tools（使用可能なツール）には、Read（ファイル読み込み）、Grep（テキスト検索）、Glob（ファイルパス探索）などを指定します。
このように定義しておくことで、文脈に応じて適切なスキルが自動的に呼び出されるようになります。まずは1つ、コードレビューやログ分析などよく行う作業をスキルとして定義してみてください。それだけでも、Claude Codeでの作業が一段と効率的になります。
6. 専門エージェント： agents/
特定業務に特化した専門性を持つAIエージェントを“サブエージェント”として定義するフォルダです。「コードレビューの専門家」「セキュリティ監査の専門家」といった役割を持つエージェントを作成できます。
サブエージェントはメインの会話とは切り離された独立したコンテキストで動作します。そのため、大量のコードを解析させてもメインのチャットに影響が出にくいというメリットがあります。また、エージェントごとに使用できるツールやAIモデルを設定できるため、用途に応じた効率的な運用が可能です。
各エージェントは.claude/agents/フォルダ内にMarkdownファイル（例：security-auditor.md）として配置します。例えば、コードのセキュリティ上の問題をチェックするエージェントはリスト6のように定義します。
---
name: security-auditor
description: セキュリティ観点でコードを監査し、脆弱性やリスクを指摘する
allowed-tools: Read, Grep, Glob
model: claude-opus-4-6
---
# セキュリティ監査エージェント
コード全体をセキュリティ観点でチェックしてください。
## チェック項目
- 入力値のバリデーションが適切に行われているか
- 機密情報（APIキーなど）がハードコードされていないか
- 権限チェックや認証処理に問題がないか
- 想定外入力による脆弱（ぜいじゃく）性（インジェクションなど）がないか
## 出力形式
- 検出されたリスク
- 改善案
- 重大度（高／中／低）
model（モデル）には、モデル種別（例：sonnet／opus／haiku）や、完全なモデルID（例：claude-opus-4-6）などを指定します。
専門分野ごとに担当するエージェントを分けることで、目的に応じた専門的な処理を安定して実行できるようになります。例えば「セキュリティチェックは“セキュリティ監査エージェント”に任せる」といった形で作業を分担することで、より高度で確実なセキュリティチェックができるようになります。
まずは1つ、セキュリティチェックやコードレビューなど役割が明確な作業をエージェントとして切り出してみてください。「セキュリティ監査エージェントを使ってチェックして」といったプロンプトで活用できます。
まとめ： Claude Codeをもっと使いこなそう
ここまで、Claude Codeにおける.claudeフォルダの構造と役割を解説してきました。重要なのは、Claude Codeをプロンプトでそのまま使うだけでなく、ルールやワークフロー、エージェントなどの設定を少しずつ整えていくことで、より適切な振る舞いを引き出していくという発想です。
具体的には、
- CLAUDE.mdファイルで、プロジェクト全体に関わる共通的な指示を定義
- .claude/settings.jsonファイルで、権限管理＋設定を制御
- .claude/rules/フォルダで、役割ごとにルールや実行手順、注意書きなどを整理
- .claude/skills/フォルダで、自動的に呼び出されるワークフロー処理を定義
- .claude/agents/フォルダで、特定業務に特化したサブエージェントを定義し、役割を分担
していきます。こうした構造をあらかじめ用意し、徐々に育てていくことで、AIコーディングをより安定させることができます。
まずはCLAUDE.mdとsettings.jsonから始め、必要に応じてrules/やskills/、agents/といったフォルダを追加していきましょう。本稿が、その第一歩になれば幸いです。
Deep Insider編集長の一色です。こんにちは。
私自身もClaude Codeを使って日々開発していますが、正直に言うと.claudeフォルダについては、これまで十分に使いこなせていませんでした。プロンプトで指示すれば動くため、それで満足してしまっていた部分もあります。
しかし今回あらためて整理してみると、Claude Codeの能力や魅力を十分に引き出せていなかったことがよく分かりました。.claudeフォルダを育てていくことが、より良い開発につながるはずです。ぜひ皆さんもこの記事をきっかけに取り組んでみてください。
また最近は私自身も、OpenAI Codex CLIでサブエージェント（Subagent）機能を試したり、Claude Codeでエージェントチーム（Agent Teams）機能を触ってみたりと、複数のエージェントを組み合わせた開発を模索しています。そうした活用の土台としても、まずはagents/フォルダでサブエージェントを定義し、役割ごとに分けて扱うことに慣れておくことをお勧めします。
次の一歩： .claudeフォルダを作って、AIと一緒に育てる
※この記事の内容を実際に手を動かして試してみたい方は、ここから先を読み進めてみてください。以下は、Claude Codeで.claudeフォルダを作り、内容を調整していくための最初のステップです。
まずはClaude Code上で/initコマンドを実行し、CLAUDE.mdファイルのたたき台を生成します。その上で、生成された内容をそのまま使うのではなく、自分のプロジェクトに合わせて調整していきます。
次に、CLAUDE.mdの内容を見ながら、どのように修正／分割すべきかをClaude Codeに相談しながら進めていきます。進め方に迷う場合は、以下のプロンプトから始めてみてください。
Claude Code用の.claudeフォルダ構成を整えたいです。
/initで生成されたCLAUDE.mdをベースに、内容を見直したいと考えています。
まずは一度に全て作るのではなく、次の観点で改善方針を整理してください。
・CLAUDE.mdに追加すべき内容
・rules/に分割した方がよい内容
・settings.jsonで最低限denyすべき項目
・skillsとして切り出せる処理
・agentsとして分担すべき役割
必要であれば質問しながら進めてください。
プロジェクト概要：
（ここに自分の開発内容を書く）
実際に試してみましたが、Claude Codeが1つずつ質問してくれるため、それに回答していくだけでプランを整理しながら進めることができました。比較的取り組みやすいので、ぜひ試してみてください。
情報元
Copyright© Digital Advantage Corp. All Rights Reserved.
アイティメディアからのお知らせ
注目のテーマ
ITmediaはアイティメディア株式会社の登録商標です。