存储与记忆

官方文档地址：

Claude 如何记住你的项目 - Claude Code Docs

• CLAUDE.md：由于它是“始终开启”的，内容越多，每次对话扣的钱（Token）就越多，效率也可能下降。

这份文档详细介绍了 Claude Code（Anthropic 的命令行工具）如何通过两套互补的系统来记住你的项目背景，从而在不同会话之间保持连贯性。

以下是核心内容的深度解析：

一、 核心双系统：谁在记？记什么？

Claude Code 的记忆由手动指令和自动学习共同构成，两者都会在每次对话开始时加载到上下文窗口中。

二、 CLAUDE.md：你给 Claude 定的“家规”

这是你主动控制 Claude 行为的主要方式。你可以通过以下层级来管理指令：

• 项目级 (./CLAUDE.md)：最常用的位置，用于存放项目特有的架构、测试命令和命名约定。通过版本控制与团队共享。
• 个人级 (~/.claude/CLAUDE.md)：适用于你机器上的所有项目，存放你个人的代码风格偏好或工具快捷方式。
• 组织级 (托管策略)：由 IT/DevOps 管理，强制执行公司范围的安全策略和合规要求。

💡 编写建议：

• 具体化：不要说“格式化代码”，要说“使用 2 空格缩进”。
• 简洁性：单个文件尽量保持在 200 行以下，否则 Claude 的遵循度会下降。
• 模块化：可以使用 @path/to/file 语法导入 README 或 package.json，避免重复编写。

三、 进阶组织：使用 .claude/rules/

对于大型项目，你可以将规则拆分到 .claude/rules/ 文件夹中。

• 特定路径规则：通过 YAML 配置，让规则仅在 Claude 处理特定文件（如 src/api/**/*.ts）时才加载，节省上下文空间。
• 共享规则：支持通过符号链接（Symbolic Links）在多个项目间共享一套通用的安全或编码标准。

四、 自动记忆：Claude 的“随身笔记”

这是 Claude 2.1.59 版本后的新功能，它会自动记录它认为对未来有用的信息。

• 工作机制：Claude 在修复 Bug 或构建项目时，会总结经验并写入本地的 MEMORY.md。
• 本地性：记忆存储在你的机器本地，不会在云端或团队间共享。
• 可审计性：你可以随时通过 /memory 命令查看、编辑或删除这些笔记。

五、 实用操作命令

• /init：自动生成起始的 CLAUDE.md。它会扫描代码库并提炼出构建命令和项目约定。
• /memory：查看当前会话加载的所有指令文件，并管理自动记忆的开关。
• /compact：在压缩对话历史时，Claude 会重新读取 CLAUDE.md 以确保指令不会丢失。

总结建议

如果你希望 Claude 成为一个高效的“项目专家”，最好的做法是：

1. 运行 /init 生成基础规则。
2. 在 CLAUDE.md 中明确写下你最在意的编码禁忌和必运行的测试命令。
3. 让自动记忆处理那些细碎的调试细节。

这个文档读下来感觉如何？你是否需要我针对某个特定的配置（比如如何设置特定路径的规则）提供更详细的操作步骤？

放置原则可以这样分：

结论

• 跨项目都成立的本机事实：放 ~/.config/opencode/AGENTS.md
• 只对某个项目成立的约定：放 项目根目录/AGENTS.md
• 敏感信息 / 经常变化的信息：不要放 AGENTS
  • 放环境变量、.env.local、本机笔记，或进入会话时临时告诉 AI

适合放到全局 AGENTS 的内容

放“稳定、长期、跨项目复用”的本机能力说明，比如：

• 你主要在 WSL2 下开发
• 常用 shell 是什么
• 本机安装了哪些关键工具
  • docker
  • pnpm
  • bun
  • node
  • psql
  • gh
  • playwright
• 本机有哪些长期可用能力
  • 可以跑 Docker
  • 可以访问本地域名
  • 有浏览器自动化能力
  • 某些命令必须在 WSL 内执行
• 路径和运行习惯
  • 项目通常在 ~/workspace/...
  • 不要假设 Windows 路径优先
  • 优先用 Linux 路径和 WSL 命令

适合放到项目 AGENTS 的内容

放“这个仓库特有”的东西，比如：

• 本项目的启动命令、测试命令
• 本项目的本地域名
  • app.test
  • api.test
  • admin.local
• 本项目依赖的本地服务
  • 数据库端口
  • Redis
  • MinIO
  • MailHog
• 这个项目在你机器上的特殊限制
  • 必须先启动 Docker compose
  • 必须走某个代理
  • 必须从 WSL 访问某个 hostname

如果这些信息只对这个项目有意义，就不要塞进全局 AGENTS。

不建议放 AGENTS 的内容

这些最好不要写进 AGENTS：

• API Key
• token
• 密码
• cookie
• 私有证书内容
• 经常变化的临时 IP / 临时端口
• 一大坨机器清单式信息，AI基本不会用

AGENTS 里应该放“AI做事时需要依赖的事实”，不是“机器资产盘点”。

一个实用写法

你可以在全局 AGENTS 里专门留一段：

## Local Environment

- I primarily work inside WSL2, not native Windows shells.
- Prefer Linux paths and commands unless I explicitly ask for Windows behavior.
- Common tools available on this machine: git, gh, docker, node, pnpm, bun, python3, playwright.
- If a task involves browsers, local web apps, or E2E checks, assume local browser automation may be available.
- Ask before relying on any secret, token, or private credential not already exposed in the workspace.

然后在具体项目的 AGENTS.md 里写：

## Local Dev Environment

- This project is usually run inside WSL2.
- Local web app: `https://app.test`
- Local API: `https://api.test`
- Admin panel: `https://admin.test`
- Start dependencies with `docker compose up -d`
- Run app with `pnpm dev`
- Use MailHog for local email testing.

最实用的判断标准

问自己一句：

• “这是 我的机器长期事实，还是 这个项目的本地运行事实？”

如果是：

• 长期事实 -> 全局 ~/.config/opencode/AGENTS.md
• 项目事实 -> 项目 AGENTS.md
• 敏感/易变事实 -> 不放 AGENTS

如果你要，我可以下一步直接帮你起草一版：

1. ~/.config/opencode/AGENTS.md 的“本机环境”模板
2. 项目 AGENTS.md 的“本地运行信息”模板

你可以直接改后拿去用。