本文为「AI 辅助编程实战指南」第8篇，完整系列持续更新中。

前言

每次开启新会话，AI 都像一个失忆的同事——你上周告诉过它的编码规范、项目架构、踩过的坑，全部忘得一干二净。你不得不每次重复解释”我们用 2 空格缩进””金额用 decimal 不用 float””API 统一返回 {code, message, data} 格式”。

这种重复不仅浪费时间，还会导致不一致——某次你忘了说”禁止裸 SQL”，AI 就给你生成了一个直接拼字符串的查询。

记忆系统就是为了解决这个问题。它让 AI 在每次新会话开始时，自动加载你之前积累的知识和规范，不用每次从零开始。更进一步，2026 年的 AI 编程工具已经支持自动记忆（Auto Memory）——AI 在工作过程中自己记笔记，下次遇到类似问题时自动查阅。

本篇学完你将掌握：

  • AI 编程工具的记忆机制全景和各工具差异
  • 自动记忆（Auto Memory）的工作原理和配置方法
  • 记忆分层策略：全局 → 项目 → 个人 → 本地
  • 跨会话记忆复用的完整实操方案
  • Skills 作为”可复用工作流记忆”的高级玩法
  • 记忆系统最常见的误用和避坑指南

💡 提示：本篇与第7篇：上下文管理互补。第7篇聚焦单次会话内的上下文优化，本篇聚焦跨会话的知识持久化和复用。两者共同构成 AI 编程的完整信息管理方案。

一、AI 的记忆机制：两个系统协同工作

在讲具体操作之前，先搞清楚 AI 编程工具的记忆架构。以 Claude Code 为例，它有两套互补的记忆系统——你写的和 AI 自己写的：

1.1 双系统总览

维度 CLAUDE.md 文件 自动记忆（Auto Memory）
谁写的 你（人工编写） AI（自动积累）
记什么 规则、规范、架构决策 学习到的模式、调试经验、偏好
存在哪 项目目录（随 Git 提交） ~/.claude/projects/<project>/memory/
加载时机 每次会话开始，全量加载 每次会话开始，加载前 200 行或 25KB
共享方式 团队共享（Git） 仅本机（不跨设备）
适合场景 编码规范、安全红线、构建命令 AI 发现的调试技巧、构建模式、偏好

两个系统都在每次会话开始时自动加载到上下文中，AI 将它们视为”背景知识”。区别在于：CLAUDE.md 是你主动告诉 AI 的规则，Auto Memory 是 AI 在工作中自己学到的经验。

1.2 各工具的持久化记忆对比

