CLAUDE.md 深度分析：为什么写、怎么写、如何与 System Prompt 结合、如何验证效果

基于 TRPC Codegen Agent 项目实践，结合行业最佳实践撰写

1. 为什么 Claude 需要 CLAUDE.md

1.1 核心问题：无记忆的 AI

每次 Claude Code 会话都从零开始。它不知道：

你的项目用什么技术栈
你的团队遵循什么编码规范
构建、测试、部署用什么命令
项目的架构决策和核心模式
哪些文件不应被修改

没有 CLAUDE.md，开发者每次会话都要花 10-15 条消息重新解释上下文。Claude 会做出错误假设——使用错误的包管理器、生成不符合项目风格的代码、触碰不该动的文件。

1.2 CLAUDE.md 的本质定位

CLAUDE.md 本质上是给 AI 看的项目入职文档，而不是给人看的 README。它的核心目标是：

目标	说明
消除歧义	告诉 Claude 项目特有的选择（"用 yapf 不用 black"）
建立约束	定义不可逾越的规则（"不要修改 trpc_main.py 的入口逻辑"）
提供上下文	帮 Claude 理解架构，在修改代码时做出正确决策
提升一致性	确保团队中所有人使用 Claude 时得到一致的行为
节省时间	从第一条消息开始就跳过重复解释

1.3 关键类比

.editorconfig  →  配置编辑器行为
.prettierrc    →  配置格式化器行为
CLAUDE.md      →  配置 AI 助手行为

三者的共同点：声明式配置，自动加载，无需人工干预。

2. CLAUDE.md 的实现规则与规范

2.1 文件层级系统

Claude Code 支持多级 CLAUDE.md，按从通用到具体的顺序加载：

~/.claude/CLAUDE.md              # 全局级：个人偏好（所有项目生效）
{project-root}/CLAUDE.md         # 项目级：项目规范（最核心）
{project-root}/.claude/CLAUDE.md # 项目级（备选位置）
{subdirectory}/CLAUDE.md         # 子目录级：局部覆盖
*.local.md                       # 本地覆盖（不提交到 Git）

优先级规则：更具体的覆盖更通用的。子目录 > 项目根目录 > 全局。

2.2 推荐的 7 大核心节（Section）

一份优秀的 CLAUDE.md 应包含以下节：

① 项目概述（2-3 行）

markdown

## 项目概述
TRPC Codegen Agent 是面向 tRPC 的多智能体 LLM 代码生成系统。
技术栈：Python 3.12+、tRPC 框架、LangGraph、A2A 协议。

告诉 Claude "你在操作什么"，而不是详细的历史或设计哲学。

② 常用命令

markdown

## 常用命令
- `./build.sh` — 安装依赖
- `python3 trpc_main.py` — 启动服务（端口 9091）
- `python -m pytest test_agent.py -v` — 运行测试
- `./format.sh` — 格式化 + lint

这是 CLAUDE.md 中最高杠杆的部分。Claude 会直接使用这些命令。

③ 代码风格

markdown

## 代码风格
- PEP 8，行宽 120，4 空格缩进
- 使用 yapf 格式化，ruff 做导入检查

只写与 Claude 默认行为不同的规则。"写干净的代码"是废话——Claude 本来就会这样做。

④ 架构

markdown

## 架构
描述关键模块、层级关系、核心模式、请求流程。

让 Claude 理解修改一处代码时需要考虑哪些关联影响。

⑤ 关键约束（Do / Don't）

markdown

## 约束
- 不要修改 trpc_main.py 的核心入口逻辑
- 新智能体必须继承 ClaudeAgent 基类
- 所有异常必须继承 CodegenError

⑥ 目录结构

markdown

## 目录结构
- team_agent/ — 领导智能体与公共模块
- config/ — 配置访问器
- common/ — 共享工具（模型工厂、文件工具集）

⑦ 入口点与配置

markdown

## 入口点
- trpc_main.py — 服务初始化
- codegen_a2a_service.py — A2A 服务

2.3 六大编写原则

#	原则	说明
1	写指令，不写描述	`"使用 yapf 格式化"` 优于 `"本项目采用 yapf 作为格式化工具"`
2	只写能改变行为的规则	如果去掉这条规则 Claude 的输出不变，就删掉它
3	保持简洁	控制在 80-150 行以内。研究表明 LLM 在约 150-200 条独立指令后效果递减
4	具体化	`"用 Vitest + happy-dom"` 优于 `"写好的测试"`
5	重要规则放前面	Claude 对靠前的指令赋予更高权重
6	迭代测试	像代码一样测试和维护 CLAUDE.md

