.claude/ フォルダ構造の分析

 (blog.dailydoseofds.com)
65 ポイント 投稿者 GN⁺ 2026-03-28 | 1件のコメント | WhatsAppで共有
  • .claude/ フォルダは Claude Codeの中核制御ディレクトリ であり、プロジェクトごとのルール・コマンド・権限・メモリ状態を管理する
  • CLAUDE.md は Claude の 行動原則とプロジェクトルールを定義する中心ファイル で、複数階層の設定をマージして適用する
  • commands/、skills/、agents/ フォルダはそれぞれ ユーザー定義コマンド、自動ワークフロー、専門サブエージェント を構成し、共同作業の効率を高める
  • settings.json は コマンド実行権限とファイルアクセス範囲 を制御し、settings.local.json によって個人ごとのオーバーライドが可能
  • 全体構造は Claude に プロジェクトのアイデンティティとルールを伝えるプロトコル として機能し、明確な設定が生産性と協業効率を最大化する

.claude/ フォルダ構造と構成要素

  • .claude/ フォルダは Claude Code の動作を制御する中核ディレクトリ であり、プロジェクトごとのルール・コマンド・権限・メモリ状態を管理する
  • プロジェクトルートのフォルダには チーム単位の設定 が含まれ、Git にコミットされる
  • ホームディレクトリ（~/.claude/）のフォルダには 個人設定とセッション記録 が保存され、自動メモリや個人コマンドも含まれる

  • CLAUDE.md — Claude のガイド

    • Claude Code セッション開始時に最初に読むファイルで、Claude の行動原則とプロジェクトルールを定義 する
    • プロジェクトルートの CLAUDE.md はチーム共通ルール、~/.claude/CLAUDE.md は グローバルな個人ルール、下位フォルダの CLAUDE.md は フォルダごとのルール を担当する
    • Claude は複数の CLAUDE.md ファイルを マージして適用 する
    • 推奨内容は、ビルド・テストコマンド、主要なアーキテクチャ判断、直感的ではない制約事項、命名・エラー処理ルールなど
    • 200行以下を維持 することが推奨され、長すぎると Claude の指示順守率が低下する

  • CLAUDE.local.md — 個人別オーバーライド

    • チーム共通ルールとは別に 個人の好みを反映 できるファイル
    • プロジェクトルートに CLAUDE.local.md を作成すると Claude がこれもあわせて読む
    • .gitignore に自動的に含まれ、リポジトリにはコミットされない

  • rules/ フォルダ — モジュール型ルール管理

    • CLAUDE.md が大きくなった場合は .claude/rules/ フォルダへ分離して管理する
    • 各ルールファイルは テーマごとに分割 され、保守しやすい
      • 例: code-style.md、testing.md、api-conventions.md、security.md
    • YAML フロントマターの paths フィールドを使うと 特定パスのみに適用されるルール を指定できる
      • 例: src/api/**/*.ts パスにのみ API ルールを適用
    • パス指定のないルールは、すべてのセッションで常にロードされる

  • commands/ フォルダ — ユーザー定義スラッシュコマンド

    • .claude/commands/ フォルダ内の各 Markdown ファイルは スラッシュコマンド(/) として登録される
      • 例: review.md → /project:review、fix-issue.md → /project:fix-issue
    • ! バックティック構文によって シェルコマンド実行結果を Claude のプロンプトに挿入 できる
      • 例: !git diff main...HEAD
    • $ARGUMENTS 変数を使って、コマンド実行時に 引数を渡す ことができる
      • 例: /project:fix-issue 234 → GitHub Issue 234 の内容を自動ロード
    • プロジェクトコマンドはチームと共有され、個人コマンドは ~/.claude/commands/ に保存されて すべてのプロジェクトで利用可能

  • skills/ フォルダ — 自動実行ワークフロー

    • コマンドに似ているが自動でトリガーされるワークフロー として機能する
    • Claude が会話内容を分析し、適切な状況で自動実行 する
    • 各スキルはサブフォルダ内の SKILL.md ファイルで定義され、YAML フロントマターによって トリガー条件と許可ツール を指定する
      • 例: security-review スキルはセキュリティ関連の会話時に自動実行
    • スキルフォルダには DETAILED_GUIDE.md などの 補助ドキュメントやテンプレートファイル を含められる
    • 個人スキルは ~/.claude/skills/ に保存され、グローバルに利用できる

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

    • .claude/agents/ フォルダには 特定の役割を担うサブエージェント（ペルソナ） を定義する
    • 各エージェントは独立したシステムプロンプト、モデル、ツールアクセス権限を持つ
      • 例: code-reviewer.md、security-auditor.md
    • tools フィールドでアクセス可能なツールを制限し、セキュリティと役割分離 を実現する
    • model フィールドで作業に適した Claude モデル（例: Haiku、Sonnet、Opus）を選択できる
    • Claude は必要に応じて該当エージェントを 別コンテキストで実行 し、結果だけを要約して報告する

  • settings.json — 権限とプロジェクト設定

    • .claude/settings.json は Claude の コマンド実行権限とファイルアクセス範囲 を定義する
    • $schema フィールドは VS Code などで 自動補完とバリデーション を支援する
    • allow リストは 自動承認コマンド、deny リストは 完全遮断コマンド を指定する
      • 例: 許可 — Bash(npm run *)、Read、Write、Edit
      • 遮断 — Bash(rm -rf *)、Bash(curl *)、.env ファイルの読み取り
    • リストにないコマンドは実行前に ユーザー確認を要求 する
    • 個人ごとの権限変更は .claude/settings.local.json に保存され、Git には含まれない

  • ~/.claude/ フォルダ — グローバル設定とメモリ

    • ~/.claude/CLAUDE.md は すべてのプロジェクトに共通適用される個人向け指針
    • ~/.claude/projects/ には プロジェクトごとのセッション記録と自動メモリ が保存される
      • Claude が学習したコマンド、パターン、構造的な洞察を保持する
      • /memory コマンドで参照および修正できる
    • ~/.claude/commands/、~/.claude/skills/、~/.claude/agents/ は グローバルな個人コマンド・スキル・エージェント の保存先

  • 全体構造の例

    your-project/  
