CLAUDE.md ガイド

Claude Code の核心指針ファイル体系を詳しく案内します。CLAUDE.md は毎セッション常にロードされるファイルなので、このファイルの 1 行 1 行がそのまま常時コンテキストのコストです — 指針体系の設計はハーネス設計であると同時にトークノミクスでもあります。

情報

一行要約: CLAUDE.md はプロジェクトの 憲法 です。Claude Code がプロジェクトをどう理解し、どんなルールに従い、どのエージェントを呼び出すか、すべてこのファイルで決まります。

CLAUDE.md は Claude Code がセッションを開始するとき 最初に読む指針ファイル です。このファイルにプロジェクトのルール、エージェント構造、ワークフロー、品質基準などが定義されています。

人が新しい会社に入社すると社員ハンドブックを読むように、Claude Code はセッションを開始するとき CLAUDE.md を読んでプロジェクトの文脈を把握します。

MoAI-ADK は 2 つの指針ファイルとルールディレクトリを使います。

flowchart TD
    subgraph MAIN["CLAUDE.md (プロジェクトレベル)"]
        M1["核心アイデンティティ"]
        M2["リクエスト処理パイプライン"]
        M3["コマンドリファレンス"]
        M4["エージェントカタログ"]
        M5["SPEC ワークフロー"]
        M6["品質ゲート"]
    end

    subgraph LOCAL["CLAUDE.local.md (個人レベル)"]
        L1["個人ルール"]
        L2["MDX ガイドライン"]
        L3["プロジェクトメモ"]
    end

    subgraph RULES[".claude/rules/ (条件付きルール)"]
        R1["core/ 核心原則"]
        R2["development/ 開発標準"]
        R3["workflow/ ワークフロー"]
        R4["languages/ 言語別ルール"]
    end

    MAIN --> LOCAL
    MAIN --> RULES

MoAI オーケストレーターの役割と HARD ルールを定義します。

## 1. 核心アイデンティティ

MoAI は Claude Code の戦略的オーケストレーターです。

### HARD ルール (必須)
- [HARD] 言語認識応答: ユーザーの conversation_language で応答
- [HARD] 並列実行: 独立したツール呼び出しは並列実行
- [HARD] XML タグ非表示: ユーザー対面応答に XML を非表示
- [HARD] Markdown 出力: すべてのコミュニケーションに Markdown を使用

すべてのリクエストは入力言語と無関係に 1 つの順序化されたパイプラインを経ます。v3.0 の核心は 意図分析が常に先 という点です — 英語のキーワードマッチングではなく言語独立的な意味分類でルーティングします。

/moai がすべての MoAI 開発ワークフローの単一の進入点です。

MoAI-ADK は 11 個の保存エージェント (10 個 MoAI-custom + 1 個 Anthropic built-in) で構成されます。アーキテクチャの単純化により manager-strategy, manager-quality, manager-brain, manager-project など 12 個の archived エージェントは特定ドメインに対する per-spawn Agent(general-purpose) delegation に置き換えられました。

3 段階の SPEC ベース開発ワークフローを定義します。

# Plan: SPEC ドキュメント生成 (30K トークン)
> /moai plan "機能の説明"

# Run: DDD 実装 (180K トークン)
> /moai run SPEC-XXX

# Sync: ドキュメント同期 (40K トークン)
> /moai sync SPEC-XXX

# E2E: Web/モバイル/デスクトップの E2E テスト実行
> /moai e2e

TRUST 5 フレームワークと LSP 品質ゲートを定義します。

下位エージェントはユーザーと直接対話できません。ユーザー接点は MoAI 一つに固定されます。

flowchart TD
    USER["ユーザー"] --> MOAI["MoAI"]
    MOAI -->|"1. 情報収集"| USER
    MOAI -->|"2. 作業委任"| AGENT["下位エージェント"]
    AGENT -->|"3. 結果を返す"| MOAI
    MOAI -->|"4. 結果報告"| USER

    AGENT -.-x|"直接対話不可"| USER

言語設定、ユーザー設定、プロジェクトルールを参照します。

language:
  conversation_language: ko           # ユーザー応答言語
  agent_prompt_language: en           # エージェント内部言語
  git_commit_messages: en             # Git コミットメッセージ
  code_comments: en                   # コードコメント
  documentation: en                   # ドキュメントファイル

CLAUDE.local.md は個人的なルールとメモを書くファイルです。MoAI-ADK アップデートと無関係に保存されます。

# プロジェクトローカル設定

## ドキュメント作成ガイドライン

### MDX レンダリングエラーの防止
- 強調表示と括弧の間に必ず空白