2.4 常见反模式

反模式	问题	修正
500+ 行的"小说"	上下文膨胀，关键规则被淹没	拆分到 `.claude/rules/*.md`
重复 README 内容	浪费 token，Claude 已经能读 README	CLAUDE.md 只放 AI 需要的指令
写"最佳实践"	Claude 已内置通用最佳实践	只写项目特有的规则
从不更新	过时的 CLAUDE.md 比没有更糟	每月审查，删除过时规则
矛盾指令	Claude 行为不可预测	保持一致，定期检查

3. CLAUDE.md 与 System Prompt 的结合机制

3.1 技术架构

理解 CLAUDE.md 的技术实现是掌握它的关键。很多人误以为 CLAUDE.md 直接注入了 system prompt，但实际机制更巧妙。

System Prompt 的组成

Claude Code 发送给 API 的请求结构：

json

{
  "system": [
    {"type": "text", "text": "You are Claude Code...", "cache_control": {"type": "ephemeral"}},
    {"type": "text", "text": "<tool definitions...>"}
  ],
  "messages": [
    {"role": "user", "content": "<system-reminder>...\n# claudeMd\nContents of CLAUDE.md...\n</system-reminder>\n\n用户实际消息"}
  ],
  "tools": [...]
}

关键发现：CLAUDE.md 不在 system prompt 中

CLAUDE.md 的内容被注入到 messages 数组中，而不是 system 数组中。 这是一个有意的架构设计：

┌──────────────────────────────────────────────────┐
│  system prompt (约 27,000 tokens)                 │
│  ├── 身份定义 ("You are Claude Code...")          │
│  ├── 工具使用指南                                  │
│  ├── 代码风格与格式化指南                           │
│  ├── 安全规则                                      │
│  └── 内置行为指令 (110+ 条)                        │
│                                                    │
│  ★ 所有用户共享，支持 prompt cache                  │
├──────────────────────────────────────────────────┤
│  messages[0] (用户消息前缀)                        │
│  ├── <system-reminder> 标签包裹                    │
│  │   ├── CLAUDE.md 内容                           │
│  │   ├── MEMORY.md 内容                           │
│  │   ├── Skills 定义                               │
│  │   └── MCP 工具描述                              │
│  └── 用户实际消息                                  │
│                                                    │
│  ★ 每用户不同，不影响共享缓存                       │
└──────────────────────────────────────────────────┘

为什么这样设计？

缓存经济性：system prompt 是所有用户共享的（约 27K tokens）。如果每个用户的 CLAUDE.md 都放进 system prompt，每个用户需要独立缓存，Anthropic 的成本会爆炸
灵活性：messages 中的内容可以动态变化，不需要重建缓存
层级合并：多个 CLAUDE.md 文件的内容可以在注入前合并

3.2 在 Cursor IDE 中的集成方式

在 Cursor 等 IDE 中，CLAUDE.md 的注入方式略有不同。Cursor 使用 always_applied_workspace_rules 机制：

xml

<always_applied_workspace_rules>
  <always_applied_workspace_rule name="CLAUDE.md">
    （CLAUDE.md 的完整内容）
  </always_applied_workspace_rule>
</always_applied_workspace_rules>

这些内容被直接嵌入到 system prompt 中，作为始终生效的工作区规则。本项目当前正是通过这种方式生效的。

3.3 注入时序与 Token 预算

会话启动
  │
  ├── 1. 加载共享 system prompt (~27K tokens)
  ├── 2. 遍历目录树，收集所有 CLAUDE.md 文件
  ├── 3. 合并 CLAUDE.md 内容（子目录覆盖父目录）
  ├── 4. 加载 MEMORY.md、Skills、MCP 工具定义
  ├── 5. 打包为 <system-reminder> 注入 messages[0]
  └── 6. 等待用户输入

总初始 token 开销：
  无项目配置：~27,000 tokens
  有项目配置：~30,000-35,000 tokens
  CLAUDE.md 的占比：约 3,000-8,000 tokens（视文件大小）

3.4 与本项目的 Instruction 系统的关系

本项目（TRPC Codegen Agent）有自己的 instruction 机制，与 CLAUDE.md 是两个层面的事：

