CLAUDE.md 指南

详细介绍 Claude Code 的核心指令文件体系。CLAUDE.md 是每个会话都会加载的文件，因此这份文件的每一行都是常驻的上下文成本 — 指令体系设计既是 Harness 设计，也是代币经济学。

信息

一句话总结：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

所有请求无论输入语言如何，都经过同一条有序管线。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) 委派所取代。

定义 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，而是拆分为条件化文件，理由只有一个 — 让用不到的规则不占用上下文。

.claude/rules/moai/
├── core/                          # 核心原则
│   └── moai-constitution.md       # TRUST 5、核心规则
├── development/                   # 开发标准
│   ├── skill-authoring.md         # 技能编写指南
│   └── coding-standards.md        # 编码标准
├── workflow/                      # 工作流
│   ├── workflow-modes.md          # Plan/Run/Sync 定义
│   └── spec-workflow.md           # SPEC 工作流
└── languages/                     # 按语言的规则 (16 种)
    ├── python.md
    ├── typescript.md
    ├── javascript.md
    └── ...

规则文件通过 paths frontmatter 仅在操作特定文件时加载。

---
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 更新时个人规则也会被安全保留。