为什么 35 行的 CLAUDE.md 比 100 行更管用？—— 揭秘 Claude Code 提示词优化法则

引言

在使用 Claude Code 等 AI 辅助开发工具时，很多开发者都有这样一个误区：认为 CLAUDE.md（项目专属系统提示词）写得越长越详细，AI 的表现就会越好。于是把各种编码规约、历史片段、代码风格全都塞进去，硬生生拼凑出上百行的文档。

但实际效果往往事与愿违：CLAUDE.md 越长，Claude Code 反而越容易“不听话”。

一份 100 行的提示词，效果往往比不上一份精简到 35 行、并把次要规则拆分到 .claude/rules/ 的配置。本文将基于 Claude Code 的底层注入机制，探讨为什么会出现这种情况，以及如何通过“注意力经济学”来优化你的 CLAUDE.md。

底层机制：为什么长指令会被“埋没”？

要理解为什么指令会失效，首先要了解 CLAUDE.md 是如何被 AI 读取的。根据官方文档：

CLAUDE.md adds the contents as a user message following Claude Code’s default system prompt.

这是一个非常关键的细节：CLAUDE.md 并不是作为 System Prompt 存在的，而是被追加为一条 User Message。 这种机制导致了四种削弱指令效果的现象：

位置偏差（Recency Bias）：大语言模型对最新输入的信息赋予更高权重。当对话进行了几十轮后，位于最开头的 CLAUDE.md 就会在最新指令的对比下变得“人微言轻”。
注意力稀释（Attention Dilution）：上下文 Token 越多，分配给每个 Token 的注意力就越少。把 30 行能说清楚的事写成 100 行，反而会稀释核心指令的权重。
指令冲突（Instruction Drift）：如果在对话中临时要求“这次跳过测试”或“换个写法”，这些即时指令会覆盖掉 CLAUDE.md 中的默认原则。
上下文压缩：在长对话中，Claude Code 会在内部对历史消息进行压缩（compact），导致 CLAUDE.md 中细微的规约丢失。

graph TD A[System Prompt] --> B[CLAUDE.md
作为首条 User Message 注入] B --> C[对话轮数增加] C --> D{衰减效应} D -->|位置偏差| E[优先遵循最新对话] D -->|注意力稀释| F[核心原则权重下降] D -->|上下文压缩| G[丢失细节规约]

注意力经济学：每一行都有“成本”

CLAUDE.md 中的每一行都在消耗 Claude 有限的“注意力资源”。我们评估每一行内容的标准，应该是它能带来多大的“判断改善”。

收益极高的指令

技术栈与版本号：

1
2
- Next.js 15 (App Router)
- TypeScript 5.7 (strict mode)

仅仅写上版本号和模式，就能彻底切断 AI 生成过时代码（如 Pages Router 语法）的可能。

行为原则（Behavioral Principles）：

1
2
- 3步骤以上的任务，必须先使用 Plan 模式制定计划。
- 只有在证明代码能运行（如通过测试）后，才能将任务标记为完成。

这能从根本上改变 AI 的思考和工作流程，防止它上来就盲目写代码导致最终翻车。

收益极低的指令

可被自动化工具替代的规范：

1
2
- 缩进使用 2 个空格
- 必须加分号

这些完全可以（也应该）交给 Prettier 或 ESLint 等工具在保存时自动处理。把宝贵的 AI 注意力浪费在格式上，是极度低效的。

黄金法则：该留什么，该扔什么？

为了将注意力用在刀刃上，我们需要对提示词进行断舍离。

1. 必须留在 `CLAUDE.md` 的全局核心

这是 Claude 在执行任何操作时都需要知道的全局上下文：

项目摘要（1-2 行说明这是个什么项目）
核心技术栈（带上具体版本）
常用命令（如何启动、测试、构建）
目录结构（核心功能模块的位置）
行为原则（强制验证、强制读码、强制规划）

2. 移交到 `.claude/rules/` 的按需规则（Conditional Rules）

对于只有在特定场景下才需要遵守的规约，应当利用条件规则剥离出去。通过在 .claude/rules/*.md 文件的 Frontmatter 中配置 paths，可以让这些规则仅在 AI 编辑特定文件时才被注入。

例如，针对 API 接口的校验规则 api-validation.md：

1
2
3
4
5
6
7
---
paths: src/api/**/*.ts,src/routes/**/*.ts
---

# API 校验规约
- 所有接口必须使用 Zod 校验入参
- 错误统一返回 422 状态码

这样不仅能大幅精简主 CLAUDE.md，还能因为“按需注入”使得规则在对话后期依然保持强大的约束力（不受位置偏差影响）。

3. 必须删掉的无用信息

旧代码片段：代码是会快速迭代的，写死在文档里的代码片段很快就会腐化。
“正确的废话”：比如“遵循 DRY 原则”、“写出优雅的代码”，现代大模型本身就内置了这些最佳实践，写出来只是在白白浪费 Token。

行动建议：打造你的 35 行模板

摒弃长篇大论，尝试用下面这个极简但控制力极强的模板重构你的 CLAUDE.md：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# [项目名称]

[1-2句话的项目功能概述]

## 技术栈
- [框架名称] v[版本号]
- [语言名称] v[版本号] (strict mode)
- [核心库/数据库]

## 常用命令
| 用途 | 命令 |
|---|---|
| 启动开发 | `npm run dev` |
| 运行测试 | `npm test` |
| 构建产物 | `npm run build` |

## 目录架构
| 路径 | 职责 |
|---|---|
| `src/components/` | 纯 UI 组件 |
| `src/app/` | 页面与路由 |

## 行动原则
- **强制规划**：3 个步骤以上的任务，必须先输出计划并等待确认。
- **强制验证**：必须运行测试证明代码无误后，才能认为任务完成。
- **先读后写**：在修改任何文件前，必须先阅读现有代码。
- **及时止损**：如果多次尝试失败或上下文逼近极限，主动停止并请求人类介入。

将复杂的测试规约、特定组件的写法拆分至 .claude/rules/ 目录下。你会发现，虽然字数变少了，但 Claude 的输出质量、遵循规则的意愿，反而得到了肉眼可见的提升。

少即是多，在 AI 驱动开发的时代，这同样是一条铁律。

引言