维度	CLAUDE.md	项目 Instruction 系统
作用对象	开发者使用的 Claude Code / Cursor	项目运行时的子智能体
加载方式	IDE/CLI 自动注入	`_get_leader_instruction()` 代码加载
配置来源	文件系统	Rainbow 配置平台
影响范围	开发者与 Claude 的对话	生产环境中智能体的行为
示例	"使用 yapf 格式化"	"根据 proto 文件生成 Go 服务骨架"

python

# 项目自身的 instruction 加载（team_agent/agent.py）
def _get_leader_instruction(ctx: InvocationContext) -> str:
    instruction_template = get_leader_instruction()  # 从 Rainbow 获取
    instruction = Template(instruction_template).safe_substitute(
        code_gen_dir=workspace,
        upstream_params=_format_upstream_params(message),
    )
    return instruction

CLAUDE.md 帮助开发者更好地维护这个项目，而 instruction 系统决定项目运行时智能体如何工作。两者互补。

4. 如何验证 CLAUDE.md 对回答质量的帮助

4.1 定性验证法（人工观察）

方法一：规则合规性测试

步骤：
1. 启动全新 Claude Code 会话
2. 要求 Claude 执行一个应触发 CLAUDE.md 规则的任务
3. 检查输出是否遵循了规则
4. 如不遵循，分析原因（规则太模糊？位置太靠后？与其他规则矛盾？）

本项目验证示例：

测试任务	期望行为（来自 CLAUDE.md）	通过标准
"帮我格式化这个文件"	使用 `yapf -i <file>` 而非 black	Claude 调用 yapf
"运行测试"	使用 `python -m pytest test_agent.py -v`	命令正确
"新增一个代码检查智能体"	放在正确目录、继承正确基类	结构符合架构规范
"看看项目入口"	指向 `trpc_main.py`	不会去猜测其他入口

方法二：A/B 对比测试

实验组：保留完整 CLAUDE.md，执行任务
对照组：清空/删除 CLAUDE.md，执行相同任务
比较：输出质量、正确性、是否需要人工修正

4.2 定量验证法（自动化基准测试）

工具一：mdarena（基于真实 PR 的基准测试）

mdarena 从项目历史 PR 中提取任务，在有/无 CLAUDE.md 的条件下运行 Claude，然后与实际合并的 PR 对比：

bash

# 从仓库历史挖掘 50 个已合并的 PR 作为测试集
mdarena mine owner/repo --limit 50 --detect-tests

# 对比多个 CLAUDE.md 版本 + 无 CLAUDE.md 的基线
mdarena run -c claude_v1.md -c claude_v2.md -c agents.md

# 生成对比报告
mdarena report

评估维度：

测试通过率（与 SWE-bench 相同标准）
文件/代码块重叠率（与真实 PR diff 对比）
Token 消耗
统计显著性（配对 t 检验）

实际数据：在大型生产仓库上，好的 CLAUDE.md 比无 CLAUDE.md 提升 ~27% 的测试解决率。

工具二：claude-benchmark（综合评分）

bash

# 运行基准测试
claude-benchmark run --profiles empty,current,optimized

# 评分维度（满分 100）：
#   测试通过率：25%（pytest 自动化）
#   代码质量/lint：15%（Ruff 自动化）
#   圈复杂度：10%（Radon 自动化）
#   LLM 评估：50%（Claude Haiku 评判可读性、架构、正确性）

关键发现：

对通用编码任务，空 CLAUDE.md 与详细 CLAUDE.md 的差异仅 0.6 分（百分制）
对项目特定任务，针对性的 CLAUDE.md 提供了显著提升
模型选择比 prompt 工程影响更大

工具三：Claude Code 贡献度指标（GitHub 集成）

Anthropic 官方提供的度量方式：

跟踪使用 Claude Code 辅助的 PR 合入数量
代码提交量对比
Anthropic 内部数据：Claude Code 使工程师日均合并 PR 数增加 67%

4.3 本项目的验证策略

针对本项目 CLAUDE.md 的验证建议：

验证清单：
□ 新会话中，Claude 是否知道项目用 Python 3.12+、tRPC、LangGraph？
□ 要求"运行测试"时，Claude 是否使用 pytest 而非其他测试框架？
□ 要求"格式化代码"时，Claude 是否调用 yapf/format.sh？
□ 修改子智能体时，Claude 是否理解领导智能体→子智能体的层级？
□ 创建新异常类时，Claude 是否继承 CodegenError？
□ 修改配置时，Claude 是否知道配置来自 Rainbow 平台？
□ 首条消息的回复中，Claude 是否无需额外提问即可开始工作？

