CLAUDE.md Guide

A detailed guide to Claude Code’s core instruction file system. CLAUDE.md is loaded in every session, so every single line of this file is a standing context cost — designing the instruction system is harness design and tokenomics at the same time.

Info

One-line summary: CLAUDE.md is the project’s constitution. How Claude Code understands the project, which rules it follows, and which agents it invokes are all decided in this file.

CLAUDE.md is the first instruction file Claude Code reads when it starts a session. The project’s rules, agent structure, workflow, and quality criteria are defined in this file.

Just as a person joining a new company reads the employee handbook, Claude Code reads CLAUDE.md at session start to grasp the project’s context.

MoAI-ADK uses two instruction files plus a rules directory.

flowchart TD
    subgraph MAIN["CLAUDE.md (project level)"]
        M1["Core identity"]
        M2["Request processing pipeline"]
        M3["Command reference"]
        M4["Agent catalog"]
        M5["SPEC workflow"]
        M6["Quality gates"]
    end

    subgraph LOCAL["CLAUDE.local.md (personal level)"]
        L1["Personal rules"]
        L2["MDX guidelines"]
        L3["Project notes"]
    end

    subgraph RULES[".claude/rules/ (conditional rules)"]
        R1["core/ core principles"]
        R2["development/ development standards"]
        R3["workflow/ workflows"]
        R4["languages/ per-language rules"]
    end

    MAIN --> LOCAL
    MAIN --> RULES

Defines the role of the MoAI orchestrator and the HARD rules.

## 1. Core Identity

MoAI is the strategic orchestrator for Claude Code.

### HARD Rules (required)
- [HARD] Language-aware responses: respond in the user's conversation_language
- [HARD] Parallel execution: run independent tool calls in parallel
- [HARD] No XML tags: no XML in user-facing responses
- [HARD] Markdown output: use Markdown for all communication

Every request goes through a single ordered pipeline, regardless of input language. The core of v3.0 is that intent analysis always comes first — routing is by language-independent semantic classification, not English keyword matching.

/moai is the single entry point for all MoAI development workflows.

MoAI-ADK consists of 11 retained agents (10 MoAI-custom + 1 Anthropic built-in). Through architecture simplification, 12 archived agents such as manager-strategy, manager-quality, manager-brain, and manager-project were replaced by per-spawn Agent(general-purpose) delegation for specific domains.

Defines the 3-phase SPEC-based development workflow.

# Plan: create SPEC document (30K tokens)
> /moai plan "feature description"

# Run: DDD implementation (180K tokens)
> /moai run SPEC-XXX

# Sync: documentation sync (40K tokens)
> /moai sync SPEC-XXX

# E2E: run web/mobile/desktop E2E tests
> /moai e2e

Defines the TRUST 5 framework and the LSP quality gates.

Sub-agents cannot converse with the user directly. The user touchpoint is fixed to MoAI alone.

flowchart TD
    USER["User"] --> MOAI["MoAI"]
    MOAI -->|"1. Gather information"| USER
    MOAI -->|"2. Delegate work"| AGENT["Sub-agent"]
    AGENT -->|"3. Return results"| MOAI
    MOAI -->|"4. Report results"| USER

    AGENT -.-x|"No direct conversation"| USER

References language settings, user settings, and project rules.

language:
  conversation_language: ko           # user response language
  agent_prompt_language: en           # agent internal language
  git_commit_messages: en             # Git commit messages
  code_comments: en                   # code comments
  documentation: en                   # documentation files

CLAUDE.local.md is the file for your personal rules and notes. It is preserved regardless of MoAI-ADK updates.

# Project local settings

## Documentation guidelines

### Prevent MDX rendering errors
- Always put a space between emphasis markers and parentheses

### Mermaid diagram direction
- All diagrams vertical (flowchart TD)

## Personal notes
- Always back up before DB migration
- API endpoint naming: use kebab-case

The .claude/rules/ directory stores conditionally loaded detailed rules. There is exactly one reason not to put every rule in CLAUDE.md and to split them into conditional files instead — so that unused rules do not occupy context.

.claude/rules/moai/
├── core/                          # core principles
│   └── moai-constitution.md       # TRUST 5, core rules
├── development/                   # development standards
│   ├── skill-authoring.md         # skill authoring guide
│   └── coding-standards.md        # coding standards
├── workflow/                      # workflows
│   └── spec-workflow.md           # SPEC workflow (Plan/Run/Sync definitions)
└── languages/                     # per-language rules (16)
    ├── python.md
    ├── typescript.md
    ├── javascript.md
    └── ...

A rule file is loaded only when working on specific files, via the paths frontmatter.

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

# Python coding rules
- use the ruff formatter
- type hints required
- Google-style docstrings

This rule loads only when Python files are being modified, saving tokens.

CLAUDE.md must stay under 40,000 characters. MoAI-ADK itself kept putting CLAUDE.md on a diet throughout the v3 period — the shorter the always-loaded instructions, the cheaper every session becomes.

flowchart TD
    CHECK{"CLAUDE.md
over 40,000 chars?"}

    CHECK -->|Yes| MOVE["Move details to
.claude/rules/"]
    CHECK -->|No| OK["Keep as is"]

    MOVE --> REF["Leave only references
in CLAUDE.md"]
    REF --> SLIM["Keep only core rules
in CLAUDE.md"]

Response strategies:

1. Move details out: split long explanations into .claude/rules/ files
2. Use references: reference from CLAUDE.md via @file-path
3. Keep only the core: retain only identity, HARD rules, and the agent catalog
4. Convert to skills: turn long pattern explanations into skills

# Project local settings

## React rules
- Components must be written as functional components
- Define the Props interface at the top of the component file
- Use Zustand for state management
- Use Tailwind CSS only for CSS

## Naming rules
- Components: PascalCase (UserProfile.tsx)
- Utilities: camelCase (formatDate.ts)
- Constants: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- API endpoints: kebab-case (/api/user-profiles)

## Prohibitions
- No use of the any type
- No console.log in production code
- No default export (named exports only)

# Project local settings

## Python rules
- Use FastAPI
- Prefer async functions (async/await)
- Use Pydantic v2 models
- SQLAlchemy 2.0 style

## Database rules
- Always back up before migration
- Add indexes after analyzing query patterns
- Use the soft-delete pattern (is_deleted flag)

## API rules
- RESTful endpoint naming
- Unified response format: {"data": ..., "message": ...}
- Standardized error codes

The instruction system is divided into 4 layers; loading conditions narrow as you descend.

flowchart TD
    subgraph HIERARCHY["Instruction system layers"]
        CLAUDE["CLAUDE.md
Top-level instructions (always loaded)"]
        RULES[".claude/rules/
Conditional rules (on paths match)"]
        SKILLS[".claude/skills/
Expertise (on trigger match)"]
        AGENTS[".claude/agents/
Agent definitions (on delegation)"]
    end

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

    CLAUDE -.->|"references"| RULES
    AGENTS -.->|"use skills"| SKILLS

• Skill Guide - skill system details
• Agent Guide - agent system details
• settings.json Guide - configuration file management
• Hooks Guide - event automation

Info

Tip: Rather than editing CLAUDE.md directly, we recommend adding your personal rules to CLAUDE.local.md. Your personal rules are safely preserved across MoAI-ADK updates.