├── CLAUDE.md  
├── CLAUDE.local.md  
└── .claude/  
    ├── settings.json  
    ├── settings.local.json  
    ├── commands/  
    ├── rules/  
    ├── skills/  
    └── agents/  
~/.claude/  
├── CLAUDE.md  
├── settings.json  
├── commands/  
├── skills/  
├── agents/  
└── projects/

  • 初期設定の手順

    • ステップ1: /init コマンドで基本の CLAUDE.md を生成し、重要な内容だけを残す
    • ステップ2: .claude/settings.json を作成し、実行許可・遮断ルールを定義する

    • 3段階:よく使うワークフロー（例: コードレビュー、Issue 修正）に合わせたコマンドを追加

      • 4段階: CLAUDE.md が大きくなったら .claude/rules/ に分割する
      • 5段階: ~/.claude/CLAUDE.md に個人の好みのルールを追加する

核心インサイト

  • .claude/ フォルダは Claude にプロジェクトのアイデンティティとルールを伝えるプロトコル である
  • CLAUDE.md が最も重要なファイルであり、これを明確に定義するほど Claude の生産性が最大化 される
  • それ以外の構成要素はこれを補完する最適化レイヤーであり、段階的に拡張できる
  • 明確な設定は Claude の修正依頼の減少と効率的な協業 につながる

追加議論

  • settings.json の deny リストは人間の利用では安全でも、エージェントモードでは Bash アクセスにより追加保護が必要
  • OneCLI はネットワークレベルで 認証情報トークンを置き換えるプロキシレイヤー を提供し、秘密情報の露出を防ぐ
  • 将来的に エージェントモード専用の .claude 設定（ルール・権限・スキルの分離）が必要ではないかという指摘
  • 最新ドキュメントによれば コマンド（commands） と スキル（skills） は統合され、.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は同じく /deploy コマンドを生成し、スキルは追加機能（補助ファイル、自動トリガーなど）をサポートする

関連記事

