Claude Code設定のための.claude/フォルダ構造の理解

プロジェクトとグローバル設定フォルダ

.claudeディレクトリは2つあります：1つはプロジェクトルートにあり、チーム設定用でgitにコミットされます。もう1つはホームディレクトリ（~/.claude/）にあり、個人設定やセッション履歴などのマシンローカルな状態に使用されます。

CLAUDE.md：指示マニュアル

CLAUDE.mdは各セッションの開始時にClaudeのシステムプロンプトに読み込まれ、会話全体で従われます。プロジェクトルート、グローバル設定用の~/.claude/、またはフォルダ固有のルール用にサブディレクトリに配置できます。

効果的なCLAUDE.mdの内容には以下が含まれます：

• ビルド、テスト、リントコマンド（npm run test、make buildなど）
• 重要なアーキテクチャ上の決定事項
• 明らかでない落とし穴
• インポート規則、命名パターン、エラー処理スタイル
• 主要モジュールのファイルとフォルダ構造

CLAUDE.mdは200行以内に保ってください。それより長いファイルはコンテキストを消費しすぎて、Claudeの指示への従順性が低下し始めます。

CLAUDE.md構造の例

# プロジェクト：Acme API

コマンド
npm run dev # 開発サーバー起動
npm run test # テスト実行（Jest）
npm run lint # ESLint + Prettierチェック
npm run build # 本番ビルド
アーキテクチャ

Express REST API、Node 20
Prisma ORM経由のPostgreSQL
すべてのハンドラーはsrc/handlers/に配置
共有タイプはsrc/types/に配置

規則

• すべてのハンドラーでリクエスト検証にzodを使用
• 戻り値の形状は常に{ data, error }
• クライアントにスタックトレースを公開しない
• console.logではなくロガーモジュールを使用

注意点

• テストはモックではなく実際のローカルDBを使用。まずnpm run db:test:resetを実行
• 厳格なTypeScript：未使用のインポートは絶対に禁止

  CLAUDE.local.mdによる個人用上書き

  プロジェクトルートにCLAUDE.local.mdを作成して、チーム全体には適用されない個人設定を追加できます。ClaudeはメインのCLAUDE.mdと一緒にこれを読み込み、自動的にgitignoreされるため、個人の調整がリポジトリに混入することはありません。

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

  大規模なチームでは、rules/フォルダが単一の大きなCLAUDE.mdファイルよりも拡張性の高いモジュール化された指示を提供します。

  📖 Read the full source: HN AI Agents