4.4 持续监控策略

                    ┌──────────────┐
                    │ 日常开发观察  │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
     ┌────────▼──────┐ ┌──▼────────┐ ┌─▼──────────────┐
     │ Claude 是否遵 │ │ 是否需要  │ │ 输出代码是否符  │
     │ 循了项目规范？│ │ 重复解释？│ │ 合项目架构？    │
     └────────┬──────┘ └──┬────────┘ └─┬──────────────┘
              │           │            │
              ▼           ▼            ▼
     ┌──────────────────────────────────────┐
     │ 未遵循 → 优化 CLAUDE.md 中的规则     │
     │ 重复解释 → 补充缺失的上下文          │
     │ 不符合 → 增强架构描述                │
     └──────────────────────────────────────┘

5. 本项目 CLAUDE.md 实践分析

5.1 当前 CLAUDE.md 评估

本项目的 CLAUDE.md 位于项目根目录（/data/workspace/trpc-codegen-agent-lingshan/CLAUDE.md），约 100 行。

做得好的方面：

方面	评价
项目概述	简洁准确，2 行讲清技术栈和目标
常用命令	覆盖完整：构建、启动、测试、格式化
代码风格	具体明确（yapf、ruff、行宽 120）
架构描述	详细记录了智能体层级、核心模式、请求流程
异常层级	用树形图清晰展示继承关系
核心模块	列出了每个关键文件的职责

可优化的方面：

方面	建议
长度适中但偏描述性	部分内容可以更"指令化"（Principle 1）
缺少 Do/Don't 约束	建议增加显式的禁止规则
缺少子目录级 CLAUDE.md	可为 `team_agent/`、`config/` 等目录添加局部规则
未记录测试策略	建议补充测试相关的约定

5.2 注入方式验证

在当前环境（Cursor IDE）中，CLAUDE.md 通过 always_applied_workspace_rules 注入：

xml

<always_applied_workspace_rules>
  <always_applied_workspace_rule name="/data/workspace/trpc-codegen-agent-lingshan/CLAUDE.md">
    （完整 CLAUDE.md 内容）
  </always_applied_workspace_rule>
</always_applied_workspace_rules>

每次对话中，CLAUDE.md 的内容作为 system prompt 的一部分始终可见，确保 Claude 在回答任何问题时都拥有项目上下文。

6. 与其他 AI 编码工具的对比

6.1 各工具的上下文配置文件

工具	配置文件	位置	格式	多文件	跨工具
Claude Code	`CLAUDE.md`	项目根 + 子目录	Markdown	是	否
Cursor	`.cursorrules` / `.cursor/rules/*.mdc`	项目根	Markdown/MDC	是	否
GitHub Copilot	`.github/copilot-instructions.md`	.github/	Markdown	是	否
OpenAI Codex	`AGENTS.md`	项目根 + 子目录	Markdown	是	是（通用）
Gemini CLI	`GEMINI.md`	项目根	Markdown	是	否
Windsurf	`.windsurfrules`	项目根	Markdown	是	否

6.2 CLAUDE.md 的独特优势

层级覆盖：全局 → 项目 → 子目录 → .local.md，最丰富的层级体系
深度优化：专门为 Claude 的理解方式设计
Memory 集成：配合 MEMORY.md 自动记忆上下文

6.3 多工具协同策略

如果团队同时使用多个 AI 工具：

方案 A：统一源文件 + 自动同步
  docs/ai-rules-base.md → pre-commit hook → CLAUDE.md + .cursorrules + AGENTS.md

方案 B：AGENTS.md 作为基础 + 工具特化
  AGENTS.md（通用规则） + CLAUDE.md（Claude 特有优化）

方案 C：接受可控差异
  各工具各自维护，核心规则保持一致

总结

CLAUDE.md 的核心价值

没有 CLAUDE.md:                      有好的 CLAUDE.md:
┌──────────────────────┐            ┌──────────────────────┐
│ 每次会话重新解释     │            │ 第一条消息即开始工作  │
│ Claude 猜测你的规范  │            │ 遵循你的编码规范      │
│ 使用错误的工具/命令  │            │ 运行正确的命令        │
│ 生成不符合架构的代码 │            │ 理解项目架构          │
│ 团队成员体验不一致   │            │ 全团队一致的 AI 行为  │
└──────────────────────┘            └──────────────────────┘

关键行动项

