很多人用 Agent 工具（比如 Claude Code）的方式是：打开对话，描述需求，拿到结果。但在实际项目中，你会发现 Agent 经常"失忆"——文件乱放、命名随意、每次都要重新解释你的偏好。

这篇教程帮你建立一个从上到下的规则体系，让 Agent 每次醒来都知道该怎么做。

CLAUDE.md 是什么

CLAUDE.md 是 Claude Code 在进入工作目录后第一个读取并遵守的文件。你可以把它理解成 Agent 的行为准则。它分两层：

• 全局 CLAUDE.md：放在用户主目录下，所有项目通用
• 项目级 CLAUDE.md：放在项目根目录下，只对当前项目生效

规则从上往下穿透，全局约束打底，项目约束细化。

开始前的准备

• 已安装 Claude Code（或类似的 Agent 工具）
• 有一个需要长期维护的项目目录
• 预计耗时：30-60 分钟

具体步骤

第一步：创建全局 CLAUDE.md

在用户主目录下创建 ~/.claude/CLAUDE.md，写入你的通用工作原则。以下是经过实战验证的模板，你可以根据自己的情况修改：

## 关于我
[你的身份和角色，比如：全栈开发者 / 产品经理 / 独立开发者]

## 第一性原理
所有决策从问题本质出发，不因"惯例如此"照搬。
不要谄媚。不要夸我的想法好。给我真实判断——方案有问题直接指出来。

## 约束先行
无论开发项目还是知识管理项目，第一步永远是建规则：
- 新项目先写 CLAUDE.md
- 新目录先定结构约定（什么放哪、怎么命名、何时清理）
- 没有规范的工作空间不动手
- 需要调整规范时先改文档、再改实践，不要反过来

## 工作方式
- 默认中文，代码用英文
- 结论先行，再给理由
- 遇到模糊需求，先给最合理的方案，再问要不要调整

## 开发习惯
- 改完主动跑验证（test / lint / build），不要只改不验
- 不要为了让代码跑起来而注释掉报错，找根本原因
- 密钥、token、密码不进代码

提示: 全局 CLAUDE.md 不要写太多项目相关的规则，只放"你是谁"和"你的做事原则"。项目细节放到下一层。

第二步：创建项目级 CLAUDE.md

在每个项目根目录下创建 CLAUDE.md，定义这个项目的专属规则：

# 项目名称

## 项目概述
[一句话说明这个项目做什么]

## 目录结构

src/ components/ # UI 组件 hooks/ # 自定义 Hooks utils/ # 工具函数 pages/ # 页面组件 tests/ docs/ _sandbox/ # 实验性内容，超过30天自动清理

## 命名规范
- 组件文件：PascalCase（如 UserProfile.tsx）
- 工具函数：camelCase（如 formatDate.ts）
- 常量：UPPER_SNAKE_CASE
- 测试文件：[源文件名].test.ts

## 技术栈
- 框架：Next.js 14
- 状态管理：Zustand
- 样式：Tailwind CSS
- 包管理：pnpm

## 开发规范
- 新增组件必须同时写测试
- API 路由统一放在 src/app/api/ 下
- 环境变量统一在 .env.local 中管理

第三步：验证规则是否生效

保存 CLAUDE.md 后，在项目目录下启动 Claude Code，执行一个简单任务，观察它是否：

1. 读取了 CLAUDE.md 中的规范
2. 按照你定义的目录结构放置文件
3. 遵循了命名规范

你可以直接问它："读一下这个项目的 CLAUDE.md，告诉我你了解到了哪些规范。"

为什么"约束先行"比 Prompt 技巧更重要

Agent 的短期记忆会在关闭对话后丢失。下次打开，它唯一能看到的就是你留下来的文档和记忆文件。你的文档里写了什么，直接决定了 Agent 每一次醒来时是清醒的还是懵的。

关键原则：

• 规则写在文档里，不要只放在脑子里。你脑子里知道的东西，如果没有写进文档，对 Agent 来说就是不存在的
• 规则从上往下穿透。全局规范是城市主干道，项目规范是片区支路
• 先改文档再改实践。规则不是死的，但改规则也要走规则的路

常见问题

• CLAUDE.md 写多长合适？: 全局的控制在 30-50 行以内，项目级的根据复杂度调整。太长 Agent 会忽略，太短约束不够
• 规则和 Agent 的实际行为不一致怎么办？: 先改文档，再让 Agent 重新执行。不要在对话里口头纠正后就不管了
• 不同项目之间怎么复用规则？: 把通用的部分放在全局 CLAUDE.md 里，项目特有的放在项目级里。两层叠加生效