CLAUDE.md 五层知识体系：让每个 Claude Code 会话自动对齐团队规范CLAUDE.md 五层结构完整拆

CLAUDE.md 五层知识体系：团队知识的核心载体

本文是「Claude 企业级工程实战手册」专栏第 06 篇。用好 CLAUDE.md，让每个 Claude Code 会话自动对齐团队规范，不再重复交代基础背景。

为什么需要 CLAUDE.md

Claude Code 每次启动都是全新的会话，它不知道你的项目用什么框架、有什么禁忌、测试怎么跑。

没有 CLAUDE.md 的团队，每次对话的前 10 条消息都在交代背景。有 CLAUDE.md 的团队，Claude 启动就已经是"熟悉项目的新同事"。

一、五层结构

~/.claude/CLAUDE.md                    ← 层1：个人全局层
     ↓ 自动加载
project/CLAUDE.md                      ← 层2：项目共享层（进 Git）
     ↓ 自动加载
project/CLAUDE.local.md                ← 层3：项目私有层（.gitignore）
     ↓ 按文件路径加载
.claude/rules/security.md              ← 层4：领域规则分治层
.claude/rules/testing.md
.claude/rules/api.md
     ↓ 按命令触发
.claude/skills/security-auditor/       ← 层5：自定义技能层

层1：个人全局层（`~/.claude/CLAUDE.md`）

不进 Git，每个人自己维护。记录个人偏好：

# 我的个人开发偏好

## 编辑器
- 使用 VSCode，快捷键习惯 Vim 模式
- 喜欢 compact 的代码风格，不喜欢多余的空行

## 常用命令映射
- 测试：`make test`
- 本地启动：`make dev`

## 个人约定
- 调试时使用 breakpoint() 而不是 print
- 提交信息用英文

层2：项目共享层（`project/CLAUDE.md`）

进 Git，全团队共享。这是最重要的一层。

编写原则：保持在 200 行以内，超过就拆到层4。

# 项目上下文与核心开发指南

## 核心技术栈
- 语言：Python 3.11+，强制使用显式类型注解
- 框架：FastAPI + Pydantic v2 + SQLAlchemy 2.0
- 数据库：PostgreSQL 15+，Alembic 负责迁移
- 质量控制：Ruff + pytest（覆盖率门槛 90%）

## 构建命令
- 测试：`pytest tests/ -v --cov=src`
- Lint：`ruff check src/ --fix`
- 格式化：`black src/`
- 迁移：`alembic revision --autogenerate -m "描述"`

## 禁忌（CRITICAL）
- ❌ 严禁拼接 SQL 字符串 → 必须用 SQLAlchemy ORM
- ❌ 严禁 print() 调试 → 用 structlog
- ❌ 严禁硬编码密钥 → 用 config/settings.py
- ✅ 所有路由端点必须有集成测试
- ✅ 异步函数必须用 async/await

## 常见陷阱
- 数据库会话：每请求一个 AsyncSession，中间件层统一关闭
- 测试隔离：每个用例独立事务，测试后自动回滚

层3：项目私有层（`project/CLAUDE.local.md`）

加入 .gitignore，只在本地生效。记录临时信息：

# 本地私有配置（不进 Git）

## 当前调试任务
- 正在排查 payment_service.py 第 142 行的并发问题
- 复现步骤：并发发送 100 个请求，约 30% 概率触发

## 本地特殊配置
- 本地数据库端口：5433（不是默认的 5432）
- 本地 Redis 未启动，跳过 cache 相关测试

层4：领域规则分治层（`.claude/rules/`）

按领域拆分，通过 Glob 路径匹配精准加载：

<!-- .claude/rules/security.md -->
<!-- 当修改 src/payments/**/*.py 时自动加载 -->

# 支付安全规范

## 必须遵守
- 所有用户输入必须通过 Pydantic 模型验证，不接受裸字典
- 数据库查询必须使用参数化，示例：
  ```python
  stmt = select(Payment).where(Payment.id == payment_id)

敏感字段（card_number, cvv）在日志中必须脱敏

密码学要求

哈希：bcrypt，rounds >= 12
对称加密：AES-256-GCM
禁止：MD5, SHA-1, ECB 模式


```markdown
<!-- .claude/rules/testing.md -->
<!-- 当修改 tests/**/*.py 时自动加载 -->

# 测试规范

## 结构要求
- 单元测试：tests/unit/（镜像 src/ 结构）
- 集成测试：tests/integration/
- 每个文件对应一个测试文件

## 必须使用的 Fixture
- `async_session`：数据库会话，自动回滚
- `test_client`：FastAPI 测试客户端
- `mock_redis`：Redis Mock，不依赖真实 Redis

## 覆盖率要求
- 核心业务逻辑：≥ 95%
- API 端点：≥ 90%
- 工具函数：≥ 85%

层5：自定义技能层（`.claude/skills/`）

详见第 09 篇《Agent Skills 升级》。

二、CLAUDE.md 初始化流程

首次在新项目使用 Claude Code：

# 1. 让 Claude 自动分析项目生成初稿
cd your-project
claude
> /init

# Claude 会自动扫描项目结构，生成 CLAUDE.md 初稿

# 2. 人工审查和补充
# 特别注意添加：禁忌规则、测试命令、常见陷阱

# 3. 提交到 Git
git add CLAUDE.md .claude/rules/
git commit -m "chore: add Claude Code project context"

三、常见错误

错误一：CLAUDE.md 太长

超过 200 行的 CLAUDE.md 会导致注意力衰退——Claude 开始忽略后半部分的规则。

解决方案：超过的内容拆分到 .claude/rules/ 下的领域文件。

错误二：禁忌规则没有替代方案

# ❌ 只有禁止
- 严禁使用 print() 调试

# ✅ 禁止 + 替代方案
- ❌ 严禁使用 print() 调试 → ✅ 使用 structlog.get_logger().debug("msg", key=value)

错误三：技术栈版本不精确

# ❌ 模糊
- 框架：FastAPI

# ✅ 精确
- 框架：FastAPI 0.115+，使用 lifespan 管理生命周期（不用 on_startup/on_shutdown）

四、验证 CLAUDE.md 是否有效

打开新会话，直接问：

你了解这个项目的哪些信息？
列出你知道的：技术栈、测试命令、禁忌规则。

如果 Claude 能准确复述关键信息，说明 CLAUDE.md 加载成功且有效。

下一篇：07. Hooks 确定性安全栅栏

专栏导航 · Claude 企业级工程实战手册

⬅️ 上一篇：05. 像管理代码一样管理 Prompt：企业级版本管理体系全实战 ➡️ 下一篇：07. Claude Code Hooks 安全栅栏：PreToolUse 高危拦截 + PostToolUse 自动格式化

本专栏共 14 篇，系统覆盖 Claude 模型选型 / Prompt 工程 / Claude Code 工作流 / API 高级用法 / MCP / RAG / AI 安全合规全链路。欢迎收藏：Claude 企业级工程实战手册

CLAUDE.md 五层知识体系：让每个 Claude Code 会话自动对齐团队规范