### Mermaid ダイアグラムの方向
- すべてのダイアグラムは縦方向 (flowchart TD)

## 個人メモ
- DB マイグレーション前にバックアップ必須
- API エンドポイントの命名: kebab-case を使用

.claude/rules/ ディレクトリには 条件付きでロードされる詳細ルール が保存されます。すべてのルールを CLAUDE.md に入れず条件付きファイルに分離する理由はただ 1 つ — 使わないルールがコンテキストを占めないようにするためです。

.claude/rules/moai/
├── core/                          # 核心原則
│   └── moai-constitution.md       # TRUST 5、核心ルール
├── development/                   # 開発標準
│   ├── skill-authoring.md         # スキル作成ガイド
│   └── coding-standards.md        # コーディング標準
├── workflow/                      # ワークフロー
│   └── spec-workflow.md           # SPEC ワークフロー (Plan/Run/Sync 定義)
└── languages/                     # 言語別ルール (16 個)
    ├── python.md
    ├── typescript.md
    ├── javascript.md
    └── ...

ルールファイルは paths フロントマターを通じて 特定のファイル作業時にのみロード されます。

---
paths:
  - "**/*.py"
  - "**/pyproject.toml"
---

# Python コーディングルール
- ruff フォーマッターを使用
- type hints 必須
- docstring は Google スタイル

このルールは Python ファイルを修正するときだけロードされて トークンを節約 します。

CLAUDE.md は 40,000 文字以下 を維持する必要があります。MoAI-ADK 自体も v3 期間中に CLAUDE.md を継続的にダイエットしてきました — 常時ロード指針は短いほどすべてのセッションが安くなります。

flowchart TD
    CHECK{"CLAUDE.md
40,000 文字超過?"}

    CHECK -->|はい| MOVE["詳細内容を
.claude/rules/ へ移動"]
    CHECK -->|いいえ| OK["正常維持"]

    MOVE --> REF["CLAUDE.md には
参照のみ残す"]
    REF --> SLIM["核心ルールのみ
CLAUDE.md に維持"]

対応戦略:

1. 詳細内容の移動: 長い説明は .claude/rules/ ファイルに分離
2. 参照の使用: CLAUDE.md で @ファイルパス で参照
3. 核心のみ維持: アイデンティティ、HARD ルール、エージェントカタログのみ維持
4. スキルへの転換: 長いパターンの説明はスキルに変換

# プロジェクトローカル設定

## React ルール
- コンポーネントは必ず関数型で記述
- Props インターフェースはコンポーネントファイルの上部に定義
- 状態管理は Zustand を使用
- CSS は Tailwind CSS のみ使用

## 命名ルール
- コンポーネント: PascalCase (UserProfile.tsx)
- ユーティリティ: camelCase (formatDate.ts)
- 定数: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- API エンドポイント: kebab-case (/api/user-profiles)

## 禁止事項
- any 型の使用禁止
- console.log をプロダクションコードに禁止
- default export 禁止 (named export のみ使用)

# プロジェクトローカル設定

## Python ルール
- FastAPI を使用
- 非同期関数を優先 (async/await)
- Pydantic v2 モデルを使用
- SQLAlchemy 2.0 スタイル

## データベースルール
- マイグレーション前に必ずバックアップ
- インデックスはクエリパターン分析後に追加
- soft delete パターンを使用 (is_deleted フラグ)

## API ルール
- RESTful エンドポイントの命名
- 応答形式の統一: {"data": ..., "message": ...}
- エラーコードの標準化

指針体系は 4 階層に分かれ、下の階層に行くほどロード条件が狭くなります。

flowchart TD
    subgraph HIERARCHY["指針体系の階層"]
        CLAUDE["CLAUDE.md
最上位指針 (常にロード)"]
        RULES[".claude/rules/
条件付きルール (paths マッチ時)"]
        SKILLS[".claude/skills/
専門知識 (トリガーマッチ時)"]
        AGENTS[".claude/agents/
エージェント定義 (委任時)"]
    end

    CLAUDE --> RULES
    RULES --> SKILLS
    SKILLS --> AGENTS

    CLAUDE -.->|"参照"| RULES
    AGENTS -.->|"スキル使用"| SKILLS

• スキルガイド - スキルシステムの詳細
• エージェントガイド - エージェントシステムの詳細
• settings.json ガイド - 設定ファイルの管理
• Hooks ガイド - イベント自動化

情報

ヒント: CLAUDE.md を直接修正するより CLAUDE.local.md に個人ルールを追加することを推奨します。MoAI-ADK アップデート時にも個人ルールが安全に保存されます。