CLAUDE.md

CLAUDE.md 与记忆

使用 CLAUDE.md、rules、AGENTS.md 和 auto memory 作为持久上下文，同时避免每次会话都过度膨胀。

持久上下文来源

Claude Code 有几种跨轮次和跨会话保留知识的方式：

来源适合何时加载
CLAUDE.md共享项目指令和关键规范会话启动；嵌套文件按需
.claude/rules/全局或 path-scoped rules会话启动，或读取匹配文件时
AGENTS.md多个 coding agents 共享的说明从 CLAUDE.md import，或工具直接支持时
Auto memoryClaude 应记住的项目事实会话启动
Skills可复用流程和长参考资料触发时才加载

经常需要 Claude 看到的事实放 CLAUDE.md；有作用域的行为放 rules；较长工作流放 skills，不要每次都加载。

CLAUDE.md 文件层级

Claude Code 在四个作用域读取 CLAUDE.md，从最宽泛到最具体依次加载：

  1. 企业策略（Managed policy）— /Library/Application Support/ClaudeCode/CLAUDE.md（macOS）、/etc/claude-code/CLAUDE.md（Linux/WSL）、C:\Program Files\ClaudeCode\CLAUDE.md（Windows）。由 IT 通过 MDM / 组策略统一下发，用户无法覆盖。
  2. 用户级（User）— ~/.claude/CLAUDE.md。跨所有项目的个人偏好。
  3. 项目级（Project）— ./CLAUDE.md 或 ./.claude/CLAUDE.md。提交到 git，团队共享。
  4. 本地级（Local）— ./CLAUDE.local.md。当前项目的个人备注；放进 .gitignore。

从 CWD 一直到文件系统根的所有 CLAUDE.md 会在会话开始时拼接载入。子目录里的 CLAUDE.md（位于 CWD 之下）是按需加载 —— Claude 读到对应目录里的文件时才载入，不会启动时合并。

Imports（导入）。 任何 CLAUDE.md 都可以用 @path/to/file 引入其他文件（最大深度 5 层）。如果项目里已经有给其他 AI 工具用的 AGENTS.md，在 CLAUDE.md 顶部加一行 @AGENTS.md 即可让两边共用同一份源。

Auto memory（自动记忆，v2.1.59+） 是并行的记忆机制：Claude 自己往 ~/.claude/projects/<project>/memory/MEMORY.md 写笔记。每次会话开始时 MEMORY.md 的前 200 行（或 25 KB）会被载入。运行 /memory 查看；在聊天里说"记住……"会写入 auto memory。

Rules

Rules 位于 .claude/rules/。当某条约定只适用于仓库的一部分时，它比全局 CLAUDE.md 更合适：

.claude/rules layout
.claude/rules/
├── project.md
├── frontend.md
└── api.md

当指导比整个项目更具体、但又比聊天消息更持久时，用 rules。每个 rule 文件保持短小、可执行。

AGENTS.md

如果仓库已经有 AGENTS.md 给其他 agent 工具使用，不要复制一份。在 CLAUDE.md 中 import：

markdown
@AGENTS.md

这样跨 agent 指令只有一个真源。

精准原则

对于 CLAUDE.md 中的每一行，问自己：如果我删除这行，Claude 会犯错吗？

  • 如果是 → 保留它
  • 如果否 → 删除它

简短而精准的 CLAUDE.md 胜过冗长而泛泛的版本。上下文窗口中的每个 token 都有成本——无关的上下文会分散 Claude 对重要内容的注意力。

应该包含的内容

构建和测试命令

最具影响力的内容。Claude 会使用这些命令来运行、测试和检查你的代码：

markdown
## 构建和测试

- npm run dev # 启动开发服务器（端口 3000）
- npm test # 运行所有测试
- npm test -- -t "auth" # 运行匹配 "auth" 的测试
- npm run lint # eslint 检查
- npm run typecheck # tsc --noEmit

架构和关键文件

markdown
## 架构

- Monorepo: apps/web (Next.js), apps/api (Express), packages/shared
- 数据库: PostgreSQL via Prisma (schema 位于 prisma/schema.prisma)
- 认证: NextAuth.js with JWT strategy
- 关键入口: apps/web/src/pages/\_app.tsx

编码规范

只包含 Claude 在没有明确指导时会出错的规范：

markdown
## 规范

- 使用 server actions 而非 API routes 处理数据变更
- 所有日期以 UTC 存储，以用户时区显示
- 错误边界包裹每个路由段
- 永远不要使用 any；优先使用 unknown + 类型收窄

项目特定警告

markdown
## 警告

- payments 模块使用 Stripe API v2023-10-16（不是最新版）
- 不要修改已应用的迁移文件
- legacy/ 目录正在逐步淘汰；不要在那里添加新代码

生成和更新

  • /init — 通过扫描项目自动生成 CLAUDE.md
  • /memory — 会话内的记忆浏览器：列出当前载入的 CLAUDE.md / CLAUDE.local.md / rules 文件，可直接打开编辑
  • 在聊天里要求 Claude — "把 X 加到 CLAUDE.md"会直接修改文件；"记住 X"则写入 auto memory
  • 手动编辑 — 像对待其他配置文件一样；定期审查和精简

反模式

  • 直接复制整个 README — CLAUDE.md 不是文档，而是运行上下文。
  • 列出每个文件 — Claude 可以探索文件系统。只列出不明显的入口文件。
  • 泛泛的编码建议 — "写干净的代码" 毫无意义。"使用 server actions 而非 API routes" 才是可操作的。
  • 从不更新 — 你的项目在演进。当重大架构变更发生时，重新审视 CLAUDE.md。

为什么精简的上下文比更多上下文效果更好？

LLM 有有限的上下文窗口。每一个无关的 token 都会与重要的 token 竞争注意力。理解这种注意力机制是有效提示工程的关键——无论是在 CLAUDE.md 还是其他任何提示中。

学习 Prompts 和 Structured Output 基础

延伸阅读

  • 快速开始 — 包含基础 CLAUDE.md 的快速设置
  • Hooks — 执行 CLAUDE.md 单独无法保证的规则
  • 上下文管理 — 理解哪些内容会进入窗口
  • Skills — 把可复用流程移出持久上下文

继续实践

CLAUDE.md 与记忆 的核心概念已经读完

如果你想把理解变成可复用的能力，可以到 AgentWay 继续练习

进入练习