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

📌 标签：#项目记忆 #团队协作 #版本控制 #进阶实践

第21篇我们学习了 CLAUDE.md 的基础用法——如何让 AI 记住命令、规范和架构。这一篇我们深入进阶场景：当项目变大、团队变多、记忆变复杂时，如何管理、演进、调试和共享你的项目记忆，让它成为团队的共同资产而非混乱源头。

1. 从“个人便利”到“团队资产”

第21篇的场景聚焦在个人开发：你写一份 CLAUDE.md，AI 记住了你的偏好。但在团队中，事情更复杂：

• 不同角色（前端、后端、运维）可能需要不同的 AI 行为
• 新人加入时，记忆文件应该是 onboarding 的一部分
• 规范更新后，如何确保 AI 不再沿用旧习惯？
• 多人同时修改记忆文件，如何解决冲突？

进阶篇的目标：将项目记忆变成 团队共享的、可演进的、可调试的 基础设置。

2. 多层级记忆的优先级与合并策略

Claude Code 支持多个记忆源，它们按以下优先级合并（后加载的覆盖先加载的）：

合并规则：

• Markdown 文件（CLAUDE.md 系列）会按顺序拼接，后加载的追加到末尾。如果要覆盖某条规则，建议在后加载的文件中明确写“不要使用 X，改用 Y”。
• JSON 配置（settings.json）会深度合并，后加载的同名键覆盖先加载的。

实战示例：团队统一使用 npm test，但你个人想用 pnpm test。

在 .claude/CLAUDE.local.md 中写：

## 个人覆盖
– 忽略项目 CLAUDE.md 中的“常用命令：npm test”，改用 `pnpm test`

AI 会读到两条命令，但因为后加载的 CLAUDE.local.md 中明确“改用”，它会优先遵循。

3. 记忆的版本控制与演进

3.1 将 .claude/ 目录纳入 Git

git add .claude/
git commit -m "chore: 添加 Claude Code 项目记忆"

团队每个成员 clone 后，运行 claude 即可获得统一的行为。

3.2 记忆文件的 PR 审查

像代码一样，CLAUDE.md 的变更也应该通过 PR 审查。审查要点：

• 新增的命令是否在所有开发环境都能运行？
• 规范是否与项目实际 lint 配置一致？
• 是否包含了敏感信息（如硬编码的路径、凭证）？
• 是否与现有记忆冲突？

示例 PR 描述：

更新 CLAUDE.md：
– 添加数据库迁移命令（npx prisma migrate dev）
– 明确禁止修改 src/generated/ 目录
– 补充测试环境变量说明

测试：运行 claude，输入“如何运行迁移？”，AI 应返回正确的命令。

3.3 记忆的变更日志

建议在 .claude/CHANGELOG.md 中记录重大变更，帮助团队成员理解为何修改：

# Claude Code 记忆变更日志

## 2026-05-20
– 将测试命令从 `npm test` 改为 `npm run test:ci`（因为 CI 环境需要额外参数）
– 废弃了 `formatDate` 函数的旧用法，请使用 `date-fns` 替代

## 2026-05-10
– 初始化，添加了技术栈和常用命令

4. 角色分离：不同目录使用不同的记忆

如果你有一个 monorepo，前端和后端的构建命令、规范完全不同。你可以在子目录中放置独立的 .claude/CLAUDE.md，并在该目录下运行 claude 时自动加载。

目录结构：

monorepo/
├── .claude/CLAUDE.md # 根级记忆（通用）
├── frontend/
│ ├── .claude/CLAUDE.md # 前端专用（覆盖根级）
│ └── …
└── backend/
├── .claude/CLAUDE.md # 后端专用
└── …

当你在 frontend/ 目录下运行 claude 时，AI 会同时加载根目录和 frontend/.claude/ 的记忆，以后者为准（优先级更高）。

技巧：在根级 CLAUDE.md 中写通用规范（如 Git 提交格式），在子目录中写技术栈相关命令。

5. 调试记忆问题

当 AI 没有按照你的预期行为时，可能是记忆未正确加载或冲突。

5.1 查看 AI 实际加载的系统提示词

在 Claude Code 中输入：

/status

部分版本会显示当前加载的系统提示词摘要（包括 CLAUDE.md 的内容）。如果没有，你可以直接问 AI：

请输出你从 CLAUDE.md 中读取到的所有项目规范，逐一列出。

AI 会返回它记住的内容，你对照检查是否有遗漏或错误。

5.2 检查记忆文件的语法错误

CLAUDE.md 是标准 Markdown，但某些格式可能误导 AI：

• 使用代码块包裹命令示例时，语言标注要准确（```bash 而非 ```shell）
• 列表缩进必须一致（空格 vs Tab）
• 避免使用可能被解析为指令的特殊字符（如 /compact 出现在正文中，AI 可能误以为是命令）

建议：用 markdownlint 检查格式。

5.3 解决记忆冲突

如果你发现 AI 同时遵循了两条矛盾的规则（例如“用 npm”和“用 yarn”），检查是否在不同的记忆文件中定义了。解决方案：

