Claude Code 跨项目记忆怎么配置？三层方案（2026）

截至 2026 年 8 月 10 日，官方文档明确说明：Claude Code 每次会话都会建立新的上下文，而自动记忆入口文件只会加载前 200 行或 25KB，以先达到者为准。官方记忆机制说明 因此，Claude Code 跨项目记忆的获胜方案是三层配置：用 CLAUDE.md 保存稳定事实，用 Skills 保存按需加载的流程，用外部 Agent Memory 保存跨会话的动态偏好与任务状态；不要把所有历史记录直接合并成一份全局提示词。

这篇文章适合同时维护多个仓库、希望减少重复输入项目规则的个人开发者；也适合需要统一团队流程、却不想把个人偏好写进公共仓库的负责人。若团队准备让编码 Agent 长期运行，还需要额外规划持久化、项目隔离、权限和备份。

最后更新于 2026 年 8 月 10 日，目录、作用域、自动记忆和 Skills 行为已依据官方文档重新核对，并以多个虚构仓库的规则加载、技能触发和重启恢复流程作为验收思路。

第 1 阶段：先把要记住的信息分成三类

跨项目记忆最容易出错的地方，不是文件路径，而是把不同生命周期的信息混在一起。部署前先按照“稳定事实、重复流程、动态状态”分层，后续才知道内容应该放在哪里。

• 稳定事实：项目架构、包管理器、测试命令、目录约定、代码风格、禁止修改的模块。
• 重复流程：部署、发布、代码评审、回滚、生成变更说明等需要按步骤执行的任务。
• 动态状态：某次故障的排查结论、个人偏好、尚未完成的任务、上次会话留下的临时上下文。

以下内容不应跨项目共享：

• API 密钥、访问令牌、.env 文件和证书；
• 客户名称、内部工单、未公开产品计划；
• 某个仓库的数据库结构、内部域名和部署拓扑；
• 只适用于单一项目的临时决策。

CLAUDE.md 中写“禁止读取密钥”并不能形成绝对安全边界。官方配置文档建议使用权限拒绝规则限制 .env、凭据文件和敏感目录的读取；真正需要强制执行的限制，应放在权限、钩子或外部服务端，而不是只放在自然语言说明里。配置与敏感文件限制

第 2 阶段：先建立单项目 CLAUDE.md

单项目配置应从最小可用版本开始，而不是一上来就创建一份几十页的操作手册。官方建议将每次都需要知道的项目事实写进 CLAUDE.md，复杂参考资料和多步骤流程则迁移到 Skills 或路径规则中。扩展机制与文件职责

虚构项目 AtlasNote 可以先使用这样的结构：

# AtlasNote 开发约束

## 项目结构
- API 位于 services/api/
- 前端位于 apps/web/
- 数据库迁移位于 infra/migrations/

## 常用命令
- 安装依赖：pnpm install
- 单元测试：pnpm test
- 类型检查：pnpm typecheck

## 修改规则
- 修改接口后必须同步更新测试
- 不直接编辑生成目录
- 涉及认证逻辑时先说明影响范围

这类内容具备三个条件：长期有效、每次开发都有用、可以由新成员快速理解。相反，完整发布手册、某次事故的详细日志和长篇 API 资料不适合全部塞入这个文件。

官方文档说明，Claude Code 会从当前目录向上查找 CLAUDE.md，并把发现的内容按目录层级合并；更接近当前工作目录的规则通常后加载。CLAUDE.local.md 可用于不提交到仓库的个人偏好，但必须加入忽略规则，避免将本地内容带进团队版本库。CLAUDE.md 加载规则

完成文件后，不要直接相信它已经生效，按下面步骤验证：

1. 在项目根目录启动 Claude Code。
2. 执行 /memory，确认目标文件出现在已加载列表。
3. 开启一个新会话，不依赖上一段对话背景。
4. 询问项目测试命令和目录结构，检查回答是否来自当前仓库。
5. 故意提出一条与规则冲突的修改要求，确认 Agent 是否先指出约束。
6. 运行 /context，观察过长的说明是否挤占代码和命令输出空间。

需要特别区分：文件被重新加载，只代表规则再次进入当前上下文；这不等于模型拥有永久记忆，也不代表它会自动理解所有历史任务。

第 3 阶段：把重复流程迁移到 Claude Code Skills

当 CLAUDE.md 中出现大量“先执行 A，再检查 B，最后生成 C”的内容，就说明它已经从项目事实变成了流程。此时应把流程迁移到 SKILL.md，让 Claude Code 在需要时加载，而不是每次启动都携带完整操作手册。

例如，AtlasNote 的评审技能可以放在：

.claude/skills/review-change/SKILL.md

内容示例：

---
description: Review a change for tests, API compatibility, security risks, and migration impact. Use when the user asks for a code review or before merging a large change.
---

## Review sequence

1. Inspect the diff and identify changed modules.
2. Check whether tests cover the changed behavior.
3. Flag API compatibility and migration risks.
4. Separate confirmed issues from suggestions.
5. End with a short merge recommendation.

描述字段不是装饰。它帮助 Claude 判断什么时候自动加载技能；如果描述过短，相关任务可能无法触发；如果描述过宽，技能又可能频繁误触发。官方文档确认，Skills 可以通过 /skill-name 手动调用，也可以由模型根据描述自动判断是否使用；技能正文通常在真正使用时才加载。Skills 创建与调用说明

多个项目共享 Skills 时，可以按作用域处理：

选项	适合保存什么	共享范围	主要风险
项目级 .claude/skills/	仓库专属部署、测试和评审流程	当前项目团队	被复制到其他仓库后语义失真
用户级 ~/.claude/skills/	个人通用工作流和格式偏好	当前用户的多个项目	可能把个人习惯带入团队流程
插件级 Skills	可复用的工具包和组织级能力	由插件安装范围决定	来源、权限和升级需要单独审核

