标签#项目记忆#团队协作#版本控制#进阶实践第21篇我们学习了CLAUDE.md的基础用法——如何让 AI 记住命令、规范和架构。这一篇我们深入进阶场景当项目变大、团队变多、记忆变复杂时如何管理、演进、调试和共享你的项目记忆让它成为团队的共同资产而非混乱源头。1. 从“个人便利”到“团队资产”第21篇的场景聚焦在个人开发你写一份CLAUDE.mdAI 记住了你的偏好。但在团队中事情更复杂不同角色前端、后端、运维可能需要不同的 AI 行为新人加入时记忆文件应该是 onboarding 的一部分规范更新后如何确保 AI 不再沿用旧习惯多人同时修改记忆文件如何解决冲突进阶篇的目标将项目记忆变成团队共享的、可演进的、可调试的基础设置。2. 多层级记忆的优先级与合并策略Claude Code 支持多个记忆源它们按以下优先级合并后加载的覆盖先加载的优先级文件位置用途是否提交 Git1最低~/.claude/settings.json用户全局默认值否2~/.claude/CLAUDE.md用户全局项目记忆否3.claude/settings.json项目级配置团队共享✅4.claude/CLAUDE.md项目级记忆团队共享✅5CLAUDE.md根目录向后兼容✅但推荐用.claude/6最高.claude/CLAUDE.local.md个人覆盖不提交❌合并规则Markdown 文件CLAUDE.md系列会按顺序拼接后加载的追加到末尾。如果要覆盖某条规则建议在后加载的文件中明确写“不要使用 X改用 Y”。JSON 配置settings.json会深度合并后加载的同名键覆盖先加载的。实战示例团队统一使用npm test但你个人想用pnpm test。在.claude/CLAUDE.local.md中写## 个人覆盖 - 忽略项目 CLAUDE.md 中的“常用命令npm test”改用 pnpm testAI 会读到两条命令但因为后加载的CLAUDE.local.md中明确“改用”它会优先遵循。3. 记忆的版本控制与演进3.1 将.claude/目录纳入 Gitgitadd.claude/gitcommit-mchore: 添加 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.mdecho## 当前分支$(gitbranch --show-current).claude/CLAUDE.local.mdecho请根据分支名调整行为。.claude/CLAUDE.local.md7.2 根据文件存在性调整记忆在CLAUDE.md中写条件逻辑自然语言描述## 构建命令 - 如果 docker-compose.yml 存在优先使用 docker-compose up - 否则使用 npm run devAI 会先检查文件是否存在再决定推荐哪个命令。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记忆审查每月一次团队 reviewCLAUDE.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.mdA: 你可以写“代码风格详见docs/CODING_STYLE.md”。AI 会在需要时自动读取该文件类似file引用。但注意这会消耗额外 token。11. 下篇预告记忆让 AI 成为项目专家而提示词则是你与专家沟通的语言。下一篇我们将进入提示词核心技巧学习如何用上下文、预期行动和成功标准写出高效的指令。下一篇提示词Prompt核心技巧上下文、预期行动、成功标准缺一不可注第 24 篇将按原规划回到《新建React组件从自然语言描述到完整前端模块》思考题自测理解你的团队有一个 monorepo包含三个子项目。每个子项目的测试命令不同npm run test:web,npm run test:api,npm run test:mobile。你会如何在根目录和子目录的CLAUDE.md中组织这些命令一位新成员在本地运行claude后AI 给出的建议与团队预期不符。你让他运行什么命令来检查当前加载了哪些记忆文件假设你有一个“超级记忆”文件包含了从项目开始以来的所有历史决策长达 500 行。这会导致什么负面效果你会如何精简记忆是 AI 的灵魂但需要精心维护。下一篇我们将把灵魂注入提示词——用精准的语言指挥 AI。
第二十三篇:跨会话项目记忆:让AI自动记住你的测试命令、编译指令和项目模式(进阶篇)
发布时间:2026/6/2 10:11:57
标签#项目记忆#团队协作#版本控制#进阶实践第21篇我们学习了CLAUDE.md的基础用法——如何让 AI 记住命令、规范和架构。这一篇我们深入进阶场景当项目变大、团队变多、记忆变复杂时如何管理、演进、调试和共享你的项目记忆让它成为团队的共同资产而非混乱源头。1. 从“个人便利”到“团队资产”第21篇的场景聚焦在个人开发你写一份CLAUDE.mdAI 记住了你的偏好。但在团队中事情更复杂不同角色前端、后端、运维可能需要不同的 AI 行为新人加入时记忆文件应该是 onboarding 的一部分规范更新后如何确保 AI 不再沿用旧习惯多人同时修改记忆文件如何解决冲突进阶篇的目标将项目记忆变成团队共享的、可演进的、可调试的基础设置。2. 多层级记忆的优先级与合并策略Claude Code 支持多个记忆源它们按以下优先级合并后加载的覆盖先加载的优先级文件位置用途是否提交 Git1最低~/.claude/settings.json用户全局默认值否2~/.claude/CLAUDE.md用户全局项目记忆否3.claude/settings.json项目级配置团队共享✅4.claude/CLAUDE.md项目级记忆团队共享✅5CLAUDE.md根目录向后兼容✅但推荐用.claude/6最高.claude/CLAUDE.local.md个人覆盖不提交❌合并规则Markdown 文件CLAUDE.md系列会按顺序拼接后加载的追加到末尾。如果要覆盖某条规则建议在后加载的文件中明确写“不要使用 X改用 Y”。JSON 配置settings.json会深度合并后加载的同名键覆盖先加载的。实战示例团队统一使用npm test但你个人想用pnpm test。在.claude/CLAUDE.local.md中写## 个人覆盖 - 忽略项目 CLAUDE.md 中的“常用命令npm test”改用 pnpm testAI 会读到两条命令但因为后加载的CLAUDE.local.md中明确“改用”它会优先遵循。3. 记忆的版本控制与演进3.1 将.claude/目录纳入 Gitgitadd.claude/gitcommit-mchore: 添加 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.mdecho## 当前分支$(gitbranch --show-current).claude/CLAUDE.local.mdecho请根据分支名调整行为。.claude/CLAUDE.local.md7.2 根据文件存在性调整记忆在CLAUDE.md中写条件逻辑自然语言描述## 构建命令 - 如果 docker-compose.yml 存在优先使用 docker-compose up - 否则使用 npm run devAI 会先检查文件是否存在再决定推荐哪个命令。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记忆审查每月一次团队 reviewCLAUDE.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.mdA: 你可以写“代码风格详见docs/CODING_STYLE.md”。AI 会在需要时自动读取该文件类似file引用。但注意这会消耗额外 token。11. 下篇预告记忆让 AI 成为项目专家而提示词则是你与专家沟通的语言。下一篇我们将进入提示词核心技巧学习如何用上下文、预期行动和成功标准写出高效的指令。下一篇提示词Prompt核心技巧上下文、预期行动、成功标准缺一不可注第 24 篇将按原规划回到《新建React组件从自然语言描述到完整前端模块》思考题自测理解你的团队有一个 monorepo包含三个子项目。每个子项目的测试命令不同npm run test:web,npm run test:api,npm run test:mobile。你会如何在根目录和子目录的CLAUDE.md中组织这些命令一位新成员在本地运行claude后AI 给出的建议与团队预期不符。你让他运行什么命令来检查当前加载了哪些记忆文件假设你有一个“超级记忆”文件包含了从项目开始以来的所有历史决策长达 500 行。这会导致什么负面效果你会如何精简记忆是 AI 的灵魂但需要精心维护。下一篇我们将把灵魂注入提示词——用精准的语言指挥 AI。