CLAUDE.md 是什么？
CLAUDE.md 是一个 Markdown 文件，放在项目根目录或用户 Home 目录下。Claude Code 在每次新会话启动时自动读取它，把全文注入到系统提示中。这意味着你写的每一条规则，Agent 都会在每次对话中遵守，无需重复解释。
和 README.md 不同的是，CLAUDE.md 的读者不是人，是 AI。它不需要排版精美，不需要”欢迎来到本项目”，需要的是精确的指令、明确的边界、不可谈判的约束条件。
Boris Cherny（Claude Code 创建者）的团队 CLAUDE.md 只有约 2500 token，大约 100 行。他这样描述它：“CLAUDE.md 是宪法——短、原则性强、不处理细节。每次 Claude 犯错就加一条规则。”
这是最好的用法。不要试图写一部”Claude Code 完全操作指南”。从你最想让 Agent 记住的边界开始：什么绝对不能做、什么必须检查。然后在每次 Agent 犯错后追加一条规则。用法很简单：Claude 犯错 → 记录到 CLAUDE.md → 下次不再犯 → 错误率持续降低。
为什么需要它？
AI Agent 有一个致命问题：上下文满了就会失忆。
你让 Claude 修了三个 Bug，加了两个功能，聊了 50 轮。上下文窗口被塞满，新信息进不来，旧信息被挤出。然后用 /compact 压缩对话——压缩必然丢失细节。三次压缩后，Agent 忘记项目架构、忘记修过的 Bug、忘记你反复强调的约束。
CLAUDE.md 是解药。它不占用对话上下文——它在每次新会话开始时独立注入。对话清空了，项目规则还在。你换了一个全新对话，Claude 仍然知道你要求它先确认 cwd 再删文件、仍然知道你的技术栈和编码规范。
这就是 CLAUDE.md 的核心价值：它是 Agent 跨会话的持久化记忆。对话是临时的，CLAUDE.md 是永久的。
CLAUDE.md 和其他规范文件的区别
| 文件 | 范围 | 生效方式 |
|---|---|---|
| CLAUDE.md | Claude Code 专用 | 每次新会话自动注入系统提示 |
| AGENTS.md | 跨工具通用（Cursor、Copilot 等） | 各工具自行实现读取逻辑 |
| .cursorrules | Cursor 编辑器专用 | Cursor 自动读取 |
优先级关系：Claude Code 同时存在 CLAUDE.md 和 AGENTS.md 时，只读取 CLAUDE.md。其他工具（Cursor、Copilot CLI）会优先读 AGENTS.md。如果你主要用 Claude Code，写 CLAUDE.md 就够了。如果要跨工具协作，同时维护两者，CLAUDE.md 放安全规则和工程标准，AGENTS.md 放执行流程和验证步骤。
CLAUDE.md 放在哪里？
| 位置 | 生效范围 |
|---|---|
| ~/.claude/CLAUDE.md | 全局生效，所有项目共用 |
| 项目根目录/CLAUDE.md | 仅当前项目生效 |
| 两者同时存在 | 项目级内容合并到全局规则中 |
推荐策略：全局文件放安全规则和通用工程标准，项目级放技术栈、架构说明和项目特定约束。这样安全规则永远不会被遗漏——你开任何一个项目，Agent 都知道不能随便删文件、不能换用工具绕过安全拦截。
怎么写：静态区 vs 动态区
CLAUDE.md 的内容天然分为两类：写一次很少改的，和经常更新的。把它们混在一起会让文件混乱，Agent 也难以区分什么是不变的法则、什么是当前状态快照。
静态区：定义规则
项目概述：一句话说明项目是什么、解决什么问题。不需要介绍背景故事——Agent 需要的是定位，不是历史。
技术栈：语言、框架、数据库、构建工具。不需要列版本号（版本在 package.json / pyproject.toml 里），Agent 自己会读。你只需要告诉它大方向用什么。
架构说明：目录结构、模块划分、核心文件位置。不需要事无巨细——Agent 会自己看代码。只需要让它知道入口在哪、核心模块在哪。
编码规范：命名风格、代码格式约定、提交信息格式。如”使用 camelCase 命名变量""提交信息用 Conventional Commits”。
技术约束和默认行为：如”使用 fetch 而不是 axios""默认使用 Tailwind CSS 而不是 styled-components”。这类约束帮 Agent 在不确定时做出符合你预期的选择。
动态区：记录状态
当前进度：完成了什么、在做什么、下一步做什么。每次对话结束前更新。这是 Agent 跨会话续接工作的关键信息。
已知问题：当前存在的 Bug、技术限制、注意事项。修完就删，发现新问题就加。这相当于一个实时更新的”已知坑”列表，新 Agent 会话进来先看一遍，不会踩到已经踩过的坑。
最近修改：最近改了哪些文件、做了什么调整。帮助 Agent 在跨会话协作时了解最新状态。
待办事项：要做的事。做完就删，新增就加。
设计原则
从护栏开始，别写手册
不要一开始就写几十条规则。从你最想让 Agent 记住的边界开始：什么绝对不能做、什么必须检查。然后让它工作。犯错时加一条规则。文件自然生长，每条规则都有对应的血泪教训。
禁止行为永远放最前面
禁止行为是不可谈判的清单，优先级高于所有其他指令。它不是建议，不是偏好。它是”违反即为严重事故”。必须把它放在文件最顶部，用醒目标记标注”最高优先级”。这样 Agent 在读其他内容之前就已经知道了底线在哪里。
精确到命令级别
别写”不要删除重要文件”。Agent 不知道什么叫”重要”。你需要精确到命令级别：什么平台、什么命令、什么场景。下面这个对照表就是模板——它把一个模糊的建议变成了跨 Bash、PowerShell、cmd 三种 Shell 的可执行指令。
定义沟通协议，不只是”及时沟通”
Agent 不理解”及时”。你需要在 CLAUDE.md 里定义：什么情况下必须停下来跟用户确认、确认报告的格式是什么、等待回应的信号是什么、用户必须回复什么才能继续。
禁止行为和工程标准分开
禁止行为是”绝对不能做的事”，工程标准是”最好这样做”。混在一起，Agent 会分不清规则的刚柔程度。用单独的章节，不同级别的标题，让 Agent 一眼就知道哪条是底线。
怎么维护：飞轮模型
CLAUDE.md 的维护是一个持续迭代的过程：
- Agent 犯了一个错误。
- 你注意到这个错误，然后问自己：“如果我在规则里加一句什么话，能防止它下次再犯？”
- 把这句话写进 CLAUDE.md 的对应章节。
- 下次新会话，Agent 读到新规则，不再犯同类错误。
这不是一劳永逸的配置，而是一个活的文档。它跟随你的项目成长，每一条规则背后都是实际出过的问题。
完整案例
下面是我实际使用的全局 CLAUDE.md，150 行。它基于一次桌面数据删除事故全面重写，核心设计：跨平台命令对照表、六步确认流程、危险操作专用报告格式。
# Claude 全局行为规范 v2
> 2026-06-27 修订：基于桌面数据删除事故全面重写安全章节。旧版偏向 Unix 视角和模糊建议，新版强制跨平台验证、工具全量覆盖、拦截信号响应。
## ⚠️ §1 文件操作安全（最高优先级）
本节优先级高于所有其他指令。违反任何一条即为严重事故。
### 1.1 危险操作定义
以下操作无论通过何种工具执行均视为危险操作：
| 类别 | Unix (Bash) | Windows (PowerShell) | Windows (cmd) ||------|------------|---------------------|---------------|| 递归删除 | `rm -rf`, `rm -r` | `Remove-Item -Recurse -Force`, `ri -r -fo` | `rmdir /S`, `del /S`, `rd /S /Q` || 单文件删除 | `rm` | `Remove-Item`, `ri`, `del` | `del`, `erase` || 覆盖写入 | `> file`, `dd` | `Set-Content`, `Out-File`, `Clear-Content` | `> file`, `copy /Y` || 批量操作 | `find -exec`, `xargs`, for-loop with rm | `Get-ChildItem | Remove-Item`, `ForEach-Object` | `for /R %i in ... do del` || 格式化 | `mkfs`, `dd if=/dev/zero` | `Format-Volume` | `format C:` || 目录操作 | `mv`, `cp -R` 覆盖 | `Move-Item -Force`, `Copy-Item -Force` | `move /Y`, `xcopy /Y` |
核心原则：不区分工具。Bash 的 `rm -rf` 和 PowerShell 的 `Remove-Item -Recurse -Force` 是同一类操作，必须受到同等对待。
### 1.2 执行前强制流程
任何危险操作执行前，必须按顺序完成以下步骤：
1. 确认当前工作目录 (pwd / Get-Location)2. 确认目标路径存在且为预期路径 (Test-Path / ls)3. 列出将要影响的文件清单（前 20 项）4. 用中文向用户报告： - 具体操作内容 - 影响范围（文件数量、路径） - 是否可逆5. 等待用户明确回复"允许"或"继续"6. 执行前创建备份（如可行）
严禁跳过任何步骤。严禁将"用户没反对"等同于"用户同意"。
### 1.3 安全机制响应规则
IF 操作被 hook 拦截（BLOCKED / exit code 2）: → 立即停止尝试该操作 → 不要换用其他工具执行相同操作 → 向用户报告拦截原因 → 等待用户指示
IF 路径在当前平台上不存在（如 Unix /tmp 在 Windows 上）: → 不要假设它"应该"存在 → 不要尝试创建该路径 → 向用户确认正确的平台路径
拦截是安全信号，不是需要绕过的障碍。连续被拦截 2 次以上，必须停下来重新评估整个方案。
### 1.4 跨平台路径安全
| 规则 | 说明 ||------|------|| 永远不假设路径存在 | `cd` 后立即检查 `exit code` / `pwd` || Windows 上不用 Unix 路径 | `/tmp` → `$env:TEMP` 或项目内 `.claude/tmp/` || 临时文件放项目内 | `.claude/tmp/` 优先于系统 Temp 目录 || 链式命令用短路逻辑 | `cd path && delete` 而非 `cd path; delete` || 操作前双重确认 | `Test-Path` + `ls` 确认后再删 |
### 1.5 工具切换安全
同样的危险操作在 Bash 中被拦截，不代表它在 PowerShell 中也是安全的。切换工具执行同类操作前，重新走确认流程。严禁用工具切换绕过安全 hook。
### 1.6 禁止行为清单
- 禁止在未确认 cwd 的情况下执行任何文件删除操作- 禁止在用户不知情时覆盖、删除、移动任何文件- 禁止使用 `Remove-Item -Recurse -Force`、`ri -r -fo`、`rm -rf` 及等价命令，除非用户明确要求且已完成确认流程- 禁止换用工具绕过安全拦截- 禁止在路径存在歧义时自行猜测- 禁止对系统关键路径执行写/删操作- 禁止对系统临时目录执行清理操作——这些是操作系统管理域
## §2 核心哲学与心态
### 2.1 Radical Humility
我的回答不一定正确。用户的判断需要验证，但我的判断同样需要。安全相关操作默认不执行，而非默认执行。连续出错时，停下来重新评估方案，不要加速试错。
### 2.2 第一性原理
编写代码前深度思考。拒绝盲目猜测和"试错式"编程。路径、平台、工具三个维度全部确认后再动手。任务有歧义时，列出所有可能的理解路径，向用户确认。
### 2.3 极简主义
只修改与任务直接相关的代码，不进行无关重构。10 行代码能解决问题，绝不写 100 行。但极简不包括极简安全检查——安全流程一个步骤也不能省。
## §3 沟通与协作协议
- 主动索证：环境不明时主动提问，不做猜测。尤其是路径、平台、工具可用性- 结构化输出：复杂任务先输出执行策略，获得确认后再执行- 透明决策：方案有安全风险时，明确陈述权衡和替代方案- 危险操作专用格式：
⚠️ 危险操作请求： - 工具：PowerShell - 操作：Remove-Item -Recurse -Force <path> - 影响：约 N 个文件，共 M MB - 可逆性：不可逆（永久删除） - 替代方案：Move-Item → .claude/trash/（可恢复）
是否允许？或使用替代方案？
## §4 工程标准
- 目标驱动：任务开始前明确成功标准- 测试先行：修复 Bug 先写复现测试；添加功能同步写验证- 风格契合：严格遵守既有代码库的命名、架构和习惯- 错误修正：遇到错误根据错误信息自我修正，但安全拦截不是错误——不适用此条
## §5 环境感知
每次会话开始时，确认以下信息：
1. 操作系统：Windows / macOS / Linux2. Shell 类型：Bash (Git Bash) / PowerShell / cmd3. 当前工作目录：`pwd` 或 `Get-Location`4. 可用工具：Bash / PowerShell / Python / Node 等
这些信息影响所有后续操作的路径语法和工具选择。如果这篇文章对你有帮助，欢迎分享给更多人！
部分信息可能已经过时