保持精简：80-150 行为宜，删除 Claude 本身就知道的通用规则
写指令不写描述：每条规则都应能改变 Claude 的行为
重要规则放前面：Claude 对靠前指令的遵循率更高
迭代测试：像代码一样测试你的 CLAUDE.md
提交到 Git：团队共享一致的 Claude 行为
月度审查：删除过时规则，补充新的约定

文档生成日期：2026-04-15基于 TRPC Codegen Agent 项目实践与行业最佳实践分析

docs

hook

watcher

CLAUDE.md 深度分析：为什么写、怎么写、如何与 System Prompt 结合、如何验证效果 ​

目录 ​

1. 为什么 Claude 需要 CLAUDE.md ​

1.1 核心问题：无记忆的 AI ​

1.2 CLAUDE.md 的本质定位 ​

1.3 关键类比 ​

2. CLAUDE.md 的实现规则与规范 ​

2.1 文件层级系统 ​

2.2 推荐的 7 大核心节（Section） ​

① 项目概述（2-3 行） ​

② 常用命令 ​

③ 代码风格 ​

④ 架构 ​

⑤ 关键约束（Do / Don't） ​

⑥ 目录结构 ​

⑦ 入口点与配置 ​

2.3 六大编写原则 ​

2.4 常见反模式 ​

3. CLAUDE.md 与 System Prompt 的结合机制 ​

3.1 技术架构 ​

System Prompt 的组成 ​

关键发现：CLAUDE.md 不在 system prompt 中 ​

为什么这样设计？ ​

3.2 在 Cursor IDE 中的集成方式 ​

3.3 注入时序与 Token 预算 ​

3.4 与本项目的 Instruction 系统的关系 ​

4. 如何验证 CLAUDE.md 对回答质量的帮助 ​

4.1 定性验证法（人工观察） ​

方法一：规则合规性测试 ​

方法二：A/B 对比测试 ​

4.2 定量验证法（自动化基准测试） ​

工具一：mdarena（基于真实 PR 的基准测试） ​

工具二：claude-benchmark（综合评分） ​

工具三：Claude Code 贡献度指标（GitHub 集成） ​

4.3 本项目的验证策略 ​

4.4 持续监控策略 ​

5. 本项目 CLAUDE.md 实践分析 ​

5.1 当前 CLAUDE.md 评估 ​

5.2 注入方式验证 ​

6. 与其他 AI 编码工具的对比 ​

6.1 各工具的上下文配置文件 ​

6.2 CLAUDE.md 的独特优势 ​

6.3 多工具协同策略 ​

总结 ​

CLAUDE.md 的核心价值 ​

关键行动项 ​

CLAUDE.md 深度分析：为什么写、怎么写、如何与 System Prompt 结合、如何验证效果

目录

1. 为什么 Claude 需要 CLAUDE.md

1.1 核心问题：无记忆的 AI

1.2 CLAUDE.md 的本质定位

1.3 关键类比

2. CLAUDE.md 的实现规则与规范

2.1 文件层级系统

2.2 推荐的 7 大核心节（Section）

① 项目概述（2-3 行）

② 常用命令

③ 代码风格

④ 架构

⑤ 关键约束（Do / Don't）

⑥ 目录结构

⑦ 入口点与配置

2.3 六大编写原则

2.4 常见反模式

3. CLAUDE.md 与 System Prompt 的结合机制

3.1 技术架构

System Prompt 的组成

关键发现：CLAUDE.md 不在 system prompt 中

为什么这样设计？

3.2 在 Cursor IDE 中的集成方式

3.3 注入时序与 Token 预算

3.4 与本项目的 Instruction 系统的关系

4. 如何验证 CLAUDE.md 对回答质量的帮助

4.1 定性验证法（人工观察）

方法一：规则合规性测试

方法二：A/B 对比测试

4.2 定量验证法（自动化基准测试）

工具一：mdarena（基于真实 PR 的基准测试）

工具二：claude-benchmark（综合评分）

工具三：Claude Code 贡献度指标（GitHub 集成）

4.3 本项目的验证策略

4.4 持续监控策略

5. 本项目 CLAUDE.md 实践分析

5.1 当前 CLAUDE.md 评估

5.2 注入方式验证

6. 与其他 AI 编码工具的对比

6.1 各工具的上下文配置文件

6.2 CLAUDE.md 的独特优势

6.3 多工具协同策略

总结

CLAUDE.md 的核心价值

关键行动项