第二十一篇：跨会话项目记忆：让AI自动记住你的测试命令、编译指令和项目模式

📌 标签：#项目记忆 #CLAUDE.md #持久化 #效率提升

每次打开 Claude Code，你都要重新告诉 AI “我的测试命令是 npm run test:ci”“构建需要先设置 NODE_ENV”“别碰 legacy/ 目录下的文件”——这不仅烦人，而且容易遗漏。跨会话项目记忆让这些信息永久固化，AI 每次进入项目都会自动加载，就像一位从第一天就加入团队的老成员。

1. 什么是跨会话项目记忆？

“跨会话项目记忆”不是 Claude Code 的某个单独功能，而是一套持久化上下文机制的总称。其核心思想是：

• 每个项目目录可以有自己的记忆文件（CLAUDE.md、.claude/ 下的配置）
• 这些文件会被自动加载到每个新会话的系统提示词中
• 你告诉 AI 一次“我的测试命令是 make test”，它就永远记住了（针对这个项目）
• 记忆可以提交到 Git，团队成员共享同一套 AI 行为规范

与普通对话历史的区别：

2. 核心记忆载体：CLAUDE.md

CLAUDE.md 是 Claude Code 最基础、最重要的记忆文件。当你在项目根目录（或 .claude/ 子目录）放置这个文件时，Claude Code 会在每次会话启动时读取它，并将其内容作为系统提示词的一部分。

2.1 文件位置优先级

2.2 典型内容结构

# 项目：My E-Commerce API

## 技术栈
– Node.js 20 + Express + TypeScript
– PostgreSQL + Prisma ORM
– Redis 缓存
– Jest 测试框架

## 常用命令
– 开发服务器：`npm run dev`（监听 3000，热重载）
– 生产构建：`npm run build`
– 运行所有测试：`npm test`
– 运行单个测试：`npm test — –grep "pattern"`
– 数据库迁移：`npx prisma migrate dev`
– 代码格式化：`npm run format`

## 目录结构说明
– `src/controllers/`：HTTP 请求处理，调用 service 层
– `src/services/`：业务逻辑，调用 repository
– `src/repositories/`：数据库访问（Prisma）
– `src/types/`：TypeScript 类型定义
– `tests/unit/`：单元测试
– `tests/integration/`：集成测试

## 代码规范
– 使用 `camelCase` 命名变量和函数
– 使用 `PascalCase` 命名类和组件
– 禁止 `any` 类型，未知类型用 `unknown` 并做类型守卫
– 所有 API 响应格式：`{ success: boolean, data?: T, error?: string }`

## 重要约束
– 不要修改 `src/generated/` 目录（Prisma 自动生成）
– 环境变量配置在 `.env.local`，不要提交到 Git
– 数据库迁移文件一旦生成，不要编辑，只能新增

## 外部依赖
– 支付网关 API 文档：https://docs.stripe.com/api
– 内部 Wiki：https://wiki.company.com/projects/ecommerce

有了这份文件，AI 就知道：

• 运行测试时用 npm test（而不是猜测 jest 或 mocha）
• 修改代码时遵循命名规范
• 避开自动生成的目录
• 遇到数据库操作时使用 Prisma 模式

2.3 使用 .claude/CLAUDE.local.md 做个人覆盖

你可以在项目中添加 .claude/CLAUDE.local.md（记得加入 .gitignore），存放只属于你自己的偏好：

## 个人偏好
– 我的测试环境需要额外设置环境变量：`export TEST_DB_URL=postgresql://localhost/testdb`
– 请优先使用 `pnpm` 而不是 `npm`
– 生成代码时，注释用英文，变量名用英文

AI 会同时加载 CLAUDE.md 和 CLAUDE.local.md，后者覆盖前者的冲突项。

3. 扩展记忆：.claude/settings.json

除了 CLAUDE.md，项目级配置 .claude/settings.json 也可以存储一些“记忆”，特别是关于 AI 行为本身的设置。

{
"permissions": {
"defaultMode": "default",
"allow": [
"Read",
"Grep"
],
"askForApproval": [
"Write",
"Edit",
"Bash"
]
},
"model": {
"default": "claude-3.5-sonnet",
"fallback": "claude-3-haiku"
},
"hooks": {
"preWrite": "npm run format — –check",
"postTest": "echo 'Tests completed'"
},
"maxIterations": 30,
"compactThreshold": 100000
}

这些配置虽然不完全是“自然语言记忆”，但同样会影响 AI 的行为，且跨会话持久。

4. 记忆的自动加载机制

当你运行 claude 进入项目目录时，Claude Code 按以下顺序加载记忆：

所有这些内容会被拼接到系统提示词中，对 AI 来说就像与生俱来的知识。你不需要在每次对话中重复。

5. 维护记忆的最佳实践

5.1 从零开始：让 AI 帮你生成初版 CLAUDE.md

你不会写？让 Claude Code 自己写。

在空项目或现有项目中，输入：

请根据当前项目的 package.json、目录结构和源代码，生成一份 CLAUDE.md 草稿，包含技术栈、常用命令、代码规范和建议。

AI 会扫描项目，输出一份高质量的初始文件，你只需要稍作调整。

5.2 记忆随代码演进

