教程 2026-05-20 浏览 6 次

Claude Code 从零到精通：多Agent协作开发完全教程-第三章：CLAUDE.md — 你的开发规范圣经

第三章：CLAUDE.md — 你的开发规范圣经

CLAUDE.md 是 Claude Code 最核心的配置文件，它决定了 AI 的行为边界和开发质量。规范先行是多 Agent 开发的第一原则。

3.1 CLAUDE.md 的层级结构

Plaintext

~/.claude/CLAUDE.md ← 全局规范（所有项目生效）

│

▼ (被覆盖)

项目根目录/CLAUDE.md ← 项目级规范（当前项目生效）

│

▼ (被覆盖)

子目录/CLAUDE.md ← 模块级规范（该目录下生效）

📌 覆盖规则：离你越近的 CLAUDE.md 优先级越高。子目录的规范会覆盖上层规范。

3.2 全局 CLAUDE.md 配置

位置：~/.claude/CLAUDE.md

适合放置跨项目通用的规范：

Markdown

全局开发规范

Agent Team 管理

NEVER auto-shutdown teammates after task completion.

Keep them idle and reusable indefinitely within the session.

只有用户明确要求关闭时才发送 shutdown_request。

通用编码规范

优先使用 TypeScript
使用 ESLint + Prettier 格式化代码
所有公开 API 必须有类型注解

沟通语言

Always respond in 中文。技术术语保留英文原文。

3.3 项目级 CLAUDE.md 完整模板

以下是根据实战经验总结的完整模板（你需要根据自己的项目调整）：

Markdown

项目名称 - 开发规范

一、项目概述

描述项目的核心功能和目标。

本项目是一个 [简要描述]
核心用户是 [目标用户]
主要解决的问题是 [问题描述]

二、技术栈约束

必须使用的技术

| 模块 | 技术栈 |

|------|--------|

| 前端 | React 18 + TypeScript + Vite |

| 后端 | Node.js + Express + PostgreSQL |

| 测试 | Jest + Playwright |

禁止使用的技术

❌ 不要使用 jQuery
❌ 不要使用 var 声明变量
❌ 不要使用 any 类型（除非确有必要并注释原因）
❌ 不要引入未经确认的第三方库

三、整体架构图

┌──────────────────────────────────────┐

│ 前端应用 │

│ ┌──────┐ ┌──────┐ ┌──────┐ │

│ │ 页面 │ │ 组件 │ │ 状态 │ │

│ └──┬───┘ └──┬───┘ └──┬───┘ │

│ └─────────┼─────────┘ │

│ │ HTTP/WebSocket │

├───────────────┼──────────────────────┤

│ API 层 │

│ ┌──────┐ ┌──────┐ ┌──────┐ │

│ │ 路由 │ │ 中间件│ │ 控制器│ │

│ └──┬───┘ └──┬───┘ └──┬───┘ │

│ └─────────┼─────────┘ │

│ │ │

├───────────────┼──────────────────────┤

│ 数据层 │

│ ┌──────┐ ┌──────┐ │

│ │ 模型 │ │ 数据库│ │

│ └──────┘ └──────┘ │

└──────────────────────────────────────┘

四、架构红线（不可违反）

前后端必须通过 API 通信，禁止直接数据库操作
所有 API 必须经过认证中间件
敏感数据必须加密存储
组件间通信必须通过状态管理，禁止直接 DOM 操作

五、通信协议

RESTful API 规范
请求体使用 camelCase
URL 路径使用 kebab-case
响应格式统一为：{ code, message, data }

六、目录组织规范

project/

├── CLAUDE.md # 项目规范（你正在看的这个）

├── src/

│ ├── frontend/ # 前端代码

│ │ ├── components/ # 通用组件

│ │ ├── pages/ # 页面

│ │ ├── hooks/ # 自定义 hooks

│ │ └── utils/ # 工具函数

│ ├── backend/ # 后端代码

│ │ ├── routes/ # 路由定义

│ │ ├── controllers/ # 控制器

│ │ ├── models/ # 数据模型

│ │ └── middleware/ # 中间件

│ └── shared/ # 前后端共享代码

├── tests/ # 测试文件

├── docs/ # 文档

│ ├── api.md # API 文档

│ └── dsl-spec.md # DSL 规范

└── scripts/ # 脚本工具

七、编码规范

函数长度不超过 50 行
文件长度不超过 300 行，超过需拆分
每个模块必须有 index.ts 导出
命名规范：组件 PascalCase，函数 camelCase，常量 UPPER_SNAKE_CASE

八、Git 提交规范

feat: 新功能
fix: 修复 bug
refactor: 重构
test: 测试相关
docs: 文档更新
每次提交必须附带有意义的描述

九、Agent 协作规范

主 Agent 不干重活，只负责统筹和分发任务
架构师 Agent 负责审查 git 提交记录，确保符合规范
DSL 相关修改必须全局广播给所有相关 Agent
发现 bug 时先通知相关 Agent，确认后再修复

十、测试规范

所有新功能必须附带单元测试
接口测试覆盖率 > 80%
测试必须有明确的输入输出和反馈
测试命令：npm test（运行后查看输出即可知道对错）

十一、上下文管理要求

compact 后必须重新读取本文件（CLAUDE.md 会被自动注入系统提示，但 compact 后细节可能丢失，需强制重读）
分阶段干活，每个阶段有明确的输入、目标和验收标准
当上下文超过 150K tokens 时主动执行 /compact
主 Agent 绝不自己读代码/写代码，只统筹分发，避免上下文膨胀
使用 subagent 做代码探索和调研，结果以摘要形式回传，不污染主上下文
约束文件读取范围：在提示词中明确"只读 src/xxx/ 目录"，禁止无目的全局搜索
不相关任务之间执行 /clear 清空上下文
在 CLAUDE.md 中加入 compact 保留指令："compact 时务必保留：已修改文件列表、测试命令、当前阶段进度"
配合 .claudeignore 排除 node_modules/、dist/、vendor/ 等目录，减少 40-60% 搜索噪音

3.4 编写 CLAUDE.md 的核心原则

Plaintext

┌─────────────────────────────────────────────────┐

│ CLAUDE.md 编写黄金法则 │

├─────────────────────────────────────────────────┤

│ │

│ ✅ DO ❌ DON'T │

│ ───────────── ───────────── │

│ 精确具体的约束模糊的描述 │

│ "用 React 18" "用现代框架" │

│ │

│ 必要的信息冗长的废话 │

│ 模型注意力有限！注意力会被分散！ │

│ │

│ 可验证的规则无法验证的建议 │

│ "函数不超过50行" "代码要简洁" │

│ │

│ 架构红线和边界面面俱到的指南 │

│ "禁止直接DB操作" 大量教程性内容 │

│ │

│ 经过多轮迭代优化一次性写完不再更新 │

│ 几小时反复打磨只花10分钟 │

│ │

└─────────────────────────────────────────────────┘

⚠️ 实战经验：CLAUDE.md 的质量直接决定了 AI 开发的效果。构思一个好的 CLAUDE.md 可能需要小半天时间，但这是值得的投资。它就像给员工的 Onboarding 文档——写得越清楚，员工干活越靠谱。

返回列表