工具 持久化记忆机制 自动记忆 团队共享
Claude Code CLAUDE.md + .claude/rules/*.md + Auto Memory 支持（v2.1.59+） CLAUDE.md 随 Git 提交
Cursor .cursor/rules/*.md 或 .cursorrules 不支持（需手动维护） 规则文件随 Git 提交
Qoder AGENTS.md 支持（内置记忆系统） AGENTS.md 随 Git 提交
GitHub Copilot .github/copilot-instructions.md 不支持 随 Git 提交
OpenAI Codex AGENTS.md 不支持 随 Git 提交

💡 提示：截至 2026 年中，只有 Claude Code 和 Qoder 原生支持自动记忆。其他工具需要手动维护规则文件来实现类似效果——但手动维护的规则文件质量往往更高，因为你会仔细思考每条规则的必要性。

二、自动记忆（Auto Memory）：让 AI 自己记笔记

自动记忆是 Claude Code 在 2025 年底引入的功能——AI 在工作过程中自动保存有价值的信息，下次遇到类似场景时自动调用。这是记忆系统中最容易被忽视、但潜力最大的部分。

2.1 工作原理

1
2
3
会话中 AI 发现有用信息 → 判断"这值得记住吗" → 写入 MEMORY.md 或专题文件
                                                       ↓
下次新会话开始 → 加载 MEMORY.md 前 200 行 → AI 按需读取专题文件

AI 不会每次会话都保存东西。它只在发现对未来会话有用的信息时才记笔记，比如：

  • 你纠正了它的一个错误（”我们用 pnpm，不用 npm”）
  • 它发现了一个有效的调试模式
  • 它学到了项目的某个构建技巧
  • 你表达了某个代码风格偏好

2.2 存储结构

1
2
3
4
5
~/.claude/projects/<project>/memory/
├── MEMORY.md          # 记忆索引，每次会话加载前 200 行
├── debugging.md       # 调试经验（AI 自动创建）
├── api-conventions.md # API 设计决策
└── build-tips.md      # 构建技巧

MEMORY.md 是入口文件，类似于一张”目录”。AI 在会话中读写这个目录，把详细笔记拆到专题文件中，保持 MEMORY.md 本身简洁。

2.3 启用和配置

自动记忆默认开启。如果需要关闭或调整：

1
2
3
4
// .claude/settings.json — 关闭自动记忆
{
  "autoMemoryEnabled": false
}

也可以通过环境变量全局关闭：

1
2
# 在 .bashrc 或 .zshrc 中添加
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

如果想把记忆文件存到自定义位置：

1
2
3
4
// settings.json — 自定义记忆存储路径
{
  "autoMemoryDirectory": "~/my-project-memories"
}

2.4 审查和编辑记忆

自动记忆文件就是普通 Markdown——你可以随时查看、编辑、删除。在 Claude Code 中运行 /memory 命令即可浏览：

1
2
3
4
/memory
→ 列出当前加载的所有 CLAUDE.md 和规则文件
→ 显示自动记忆开关状态
→ 提供自动记忆文件夹的链接，点击可在编辑器中打开

💡 建议：每个月花 5 分钟审查一次自动记忆。AI 可能记住了一些过时的信息（比如你已经从 npm 迁移到了 pnpm，但记忆里还写着”npm install”）。过时的记忆比没有记忆更危险——它会让 AI 做出看似合理但实际错误的决策。

2.5 主动教 AI 记东西

除了让 AI 自动积累，你也可以主动告诉它”记住这个”：

1
2
3
4
5
# 方式1：直接让 AI 记住
请记住：这个项目的 API 测试需要本地 Redis 实例。

# 方式2：让 AI 写入 CLAUDE.md（团队共享）
把"所有金额字段用 decimal(10,2)"这条规则加到 CLAUDE.md。

两者的区别：方式1 保存到自动记忆（仅本机），方式2 写入 CLAUDE.md（团队共享）。选择哪种取决于这条信息是个人偏好还是团队规范。

三、记忆分层策略：四层记忆各司其职

记忆系统的核心挑战不是”记什么”，而是”记在哪里”。放错位置的记忆，要么被不该看到的人看到，要么在需要时加载不到。

3.1 四层记忆架构

1
2
3
4
5
6
7
8
9
10
11
12
13
┌─────────────────────────────────────────────────┐
│ 全局记忆（~/.claude/CLAUDE.md）                    │ ← 所有项目通用
│ 个人偏好：缩进风格、回复语言、注释语言              │
├─────────────────────────────────────────────────┤
│ 项目记忆（./CLAUDE.md 或 ./.claude/CLAUDE.md）     │ ← 团队共享
│ 项目架构、编码规范、安全红线、构建命令               │
├─────────────────────────────────────────────────┤
│ 本地记忆（./CLAUDE.local.md）                      │ ← 个人项目配置
│ 个人沙箱 URL、测试数据偏好                          │
├─────────────────────────────────────────────────┤
│ 路径规则（.claude/rules/*.md）                     │ ← 按需加载
│ 特定文件类型的规范，只在操作匹配文件时加载           │
└─────────────────────────────────────────────────┘

3.2 各层详细说明

第一层：全局记忆（~/.claude/CLAUDE.md）

适用于你在所有项目中都希望 AI 遵守的偏好：

1
2
3
4
5
6
7
8
# ~/.claude/CLAUDE.md

## 个人偏好
- 代码注释用中文
- 回复语言用中文
- 使用 2 空格缩进
- 函数命名用 camelCase，类名用 PascalCase
- 生成代码时始终包含类型注解

💡 提示：全局记忆建议控制在 50 行以内。它会在每次会话中加载，无论你做什么项目。内容太多会浪费上下文空间。

第二层：项目记忆（./CLAUDE.md）

项目级记忆是团队协作的核心——随 Git 提交，所有成员共享：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# CLAUDE.md — ShopFront 电商平台

Next.js 16 App Router、TypeScript strict、Prisma ORM、Stripe 支付。

## 常用命令
- `npm run dev` — 开发服务器（端口 3000）
- `npm test` — Jest 测试套件
- `npm run db:migrate` — Prisma 数据库迁移

## 编码规范
- 具名导出（named exports），禁止默认导出
- 禁止 `any` 类型，用 `unknown` + 类型收窄
- API handler 统一放在 `src/api/handlers/`

## 安全红线
- 禁止提交 .env 文件
- Stripe webhook 必须验证签名
- 修改 /lib 后必须运行 `npm test`

第三层：本地记忆（./CLAUDE.local.md）

个人项目配置，加入 .gitignore 不提交：

1
2
3
4
5
6
# CLAUDE.local.md

## 个人环境
- 我的沙箱 URL：https://dev-skye.shopfront.local
- 测试邮箱：skye-test@example.com
- 本地 PostgreSQL 端口：5433（非默认 5432）

第四层：路径规则（.claude/rules/*.md）

按需加载的细粒度规则，只在 AI 操作匹配文件时加载到上下文中：

1
2
3
4
5
6
7
8
9
10
# .claude/rules/api-handlers.md
---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则
- 所有接口必须包含输入验证
- 使用统一的错误响应格式 `{ code, message, errors }`
- 包含 OpenAPI 文档注释

3.3 跨工具兼容方案

如果你的团队同时使用多个 AI 工具（比如有人用 Claude Code，有人用 Cursor），可以用 @import 语法避免重复维护：

1
2
3
4
5
# CLAUDE.md
@AGENTS.md

## Claude Code 专属
使用 plan mode 处理 src/billing/ 下的修改。
1
2
3
4
5
# AGENTS.md（团队共享的通用规范）
## 编码规范
- 2 空格缩进
- 具名导出，禁止默认导出
- 所有 API 接口包含输入验证

这样 Claude Code 和 Codex 都能读取同一份规范，各自工具的特有配置分别维护。

3.4 大型项目的记忆组织

对于 Monorepo 或大型项目，使用渐进式展开策略：

1
2
3
4
5
6
7
8
9
10
11
12
13
project/
├── CLAUDE.md                    # 全局规范（< 200 行）
├── .claude/
│   └── rules/
│       ├── frontend.md          # 前端规则（paths: src/components/**）
│       ├── backend.md           # 后端规则（paths: src/api/**）
│       ├── database.md          # 数据库规则（paths: src/db/**）
│       └── security.md          # 安全规则（无条件加载）
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md            # 前端包特有规范（按需加载）
│   └── backend/
│       └── CLAUDE.md            # 后端包特有规范（按需加载）

子目录的 CLAUDE.md 不会在会话开始时加载——只有当 AI 读取该目录下的文件时才按需加载。这个机制既节省了上下文空间，又确保了相关规范在需要时可用。

⚠️ 注意：路径规则（.claude/rules/ 中带 paths 前缀的文件）只在 AI 读取匹配文件时触发加载，不是在每次工具调用时都检查。这意味着如果 AI 没有主动读取 src/api/ 下的文件，backend.md 规则就不会被加载。

四、跨会话记忆复用：让知识在会话间流动

记忆系统的真正威力在于复用——一次积累的知识，在后续无数个会话中发挥作用。以下是四种主要的复用方式。

4.1 PROGRESS.md：开发进度的持久化

这是第6篇详细介绍过的方案，这里补充记忆系统的视角：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# PROGRESS.md

## 已完成
- [x] Phase 1：BulkImportResult 数据模型（commit: a1b2c3d）
- [x] Phase 2：批量导入服务（commit: m0n1o2p）
  - 关键决策：使用 SERIALIZABLE 事务隔离级别
  - 已放弃方案：最初尝试了乐观锁，因并发冲突过多改用悲观锁

## 进行中
- [ ] Phase 3：文件上传 API 接口

## 经验教训
- openpyxl 处理 500 行以上文件时内存占用过高，改用 xlrd 流式读取
- 分类 ID 校验需要先加载分类缓存，否则 N+1 查询拖慢导入

从记忆系统角度看，PROGRESS.md 是一种手动维护的结构化记忆——它不是规则（不需要每次加载），而是进度和经验。新会话按需读取即可。

💡 建议：在 PROGRESS.md 中记录”已放弃的方案”和”经验教训”，而不只是”做了什么”。这些信息能防止 AI 在新会话中提出你已经试过并放弃的方案。

4.2 Git 历史作为隐式记忆

git log 和 git diff 是最容易被忽视的记忆源：

1
2
3
4
5
6
7
# 新会话开场 Prompt
请先查看以下信息了解项目状态：
1. `git log --oneline -20` — 最近 20 个提交
2. `git diff HEAD~5` — 最近 5 个提交的变更
3. PROGRESS.md — 当前进度

然后继续开发下一个功能。

Git 历史的优势在于它天然准确——不依赖人工维护，每次 commit 就是最真实的记录。

4.3 代码注释作为内联记忆

在代码中留下关键注释，AI 读取文件时自然获取上下文：

1
2
3
4
5
6
7
8
9
10
11
# 商品导入服务
# 
# 设计决策：
# - 使用事务回滚策略：任一行失败全部回滚
# - 不使用乐观锁（并发冲突过多，详见 commit m0n1o2p）
# - Excel 解析用 xlrd 流式读取，不用 openpyxl（内存问题）
#
# TODO: 下一步添加导入进度通知（WebSocket）

class BulkImportService:
    ...

这种”内联记忆”的好处是与代码共存——不需要额外文件，AI 读取代码时自动获取上下文。

4.4 Skills：可复用工作流的封装

Skills 不仅是扩展工具能力的插件（详见第4篇），它也是一种记忆形式——把重复性的工作流程封装为 Skill，本质上就是”记住怎么做某件事”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# .claude/skills/deploy-check.md

# 部署前检查 Skill

当用户说"检查部署"或"部署前检查"时触发。

## 检查清单
1. 运行完整测试套件 `npm test`
2. 运行 lint 检查 `npm run lint`
3. 检查 .env 文件是否在 .gitignore 中
4. 检查数据库迁移是否已执行 `npm run db:migrate:status`
5. 检查所有新增的环境变量是否已在部署文档中记录

## 输出格式
以表格形式输出检查结果，标记 ✅ 通过 / ❌ 未通过 / ⚠️ 需确认。

Skill 与规则文件的区别：

维度 规则文件 Skill
加载时机 每次会话自动加载 按需触发
上下文消耗 常驻消耗 只在触发时消耗
适合内容 始终需要遵守的规范 特定场景的工作流程
复杂度 简短规则 多步骤流程

💡 建议：如果你发现自己在每次新会话中都给 AI 同样的多步骤指令（比如”部署前检查””代码审查流程””新功能启动清单”），就该把它封装成 Skill。这是最优雅的”记忆”方式——不占常驻上下文空间，需要时自动加载。

五、记忆系统的维护：防止”记忆腐化”

记忆系统和代码一样，需要持续维护。不维护的记忆会变成”记忆负债”——过时的规则、矛盾的指令、冗余的信息，反而干扰 AI 的判断。

5.1 记忆腐化的三种形式

腐化类型 表现 后果
过时记忆 项目已从 npm 迁移到 pnpm，但 CLAUDE.md 还写着”运行 npm install” AI 使用错误的命令
矛盾记忆 CLAUDE.md 说”禁止默认导出”，但 .claude/rules/frontend.md 说”React 组件用默认导出” AI 随机选择一条遵守
冗余记忆 同一条规则出现在全局记忆、项目记忆和路径规则中 浪费上下文空间

5.2 定期维护清单

建议每两周执行一次记忆系统”大扫除”：

1
2
3
4
5
6
7
8
# 记忆维护 Prompt
请帮我审查项目的记忆系统：
1. 读取所有 CLAUDE.md 和 .claude/rules/ 文件
2. 检查是否有过时的信息（比如引用了已删除的文件或已弃用的库）
3. 检查是否有矛盾的规则
4. 检查是否有重复的规则
5. 统计总行数，确认是否超过 200 行建议上限
输出审查报告。

5.3 记忆增长的控制策略

策略 适用场景 具体做法
一进一出 CLAUDE.md 接近 200 行 每添加一条新规则，删除或合并一条旧规则
升级到 Skill 某条规则只在特定场景需要 从 CLAUDE.md 移到 .claude/skills/
下沉到路径规则 某条规则只适用于特定文件类型 移到 .claude/rules/ 并设置 paths
归档到自动记忆 某条信息是 AI 发现的而非团队规范 从 CLAUDE.md 移到 Auto Memory

5.4 记忆的有效性验证

用这个 Prompt 定期验证记忆是否还在发挥作用：

1
2
3
4
5
6
7
请根据 CLAUDE.md 和规则文件，回答以下问题：
1. 我们的项目用什么测试框架？
2. 金额字段应该用什么类型？
3. 修改 /lib 下的文件后需要做什么？
4. 有哪些目录是不应该修改的？

如果有任何问题你无法回答，说明对应的规则缺失或不够具体。

如果 AI 的回答与你的预期不符，说明记忆需要更新。

六、踩坑记录：自动记忆”记住”了错误的调试方案

现象：
在开发支付模块时遇到一个 Stripe webhook 签名验证失败的问题。经过排查，原因是测试环境的 webhook secret 和生产环境不同。AI 在调试过程中”学到”了一个绕过方案——在请求头中硬编码一个固定的签名值。AI 把这个”经验”存入了自动记忆。

三周后，在开发另一个功能时，AI 读取了自动记忆中的这条经验，在 webhook 处理逻辑中”贴心”地加入了硬编码签名的”优化”——这次是在生产环境代码中。代码审查时人工发现了这个问题，否则将导致严重的安全漏洞。

原因：

  1. AI 无法区分”临时调试方案”和”生产级方案”——在它看来，能让测试通过的方案就是”有效方案”
  2. 自动记忆没有区分信息的适用范围（调试 vs 生产）
  3. 三周间没有人审查自动记忆的内容

解决方案：

  1. 立即删除自动记忆中的这条记录（~/.claude/projects/<project>/memory/ 中删除）
  2. 在 CLAUDE.md 中添加明确规则：”禁止在任何代码中硬编码密钥、签名或凭证“
  3. 建立自动记忆审查机制——每两周运行 /memory 检查自动记忆内容

避坑建议：

  • 自动记忆是”AI 觉得有用”就保存的，但 AI 的判断不一定对——尤其是安全相关的临时方案
  • 安全红线类的规则必须放在 CLAUDE.md（人工控制），不能依赖自动记忆
  • 在调试时明确告诉 AI：”这是临时方案，不要记住它”
  • 定期审查自动记忆，删除过时的或危险的内容
  • 如果 AI 在某次会话中”学到”了一个技巧，审查一下这个技巧是否适用于所有场景——如果只适用于特定场景，应该移到路径规则或 Skill 中，而不是留在自动记忆里

总结与回顾

核心要点 关键结论
双系统架构 CLAUDE.md（你写规则）+ Auto Memory（AI 记经验），互补协作
自动记忆 AI 自主积累学习笔记，每月审查防止过时，安全红线不能依赖自动记忆
四层分层 全局 → 项目 → 本地 → 路径规则，各层加载时机不同，按需选用
跨会话复用 PROGRESS.md + Git 历史 + 代码注释 + Skills，四种复用方式各有适用场景
记忆维护 每两周审查一次，过时/矛盾/冗余的记忆比没有记忆更危险
Skill 封装 重复性多步骤工作流封装为 Skill，不占常驻上下文，按需触发
核心原则 记忆系统的价值不在于”记住一切”，而在于”记住正确的事”

延伸阅读

本文为「AI 辅助编程实战指南」第8篇，完整系列持续更新中。