项目变化时（比如换了测试框架、增加了新的目录规范），及时更新 CLAUDE.md。可以定期让 AI 帮你审查：

检查一下 CLAUDE.md 是否还符合当前项目的实际结构？如果有过时的地方，请建议更新。

5.3 避免记忆过载

CLAUDE.md 不是越长越好。AI 每次会话都要加载它，过大的文件会：

• 消耗输入 token（每次会话的固定成本）
• 稀释重点（AI 可能忽略埋在长篇文档中的关键信息）

建议长度：150 行以内，只记录“AI 无法从代码中自动推断”的信息。例如：

• 不要写每个函数的详细说明（AI 可以读代码）
• 要写为什么某个设计决策如此（历史背景、权衡）

5.4 使用标记分区

用明显的标题和分隔符组织内容，方便 AI（和人类）快速定位：

# 项目：…

## [COMMANDS] 常用命令
…

## [CONVENTIONS] 代码规范
…

## [CONSTRAINTS] 硬性约束
…

## [CONTEXT] 背景知识
…

6. 记忆的版本控制与团队共享

将 .claude/CLAUDE.md 和 .claude/settings.json 提交到 Git，团队所有成员 clone 后就能获得相同的 AI 行为。

团队使用流程：

冲突处理：如果团队对某条规范有分歧，用 CLAUDE.md（团队共识）+ CLAUDE.local.md（个人覆盖）解决。

7. 高级记忆技术：Skill 与 Command 存储

除了 CLAUDE.md，你还可以在 .claude/commands/ 和 .claude/skills/ 中定义可复用的能力（第 18 篇），它们也是项目记忆的一部分。

例如，创建一个 .claude/commands/build-prod.md：

—
description: 构建生产版本并打包
—

执行以下步骤：
1. 运行 `npm ci –production`（确保使用 lockfile）
2. 运行 `NODE_ENV=production npm run build`
3. 将 dist/ 目录打包为 `build-$(date +%Y%m%d).tar.gz`
4. 输出打包文件名

团队成员输入 /build-prod 就能执行标准化构建流程，无需记住复杂的命令组合。

8. 案例：一个真实项目的记忆演进

初始状态：项目只有简单的 CLAUDE.md，写着“用 Jest 测试”。

第 1 个月：团队引入了 Prisma，需要频繁运行迁移。在 CLAUDE.md 中添加：

– 数据库迁移：`npx prisma migrate dev –name <描述>`
– 重置测试数据库：`npx prisma migrate reset –force`

第 3 个月：项目增加了微服务边界，要求不要跨服务直接调用。添加：

## 架构约束
– 订单服务（src/order/）不能直接导入用户服务（src/user/）的 repository
– 必须通过 src/gateway/ 中的 API 客户端调用

第 6 个月：新人加入，通过 CLAUDE.md 快速上手，AI 给出的所有建议都符合团队约定。团队将 CLAUDE.md 的更新纳入 PR 审查清单。

9. 常见问题

Q1: CLAUDE.md 和 .claude/CLAUDE.md 哪个优先？

如果两个文件都存在，Claude Code 会合并它们（先加载 .claude/ 下的，再加载根目录的）。推荐只用 .claude/CLAUDE.md，避免混乱。

Q2: 修改 CLAUDE.md 后需要重启会话吗？

不需要。在当前会话中，如果你修改了 CLAUDE.md，AI 不会自动重新加载。你可以输入 /init 命令（实验性）重新加载，或者直接 /clear 清空会话后重新进入（新会话会加载新版本）。

Q3: 如何防止敏感信息被写入 CLAUDE.md 并提交？

• 不要把 API Key、数据库密码等写在 CLAUDE.md 中。这些应该放在 .env 或 .claude/settings.local.json（加入 .gitignore）。
• 使用 ${VAR} 语法引用环境变量。

Q4: AI 有时会忽略 CLAUDE.md 中的指令，为什么？

• 检查 CLAUDE.md 是否有语法错误（如 Markdown 格式混乱）。
• 可能用户当前的指令优先级更高（AI 会优先遵循最新的用户输入）。
• 可以加强语气：“严格按照 CLAUDE.md 中的规范执行。”

Q5: 可以为子目录设置特定的记忆吗？

目前不支持。CLAUDE.md 作用于整个项目（从运行 claude 的目录递归向上查找）。但你可以通过在子目录中运行 claude（作为独立“项目”）来实现隔离。

10. 下篇预告

项目记忆让 AI 知道了你的“习惯”，但要让 Claude Code 与外部服务（如 Jira、Slack、Figma）深度协作，你还需要 MCP Server——我们已经介绍过原理，下一篇将展示一个完整的实战：如何配置 MCP Server 并打通你的日常工具链。

👉 下一篇： 使用MCP Server打造“外部连接”：从数据库到Jira、Slack全打通

（注：第 22 篇规划为 MCP 实战，与第 20 篇主题相近但侧重点不同。第 20 篇是概念与配置，第 22 篇将聚焦端到端工作流案例。）

思考题（自测理解）

记忆是 AI 的基石。给它一份好的 CLAUDE.md，它就能成为项目最资深的成员。下一章，我们将把这份记忆与外部世界连接起来。