记忆与规则

Claude Code 每次会话都是新的上下文窗口。要让它长期记住项目约定,主要靠两套机制:你写的 CLAUDE.md,以及 Claude 自动积累的 auto memory。

#CLAUDE.md 与 auto memory

这两者都是上下文,不是强制权限。想硬性阻止危险动作,用 权限规则 或 Hooks。

#文件位置

Claude 从当前目录向上查找 CLAUDE.md 和 CLAUDE.local.md。越靠近当前工作目录的内容越晚进入上下文,因此更具体。子目录里的 CLAUDE.md 会在 Claude 读取相关文件时按需加载。

#推荐结构

your-project/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    └── rules/
        ├── testing.md
        ├── api.md
        └── frontend.md

CLAUDE.md 控制全局骨架:

# 项目约定

- 包管理器: pnpm
- 改完先跑 `pnpm lint`,涉及类型再跑 `pnpm typecheck`
- 不要把 `.env`、Key、生产配置写入文档或提交

## 目录

- 页面: `src/app`
- 组件: `src/components`
- 文档: `content/docs`

## 工作方式

- 大改动先给计划
- 修改 UI 后需要检查浅色和暗色
- 输出最终结果时必须列出验证命令

#写得短,才能更稳

目标控制在 200 行以内。越长越吃上下文,也越容易互相矛盾。

有效规则通常有三个特点:

• 具体:写 pnpm lint,不要写“跑必要检查”
• 可验证:写“不要提交 .env”,不要写“注意安全”
• 按主题分组:构建、测试、目录、风格分开

#导入其它文件

CLAUDE.md 支持 @path 导入。相对路径以当前 CLAUDE.md 所在目录为基准,最多递归 4 层。

@README.md
@docs/development.md

## Claude Code 专用补充

- 优先使用现有组件
- 不做无关重构

如果只是想展示字符串,用反引号包住,例如 ` @README.md `。

首次导入项目外部文件时,Claude Code 会要求确认。拒绝后不会自动再弹,需要你手动调整。

#AGENTS.md 项目

Claude Code 默认读取 CLAUDE.md,不是 AGENTS.md。已有 AGENTS.md 的仓库可以这样兼容:

@AGENTS.md

## Claude Code

- 大范围改动先使用 plan mode
- UI 修改后检查移动端、浅色和暗色

也可以用 symlink,但 Windows 上更推荐 @AGENTS.md 导入。

#.claude/rules/

规则文件是更细粒度的 CLAUDE.md。没有 frontmatter 的规则每次启动都加载:

# 测试规则

- 修复 bug 后优先跑相关单测
- 不要跳过失败测试

带 paths 的规则只在相关文件被读取时加载:

---
paths:
  - "src/api/**/*.ts"
  - "app/api/**/*.ts"
---

# API 规则

- 所有输入必须校验
- 错误返回统一 `{ code, message }`
- 不把服务端密钥写到客户端 bundle

这对大型仓库很重要,能减少上下文噪音和缓存失效。

#Auto memory

Auto memory 会记录 Claude 从纠正中学到的内容,按仓库共享。它适合保存“这个项目里实际踩过坑”的经验,例如构建命令、测试前置条件、常见失败原因。

常见控制方式:

#排错

#官方参考

• How Claude remembers your project
• Explore the .claude directory
• Debug your configuration