官方文档还说明，Skills 目录新增、修改或删除后通常可以被当前会话检测；但如果首次创建的是此前不存在的顶层目录，可能需要重启 Claude Code 才能开始监视。Skills 热加载说明 这也是“文件已经改了，为什么技能仍然没触发”时首先要检查的边界。

第 4 阶段：再接入跨会话的动态记忆

官方自动记忆解决的是“同一台机器、同一类项目如何积累工作经验”，并不等于团队级、云端或跨环境的长期记忆。官方机制会按 Git 仓库生成项目目录，自动记忆位于本机的项目记忆路径；不同机器或云环境之间不会自动共享。自动记忆存储边界

因此，只有在确实存在以下需求时，才值得接入外部 Agent Memory：

• 个人偏好需要在多个仓库之间复用；
• 任务需要跨会话恢复，而开发环境会频繁重建；
• 团队需要查询历史决策，但又不想把全部对话提交到代码仓库；
• 远程编码环境需要在重启后恢复有限的任务状态。

外部记忆组件应至少保存这些字段：

user_id：用户或团队成员标识
project_id：仓库或业务项目标识
memory_type：偏好、决策、故障结论或待办状态
content：经过脱敏的摘要
source：来自哪次任务、哪份文档或哪次评审
created_at：写入时间
expires_at：删除或复核时间

跨项目召回不能只依赖关键词。至少应先匹配 user_id 和 project_id，再根据任务类型和时间筛选；如果项目标识不明确，宁可不召回，也不要把 AtlasNote 的认证决策带到虚构项目 NorthwindLab。

如果通过 MCP 连接外部记忆服务，应明确选择作用域：个人工具可使用用户级配置，团队共用的服务才考虑项目级配置，并为访问令牌设置环境变量而不是直接写进 .mcp.json。官方文档确认，MCP 具有本地、项目和用户等作用域，项目级配置可进入版本控制，因此必须先完成服务端权限和数据脱敏。MCP 作用域与配置方式

第 5 阶段：用固定任务做迁移和重启验收

三层方案上线后，验收重点不是“文件是否存在”，而是重新打开会话后，Claude Code 是否只加载了正确范围的内容。建议准备一组不包含真实客户信息的固定测试任务，每次升级 Claude Code 或记忆组件都重复执行。

检查清单：

• ✅ 新建项目会话后，/memory 能看到正确的 CLAUDE.md；
• ✅ 项目 A 的规则不会出现在项目 B 的项目级记忆中；
• ✅ 用户级 Skills 能在多个项目显示，但项目级 Skills 不会反向污染其他仓库；
• ✅ 修改 SKILL.md 后，当前会话能够检测到变化，或按文档要求完成重启；
• ✅ 关闭并重启远程环境后，外部记忆只恢复允许范围内的摘要；
• ✅ 删除一条记忆后，后续查询不会继续返回缓存副本；
• ✅ 记忆记录可以追溯来源，也可以按用户、项目或时间批量删除；
• ✅ .env、密钥、客户资料和完整源码不会进入记忆库；
• ✅ 规则冲突时，能通过 /memory、/skills、/status 或 /doctor 定位来源。

官方调试文档建议使用 /memory 检查规则文件，使用 /skills 检查技能，使用 /status 查看设置来源，并用 /doctor 诊断配置问题。配置调试命令 迁移前应备份 CLAUDE.md、.claude/、用户级 Skills 和外部记忆索引；不要只备份代码仓库，因为一部分个人配置并不在仓库内。

常见疑问：自动记忆、共享配置与信息隔离

FAQ 重点不在于“有没有一个永久记忆开关”，而在于确认每层内容的所有权和生命周期。稳定事实由维护者审核，流程由 Skills 版本控制，动态状态则必须具备隔离和删除机制。

如果只是希望多个仓库使用相同的提交格式或评审步骤，优先使用用户级或组织级 Skills；如果只是希望不同项目都知道某个个人偏好，可以放进用户级 CLAUDE.md，但不要把项目内部路径、客户信息和部署细节一起带过去。

如果团队需要的是长期任务恢复，而不是简单加载配置文件，就不能把 CLAUDE.md 当成数据库。它适合表达规则，不适合记录不断变化的状态；外部 Agent Memory 才适合承担查询、更新、审计和删除，但这属于部署架构，需要自行设计权限与数据边界，并非 Claude Code 自动提供的跨环境承诺。

三层配置模板：按内容生命周期分配

可以直接采用下面的分配方式：

• CLAUDE.md 层：项目结构、构建命令、测试命令、代码约束、必须遵循的目录规则。
• Skills 层：部署、发布、评审、回滚、故障排查、生成变更说明等多步骤流程。
• Agent Memory 层：用户偏好、历史决策摘要、未完成任务、远程环境重启后的恢复状态。

不适合租赁或远程环境的场景也应提前排除：如果项目长期持续高负载、必须依赖本地物理接口，或者合规要求所有数据始终留在自有设备上，自购 Mac 或自建环境可能更合适。若只是临时测试 Claude Code、需要多人共用隔离环境，传统本地方案往往有 3 个现实缺点：设备配置难以统一、重装后用户级记忆容易丢失、多人共享时权限和项目边界需要手工维护。

这类情况下，Zutcloud 的远程 Mac 环境更适合先验证“配置能否加载、Skills 是否触发、重启后记忆是否恢复”这类部署问题，再决定是否长期购置设备。正式使用前可先查看 帮助中心 了解远程环境的连接与使用边界；如果需要持续运行编码 Agent，也可以进一步评估 Mac mini 租用方案，重点核对隔离方式、访问权限和数据清理流程，而不是只比较硬件名称。