• 在优先级更高的文件中明确覆盖：“忽略其他地方的 yarn 指令，统一用 npm。”
• 或者删除低优先级文件中的冲突项。

6. 记忆与 Skills/Commands 的协同

CLAUDE.md 适合存放“陈述性知识”（是什么、怎么用），而 Skills 和 Commands 适合存放“过程性知识”（多步骤流程）。两者可以协同：

在 CLAUDE.md 中引用 Skill：

## 常用操作
– 生成 PR 描述：使用 `generate-pr-description` skill
– 运行完整测试套件：调用 `/test-all` 命令

AI 读到这些后，当你问“如何生成 PR 描述”，它会建议你运行对应的 Skill。

从 Skill 中读取记忆：在 Skill 的 Markdown 文件中，你可以写“参考 CLAUDE.md 中的数据库连接字符串”，AI 会在执行时动态读取。

7. 高级技巧：动态记忆与条件加载

7.1 根据环境变量加载不同记忆

你可以通过 CLAUDE.local.md 结合环境变量实现条件加载。例如，在 CLAUDE.local.md 中：

## 本地开发环境
当前分支：{{ env.GIT_BRANCH }}
如果是 feature/ 分支，优先使用测试数据库。

虽然 Claude Code 不支持原生模板变量，但你可以用脚本生成 CLAUDE.local.md：

echo "## 当前分支：$(git branch –show-current)" > .claude/CLAUDE.local.md
echo "请根据分支名调整行为。" >> .claude/CLAUDE.local.md

7.2 根据文件存在性调整记忆

在 CLAUDE.md 中写条件逻辑（自然语言描述）：

## 构建命令
– 如果 `docker-compose.yml` 存在，优先使用 `docker-compose up`
– 否则使用 `npm run dev`

AI 会先检查文件是否存在，再决定推荐哪个命令。

8. 案例：一个团队项目记忆的演进历程

阶段 1（项目启动）：CLAUDE.md 只包含技术栈和启动命令。

阶段 2（引入代码规范）：团队决定使用 ESLint + Prettier。在 CLAUDE.md 中添加：

## 代码格式化
– 运行 `npm run format` 自动修复格式问题
– 禁止 AI 生成 `var`，必须用 `const/let`

阶段 3（微服务拆分）：项目拆分为 user-service 和 order-service。创建子目录记忆：

user-service/.claude/CLAUDE.md # 用户服务专用命令
order-service/.claude/CLAUDE.md # 订单服务专用命令

阶段 4（团队扩大）：新成员反馈 AI 给出的测试命令不对。检查发现是因为个人环境变量不同。团队决定在 CLAUDE.md 中写通用命令，个人覆盖用 CLAUDE.local.md。

阶段 5（记忆审查）：每月一次，团队 review CLAUDE.md，删除过时内容（如已废弃的 Webpack 配置），添加新规范（如要求 AI 生成的代码必须有 JSDoc）。

结果：一年后，项目有 20+ 成员，CLAUDE.md 成为 onboarding 的核心文档。新人第一天就能用 Claude Code 完成有效贡献。

9. 记忆的备份与迁移

• 备份：git clone 就是备份。确保 .claude/ 目录被包含。
• 迁移到新项目：复制 .claude/ 目录，然后根据新项目的技术栈修改 CLAUDE.md。
• 跨团队共享：你可以将 .claude/CLAUDE.md 提取为模板，发布到内部 Wiki 或 GitHub 模板仓库。

10. 常见问题进阶

Q: 我更新了 CLAUDE.md，但 AI 仍然按旧方式回答。为什么？

A: 当前会话不会自动重新加载。运行 /init（实验性）或 /clear 后重新进入。

Q: 团队成员覆盖了太多个人偏好，导致 AI 行为不一致怎么办？

A: 在团队规范中约定：.claude/CLAUDE.md 只能包含所有人同意的规则，个人偏好一律放入 .claude/CLAUDE.local.md（不提交）。CI 环境只加载团队版。

Q: AI 忽略了 CLAUDE.md 中的某条“禁止”指令。

A: 用更强烈的语气：“绝对禁止修改 src/legacy/ 下的任何文件。” 或者将该指令写在更高的优先级文件（如 CLAUDE.local.md）中。

Q: 如何在 CLAUDE.md 中引用外部文件（如 docs/CODING_STYLE.md）？

A: 你可以写“代码风格详见 @docs/CODING_STYLE.md”。AI 会在需要时自动读取该文件（类似 @file 引用）。但注意这会消耗额外 token。

11. 下篇预告

记忆让 AI 成为项目专家，而提示词则是你与专家沟通的语言。下一篇我们将进入 提示词核心技巧，学习如何用上下文、预期行动和成功标准写出高效的指令。

👉 下一篇： 提示词（Prompt）核心技巧：上下文、预期行动、成功标准，缺一不可

（注：第 24 篇将按原规划回到《新建React组件：从自然语言描述到完整前端模块》）

思考题（自测理解）

记忆是 AI 的灵魂，但需要精心维护。下一篇，我们将把灵魂注入提示词——用精准的语言指挥 AI。