1件のコメント

 
GN⁺ 2026-03-28
Hacker Newsのコメント

  • AIエージェントのツールキット構築は、まるで完璧な生産性セットアップを探すことのように感じる
    ブログ記事やYouTubeを見ながらルーティンを作るけれど、結局はシンプルなToDoリストで着実に働く人のほうが先に進む
    私の経験では、素のClaudeに計画を立てさせてレビューしたあと実行させる、という単純なやり方が今でもいちばんうまく機能する

    • 大規模コードベースや分散システムでは話が違う
      エージェントがデータをパイプし、リクエストを作成し、システムを追跡しながらコードを更新する技術的スキルは、開発効率を飛躍的に高める
      1,000万行規模のコードで生産性が大きく向上したが、そのうち実際のコード生成が占める割合は5%にも満たない
      ほとんどは、テストと検証のためのツールチェーンを素早く作る能力のおかげだ
    • 多くの人がこの罠にはまってお金を使っている
      実際には、自分が何を望んでいるのかを明確に理解し、うまく伝えられるなら、AIでも十分多くのことができる
      ほとんどの人はそれができない。だから、計画を立てさせるプロセスが理解を得るための近道になる
    • 私はPMとして、エージェントが時間を節約し、出力の複利効果(compounding) をもたらしてほしいと思っている
      ただ、セッションごとにコンテキストを繰り返し、.mdファイルをコピーする非効率がある
      今の目標はこの繰り返しの排除だ。
      コンテキストを蓄積する「context bank」をどう管理しているのか気になる — たとえば「自分の役割、担当製品、最新ドキュメント」のような基本情報だ
      ドキュメントは重複や古いものが多く、単純にDrive全体をつなぐこともできない
      同じコンテキストの繰り返しが2回以上出てきたらSkillファイルを作るべきなのか、それとも文書を集約して1つのフォルダで管理すべきなのか悩んでいる
    • 私も似たような経験をした。作業中に生まれた成果物のほとんどは捨てられる
      過剰設定(over-configuration) は品質低下とループ問題を引き起こす
      モデルはどんどん良くなっているので、以前は必要だった指示文が、むしろ性能の妨げになることもある
      Anthropicチームが30日ごとにclaude.mdを初期化しているという話も聞いた
    • 一方で、私はローカル会計APIを統合しなければならないプロジェクトを進めているが、これは完全にカスタムAPIなのでLLMは知らない
      そこでClaudeにMCPサーバーを作らせ、今では会計作業を自動処理している
      月末締めのあと、Claudeに主要な作業を抽出してSkillにさせたところ、まるでジュニア会計士ができたように動いている
      カスタムMCPとSkillは本当に便利だと感じる

  • 多くの人は、エージェンティックコーディングを始める前に巨大な設定の壁を作ってしまうように感じる
    でも最初は空の .claude と AGENTS.md から始めて、自分で操作方法を学ぶのが正しい

    • 私はむしろ自分で作ったスキルだけ使うべきだと思う
      他人の作ったスキルをむやみに入れると非決定性(nondeterminism) が増え、コンテキストウィンドウも浪費される
      例外的に playwright-cli くらいなら外部導入を勧める
    • 大規模チームでは一定のガードレール(rule) が必要だ
      たとえば、このルールのように事前条件を確認するよう設定すれば安定する
      セキュリティチームもこうしたアプローチを好みそうだ
      私もルールを定義して、ClaudeがGPG署名なしでコミットしないようにした
      ただし、こうしたルールは固定ではなく、継続的に進化していくべきだ
    • この記事は巨大な設定を強いるものではない
      むしろ小さく始めて短く保つよう繰り返し強調している
      初心者でもAGENTS.mdに数行追加するだけで、AIがユーザーの意図をよりよく理解する
      シンプルな設定がAIの誤動作を大きく減らしてくれる
    • 1人でコードを扱うのと、チーム単位で共有プロジェクトを扱うのではまったく違う
      各開発者がエージェンティックなツールを使うようになると、協業のやり方そのものが変わる
    • まずはplanモードだけでも90%は解決する
      こうした複雑な設定の議論は、モデルの進化とともに1年以内に大半が消えていく気がする

  • ~/.claude/projects フォルダが本当に面白い部分だ

  • 私は不要な設定が少ないほど結果が良かった
    人は文書を過剰に規定しがちだが、AIは有能だが緊張している大人のようなものだ
    指示を与えすぎると、かえって愚かになる

  • この記事は実体験というより生成されたように感じる
    Claude.mdは短く、リンクを数個入れるくらいがよい
    コンテキストが積み上がると性能が悪化するので、計画と実装を分離し、毎回リセットすべきだ

    • 冒頭がClaudeの文体にあまりにも似ていて、私もClaudeに直接聞けばいいのではと思った
    • Skillとコマンドの違いがわかりにくい
      Skillは常にコンテキスト内にあり、コマンドは手動呼び出しだけなのか、はっきりしない

  • すべてのモデル提供者が標準のファイルセットを共有してくれたらいいのにと思う
    そうすればClaude、Codex、Cursor、Opencodeのあいだを切り替えやすくなるはずだ

    • ただし、モデルとハーネス(harness) の組み合わせが結果に大きく影響する
      同じプロンプトでもモデルごとに反応が違うので、プロンプトチューニングはモデル別に変える必要がある
    • 1つのagents.mdを作ってClaude.mdから参照させ、フォルダ間をシンボリックリンク(sync) でつなげばよい
      完璧ではないが、かなりうまく動く
    • 今は初期ブラウザ時代のようなものだ。標準化されていなかったからこそAJAXのような革新が生まれた
      だから今の多様性はむしろ前向きに捉えている
    • 私は暫定的にdotagents by Sentry を使ってこの問題を解決している
    • モデル提供者に、わざわざ乗り換えを容易にする理由はないと思う

  • Claude Fastの代替ドキュメントは非常に有用だ
    私には .claude フォルダの定義を嫌う理由がわからない
    メインエージェントにファイルを直接書かせ、反復的に更新させることで、自己改善型システムを作れる
    今では .claude が自ら複製し、評価し、更新している — 私はコードを書くのではなく、.claudeをコーディングしているようなものだ

    • 要するに、CLAUDE.mdは単なる文書ではなくClaudeのオペレーティングシステムだ
      振る舞いを定義し、知識をスキルに委譲し、時間とともに自ら改善していくシステムを作るということだ

  • あまり知られていない壁として、Claudeにファイルを修正させても、再読込するよう明示しない限り反映されないという点がある
    たとえばCLAUDE.mdを新しく書いたなら、Claudeがそれを新しい指示として認識するようリロードする必要がある

  • ~/.claude/plans フォルダにはplanモード実行時に生成された計画ファイルが保存される
    私はこのディレクトリを開いて、バックアップや参照用によく使っている

  • 私はグローバルMCPサーバーと複合エージェント(composite agent) を中心に構成している
    各MCPサーバーがツールセットを定義し、エージェントはその中で自律的に作業する
    .agent.md は単に利用可能なツールを説明する文書にすぎず、複雑な設定は不要だ
    Skillや再利用プロンプトの価値は低いと感じる
    モデルはすでに十分賢いので、必要なのは方向付け(orientation) だ