项目记忆
什么是 CLAUDE.md
Section titled “什么是 CLAUDE.md”CLAUDE.md 是项目的记忆文件——一个放在项目根目录的 Markdown 文件, 里面记录了这个项目的编码规范、架构约定和已知陷阱。Peri 在启动时自动加载 CLAUDE.md, 将其内容融入系统提示词, 让 Peri 理解你的项目规则。
它就像给 Peri 的 README。不需要在每个 prompt 里重复项目背景和团队约定——写一次, Peri 每次对话都会看到。
Peri 在会话启动时 (session/new) 从候选列表（{cwd}/AGENTS.md、{cwd}/CLAUDE.md、{cwd}/.claude/AGENTS.md、~/.claude/AGENTS.md）中取第一个存在的文件——不递归、不合并，只加载一个主文件。找到的内容冻结 (frozen) 在系统提示词中, 享受 Anthropic prompt cache 优化——98% 的情况下不会产生额外 token 费用。
在中间件链中, AgentsMdMiddleware 负责 CLAUDE.md 的加载和注入。它是中间件链中的第一个中间件 (排在 HITL 审批之前), 确保模型在任何操作之前就已经理解了项目上下文。冻结后的内容在整个会话生命周期内不可变, 所有子代理 (SubAgent) 也复用同一份 frozen CLAUDE.md, 不会重复读盘。
| 类别 | 内容 | 示例 |
|---|---|---|
| 编码规范 | 项目使用的风格和约束 | “禁止 println!, 统一用 tracing” |
| 模块索引 | 各模块的职责和入口文件 | “peri-agent: ReAct 循环引擎” |
| 架构速览 | 核心数据流和组件关系 | “ACP 事件 → acp_bridge → VIEW_MODELS” |
| 陷阱速查 | 已知的坑和 TRAP 标记 | “CJK 截断必须用 chars().take()” |
| 测试规范 | 测试存放位置、命名约定 | “单元测试小于 30 行放同文件” |
| 环境变量 | 需要的 API key 和配置项 | “ANTHROPIC_API_KEY, LANGFUSE_*” |
| 任务入口 | 新增功能时该改哪些文件 | “新增 Core 工具需同步 6 处” |
Peri 自身的 CLAUDE.md 就是最好的示例——它包含了完整的 ReAct 循环架构、20 个中间件的固定顺序、TUI 渲染规则和 30 多条从 bug 现场提炼的 TRAP 标记。
不应该写什么
Section titled “不应该写什么”CLAUDE.md 占据上下文窗口, 每条内容都应该物有所值。以下几种内容不应该放进去:
- 临时的 todolist: 做完就过时, 徒占空间
- 大段示例代码: 用文档引用或
@import替代 - 个人偏好而非项目约定: 用
~/.claude/AGENTS.md（全局）或./CLAUDE.local.md（个人项目级）管理 - 多步骤操作流程: 超出单项目的通用流程写成 Skills。Peri 没有 per-directory 按需加载机制——路径相关规则直接写在候选文件的规则段落中
Peri 从以下候选路径中按顺序取第一个存在的文件（不是 ~/.claude/CLAUDE.md，也没有子目录按需加载机制）:
| 位置 | 作用域 | 优先级 |
|---|---|---|
项目根/AGENTS.md | 当前项目 (第一候选) | 最高 |
项目根/CLAUDE.md | 当前项目 | ↑ |
项目根/.claude/AGENTS.md | 当前项目 (备选位置) | ↑ |
~/.claude/AGENTS.md | 所有项目 | 低 (仅在项目内无文件时生效) |
找到主文件后, 若存在 项目根/CLAUDE.local.md, 其内容会追加到主文件之后（个人项目级, 不入库）。
此外, CLAUDE.md 系列文件中可以用 <!-- @import path --> 语法导入其他文件——导入的文件会展开后一起进入上下文。路径相对于当前文件所在目录, 递归深度上限 3（AGENTS.md 不解析 @import）。
与自动记忆的区别
Section titled “与自动记忆的区别”Peri (以及 Claude Code) 有两套互补的记忆系统:
| CLAUDE.md | 自动记忆 | |
|---|---|---|
| 谁写 | 你手动编写 | Peri 自动记录 |
| 内容 | 项目规则和约定 | 从对话中学到的模式 |
| 用途 | 编码规范、架构约定 | 构建命令、调试经验 |
| 变更频率 | 偶尔 (架构变更时) | 持续 (每次修 bug 都可能新增 TRAP) |
自动记忆不会覆盖 CLAUDE.md——Peri 会在归档 issue 时将新发现的约束提炼为 TRAP 标记, 建议你手动写入 CLAUDE.md。这就是 Peri 项目几十条 TRAP 的来源: 没有一条是人类手写的, 全是在 bug 现场由 agent 自己提炼的。
保持更新, 定期瘦身。 架构变更后同步更新对应的段落, 过时的规则及时删除。Peri 加载整个文件, 但读到的”使用旧 API”会让它写出错误代码。建议控制在 200 行以内——超过时考虑用 <!-- @import --> 把细节拆到独立规则文件。
精炼而非详尽。 Peri 有完整的项目文件可以搜索。CLAUDE.md 不需要列出所有函数的文档——它只需给出导航索引, 告诉 Peri “在哪里能找到什么”。
用中文写。 Peri 的提示词是中文, CLAUDE.md 也用中文可以保持上下文一致性, 同时减少 token 开销 (中文比英文更紧凑)。
分段明确, 指令具体。 用 Markdown 标题分隔不同类别, Peri 可以更好地定位信息。写”用 2 空格缩进”而不是”好好格式化代码”, 写”提交前跑 cargo test --workspace”而不是”测试你的改动”。
TRAP 是硬约束。 当某个 bug 只会在特定条件下触发时, 把修复后的教训写成 TRAP 标记。格式如 [TRAP] 问题描述 → 原因 → 正确做法。Peri 将其视为硬约束, 在后续所有迭代中强制遵守。