claude.md解密

一、为什么用Markdown存Agent记忆

MarkDown是程序员间通用的文档格式，最早OpenAI的程序员将其定为LLM的输出规范 Markdown是人+Agent都能读写的显式长期记忆，无数据库/向量引擎依赖，核心优势：

1. 透明可审计：打开即看记忆内容，无黑盒
2. 持久化：存磁盘，不随进程/机器变化
3. 版本可控：Git管理，可回滚、分支、评审
4. 零迁移：标准格式，换模型/框架仅迁文件
5. 低成本：本地无额外运维与费用

---

二、Claude Code双轨记忆机制

采用CLAUDE.md（人工）+ Auto Memory（自动） 双轨：

1. CLAUDE.md（人工编写）

• 定位：AI的项目入职文档
• 官方限制：≤200行，超行降低指令遵守率

该写内容

• 技术栈与版本信息
• 常用构建/测试/启动命令（放代码块）
• 架构决策+背后原因
• 团队约定、项目特有坑点

不该写内容

• 代码风格规则（交格式化工具）
• 语言/框架默认行为
• 大段参考文档（给链接即可）

高效写法技巧

• 规则具体可验证，避免模糊表述
• 禁令配替代方案，不单纯禁止
• 慎用IMPORTANT:标记，避免滥用失效
• 用通用标题（Commands/Conventions等）

2. Auto Memory（自动积累）

• 存储路径：~/.claude/projects/<project>/memory/
• 入口文件：MEMORY.md
• 限制：仅加载前200行/25KB，超量不读
• 问题：20-30会话后笔记质量可能下降
• 禁用：环境变量CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

---

三、CLAUDE.md四层加载规则

层级	路径	作用范围	优先级
组织级	/etc/claude-code/CLAUDE.md	所有用户	最低
用户级	~/.claude/CLAUDE.md	个人所有项目	中
项目级	./CLAUDE.md/.claude/CLAUDE.md	团队共享	高
本地级	CLAUDE.local.md	个人当前项目	最高

• 加载规则：从工作目录向上查找，近目录优先级更高
• 本地级：需加入.gitignore，不提交仓库

---

四、分层管理与引用规则

1. @引用
   • 格式：@path/to/file，递归≤5层
   • 特点：启动全量加载，不减少上下文消耗
2. path-scoped rules
   • 路径：.claude/rules/
   • 特点：按需加载，仅匹配路径时生效，适合细粒度规则

---

五、CLAUDE.md维护策略

1. 添加慢：仅当Claude犯错且规则能防错时添加
2. 删除快：无效/无影响规则立即移除
3. 错误驱动：纠错后同步更新记忆
4. 预警信号
   • 反复道歉：规则表述问题
   • 反复违反：文件过长，需精简
5. 版本管理：Git提交+PR评审，可回滚

---

六、Markdown记忆 vs 传统记忆方案对比

维度	Markdown记忆	向量库/RAG	数据库型框架
检索	全量注入，无检索	语义检索，高精度	混合策略
上下文	随文件大小增加	按需加载，高效	按需加载，高效
调试	极佳，直接改文件	中等，需工具	复杂
成本	极低	高，需运维	极高
版本	原生Git	需额外同步	需额外同步
场景	规范、偏好、踩坑	海量文本检索	复杂多源记忆

---

七、CLAUDE.md不适合存储内容

• 大段日志、完整对话
• 敏感密钥、Token、账号
• 高频运行时数据
• 可实时查询的动态信息