メインコンテンツへスキップ
見出し画像

【完全ガイド】Claude Codeの.claudeフォルダを理解すれば、AIの動きが変わる

    はじめに

    画像

    Claude Codeを使っていると、プロジェクトルートに .claude/ というフォルダが自動的に作られることに気づくと思います。中を開いたことはありますか?

    実はこのフォルダ、Claude Codeの動作を制御するコントロールセンターです。ここにある設定ファイル次第で、Claudeの挙動は劇的に変わります。指示の精度、コマンドの許可範囲、チーム共有のルール、さらにはセッションをまたいだ記憶まで。

    この記事では、Akshay氏(@akshay_pachaar)の「Anatomy of the .claude/ folder」という素晴らしい解説をベースに、.claude/ フォルダの全体像を日本語で整理します。


    実は2つある:プロジェクトとグローバル

    まず最初に知っておくべきこと。.claude/ フォルダは2箇所に存在します。

    プロジェクトレベル(your-project/.claude/)

    • チーム全員に共有される設定

    • gitにコミットして管理

    • カスタムコマンド、ルール、パーミッション

    グローバル(~/.claude/)

    • 個人の設定、全プロジェクト共通

    • セッション履歴、自動メモリ

    • 個人用コマンドやスキル

    この2層構造を理解しておくと、「チームで共有すべき設定」と「自分だけの設定」を適切に分けられます。


    CLAUDE.md:最も重要な1ファイル

    Claude Codeが起動したとき、最初に読み込むのが CLAUDE.md です。ここに書かれた内容はシステムプロンプトに組み込まれ、セッション全体を通してClaudeの行動指針になります。

    つまり、CLAUDE.mdに「テストを書いてから実装すること」と書けば、Claudeはその通りに動きます。「console.logではなくカスタムロガーを使うこと」と書けば、毎回それを守ります。

    CLAUDE.mdの配置場所

    CLAUDE.mdは3箇所に置けます。

    • プロジェクトルート(./CLAUDE.md): 最も一般的。チーム共有

    • グローバル(~/.claude/CLAUDE.md): 全プロジェクト共通の個人設定

    • サブディレクトリ内: フォルダ固有のルール

    Claudeはこれらすべてを読み込んで統合します。

    何を書くべきか

    書くべきもの:

    • ビルド・テスト・リントのコマンド(npm run test、make build など)

    • アーキテクチャの重要な決定(「Turborepoのモノレポ構成」など)

    • 非自明な注意点(「TypeScript strictモードON、未使用変数はエラー」など)

    • import規則、命名パターン、エラーハンドリングのスタイル

    書くべきでないもの:

    • リンターやフォーマッターの設定ファイルに書くべきもの

    • 長い理論の説明

    • リンクで参照できるドキュメント

    CLAUDE.mdは200行以下に抑えましょう。 長すぎるとコンテキストを圧迫し、逆にClaudeの指示遵守率が下がります。

    実例:ミニマルだけど効果的なCLAUDE.md

    # Project: Acme API
    
    ## Commands
    npm run dev          # 開発サーバー起動
    npm run test         # テスト実行(Jest)
    npm run lint         # ESLint + Prettier
    npm run build        # 本番ビルド
    
    ## Architecture
    - Express REST API, Node 20
    - PostgreSQL via Prisma ORM
    - ハンドラは src/handlers/ に配置
    - 共有型定義は src/types/
    
    ## Conventions
    - リクエストバリデーションはzodを使用
    - レスポンス形式は常に { data, error }
    - スタックトレースをクライアントに返さない
    - console.logではなくloggerモジュールを使用
    
    ## Watch out for
    - テストはモックではなくローカルDBを使用
    - 先に npm run db:test:reset を実行すること
    - TypeScript strict: 未使用importは常にエラー

    たった20行程度ですが、Claudeがこのプロジェクトで効果的に作業するのに十分な情報が揃っています。


    CLAUDE.local.md:個人のオーバーライド

    チームの設定とは別に、自分だけのカスタマイズをしたい場合があります。たとえば、好みのテストランナーを使いたい、特定のパターンでファイルを開きたい、といった場合です。

    プロジェクトルートに CLAUDE.local.md を作成してください。Claudeは CLAUDE.md と一緒にこのファイルも読み込みますが、自動的にgitignoreされるので、個人設定がリポジトリに入ることはありません。


    rules/ フォルダ:モジュール化された指示

    画像

    CLAUDE.mdが300行を超え始めたら、rules/ フォルダの出番です。

    .claude/rules/ 内のすべてのMarkdownファイルは、CLAUDE.mdと一緒に自動的に読み込まれます。巨大な1ファイルではなく、関心事ごとに分割できます。

    .claude/rules/
    ├── code-style.md
    ├── testing.md
    ├── api-conventions.md
    └── security.md

    それぞれのファイルが独立しているので、APIの規約はAPI担当が、テスト基準はテスト担当がそれぞれ編集できます。

    パススコープで条件付きルール

    YAMLフロントマターを使うと、特定のファイルを編集しているときだけルールを有効にできます。

    ---
    paths:
      - "src/api/**/*.ts"
      - "src/handlers/**/*.ts"
    ---
    # API設計ルール
    
    - ハンドラは { data, error } 形式で返す
    - リクエストボディのバリデーションにはzodを使用
    - 内部エラーの詳細をクライアントに返さない

    Reactコンポーネントを編集しているときには、このルールは読み込まれません。src/api/ や src/handlers/ 内のファイルを触っているときだけ有効になります。


    commands/ フォルダ:カスタムスラッシュコマンド

    Claude Codeには /help や /compact などの組み込みコマンドがありますが、commands/ フォルダで自分だけのコマンドを追加できます。

    .claude/commands/ にMarkdownファイルを置くだけ。ファイル名がそのままコマンド名になります。

    • review.md → /project:review

    • fix-issue.md → /project:fix-issue

    実例:コードレビューコマンド

    ---
    description: マージ前にブランチの差分をレビュー
    ---
    ## レビュー対象の変更
    
    !`git diff --name-only main...HEAD`
    
    ## 詳細差分
    
    !`git diff main...HEAD`
    
    上記の変更を以下の観点でレビューしてください:
    1. コード品質
    2. セキュリティ脆弱性
    3. テストカバレッジの不足
    4. パフォーマンスの問題
    
    ファイルごとに具体的で実行可能なフィードバックをください。

    ! バッククォート記法でシェルコマンドの結果が自動的にプロンプトに埋め込まれます。これが単なるテンプレートではなく、コマンドが強力な理由です。

    引数を渡す

    $ARGUMENTS を使えば、コマンド実行時にテキストを渡せます。

    ---
    description: GitHubのIssueを調査して修正
    argument-hint: [issue-number]
    ---
    issue #$ARGUMENTS を調査してください。
    
    !`gh issue view $ARGUMENTS`
    
    バグの根本原因を特定し、修正し、
    それを検出できるテストを書いてください。

    /project:fix-issue 234 で、Issue #234の内容が自動的に取り込まれます。

    プロジェクト vs 個人コマンド

    • .claude/commands/ → チーム共有(/project:xxx)

    • ~/.claude/commands/ → 個人用(/user:xxx)


    skills/ フォルダ:自動で発動するワークフロー

    画像

    コマンドとスキルの違いはトリガーの仕方です。

    • コマンド: ユーザーがスラッシュコマンドで明示的に呼び出す

    • スキル: Claudeが会話の文脈を見て、タスクにマッチしたら自動的に発動する

    スキルは .claude/skills/ 内にサブディレクトリとして配置します。

    .claude/skills/
    ├── security-review/
    │   ├── SKILL.md
    │   └── DETAILED_GUIDE.md
    └── deploy/
        ├── SKILL.md
        └── templates/
            └── release-notes.md

    SKILL.mdの例

    ---
    name: security-review
    description: セキュリティ監査。コードの脆弱性レビュー、
      デプロイ前チェック、セキュリティに関する話題で使用。
    allowed-tools: Read, Grep, Glob
    ---
    コードベースのセキュリティ脆弱性を分析:
    
    1. SQLインジェクション・XSSリスク
    2. 認証情報やシークレットの露出
    3. 安全でない設定
    4. 認証・認可のギャップ
    
    @DETAILED_GUIDE.md のセキュリティ基準に従って報告。

    「このPRのセキュリティをレビューして」と言うだけで、Claudeがdescriptionを読み、マッチすると判断してスキルを自動発動します。

    コマンドとの最大の違い: スキルは関連ファイルをバンドルできます。@DETAILED_GUIDE.md のように、隣に置いたファイルを参照できます。コマンドは単一ファイルですが、スキルはパッケージです。


    agents/ フォルダ:専門家サブエージェント

    タスクが十分に複雑で、専門家に任せたい場合は、.claude/agents/ にサブエージェントを定義できます。

    ---
    name: code-reviewer
    description: コードレビューの専門家。PR確認やバグチェック時に
      プロアクティブに使用。
    model: sonnet
    tools: Read, Grep, Glob
    ---
    あなたはシニアコードレビュアーです。
    
    レビュー時:
    - スタイルではなくバグを指摘
    - 漠然とした改善ではなく具体的な修正案を提示
    - エッジケースとエラーハンドリングの確認
    - パフォーマンスはスケール時に問題になる場合のみ指摘

    ポイントは:

    • tools でエージェントのアクセス権を制限(セキュリティ監査にファイル書き込みは不要)

    • model で適切なモデルを選択(読み取り専用の探索にはHaikuで十分。重い作業にはSonnet/Opus)

    • メインセッションのコンテキストを汚さない(エージェントは独立したコンテキストで動作)


    settings.json:パーミッションの管理

    .claude/settings.json は、Claudeに何を許可し何を禁止するかを制御します。

    {
      "permissions": {
        "allow": [
          "Bash(npm run *)",
          "Bash(git status)",
          "Bash(git diff *)",
          "Read",
          "Write",
          "Edit"
        ],
        "deny": [
          "Bash(rm -rf *)",
          "Bash(curl *)",
          "Read(./.env)",
          "Read(./.env.*)"
        ]
      }
    }
    • allow: 確認なしで自動実行される操作

    • deny: 完全にブロックされる操作

    • どちらにも該当しない: Claudeが実行前に確認を求める

    この3層構造が大事です。すべてを予測してallow/denyに入れる必要はなく、不明なものはClaudeが聞いてくれます。

    settings.local.json を作れば、個人用のパーミッション上書きも可能です(自動gitignore)。


    グローバル ~/.claude/ の中身

    画像

    普段あまり触らないファイルですが、知っておくと便利です。

    • ~/.claude/CLAUDE.md: 全プロジェクト共通の個人指示

    • ~/.claude/projects/: プロジェクトごとのセッション履歴と自動メモリ。/memory コマンドで閲覧・編集可能

    • ~/.claude/commands/: 個人用カスタムコマンド(全プロジェクトで使用可能)

    • ~/.claude/skills/: 個人用スキル

    • ~/.claude/agents/: 個人用エージェント

    Claudeが「教えていないはずのこと」を覚えている場合、projects/ の自動メモリに保存されている可能性があります。


    実践:ゼロから始める5ステップ

    最後に、これからセットアップする人のための段階的なガイドです。

    Step 1: Claude Codeで /init を実行。プロジェクトを読み取ってCLAUDE.mdのひな形を自動生成してくれます。必要最小限に編集しましょう。

    Step 2: .claude/settings.json にallow/denyルールを追加。最低限、ビルドコマンドの許可と .env の読み取り禁止を設定。

    Step 3: よく使うワークフローをコマンド化。コードレビューとIssue修正がおすすめの出発点。

    Step 4: CLAUDE.mdが長くなったら、.claude/rules/ に分割。パスでスコープするとさらに効果的。

    Step 5: ~/.claude/CLAUDE.md に個人的なコーディング原則を記載。「常に型定義から書く」「クラスよりも関数型パターンを好む」など。

    ここまでで95%のプロジェクトには十分です。スキルとエージェントは、繰り返し発生する複雑なワークフローをパッケージ化したくなったときに導入しましょう。


    まとめ

    • .claude/ フォルダはプロジェクトレベルとグローバル(~/.claude/)の2箇所に存在する

    • CLAUDE.md が最もレバレッジの高いファイル。まずここを整えることが最優先

    • rules/ でCLAUDE.mdをモジュール分割し、パススコープで必要な場面だけ適用できる

    • commands/ でチーム共有のワークフローをスラッシュコマンド化

    • skills/ はコマンドと違い、Claudeが文脈に応じて自動発動するパッケージ型ワークフロー

    • agents/ で専門家サブエージェントを定義し、複雑なタスクを分離して処理

    • settings.json のallow/denyで、安全性と自動化のバランスを制御

    • 小さく始めて、必要に応じて育てていくのが最も効率的なアプローチ

    .claudeフォルダは、「Claudeに自分たちのプロジェクトをどう理解してもらうか」を定義するプロトコルです。明確に定義すればするほど、Claudeの修正に費やす時間が減り、本来の仕事に集中できるようになります。

    元記事: Akshay氏 (@akshay_pachaar) の「Anatomy of the .claude/ folder」

     
     
    1人でAIを使って、複数事業を丸ごと回しています。 業種横断でAI導入を多数支援し、現場の業務を月100時間規模で自動化。月間5万人超のAIメディアを運営。 AIで会社を回す実運用と、ビジネスに活用できるAI情報を発信します。

    あなたへのおすすめ