AI编程工具的用户级记忆：跨项目复用的全局工作习惯配置

每次开新项目第一件事就是把同样的背景重复讲一遍我习惯用哪个包管理器、代码风格是什么、测试怎么写、输出用中文还是英文、遇到问题先给方案还是先给解释。一开始我还能忍直到某天连续开了四个仓库把同样一段偏好说明复制粘贴了四遍我才意识到问题不在工具不够聪明而在记忆没被放在对的地方。今天要聊的就是这类 AI 编程工具Claude Code、openCode、以及类似形态的命令行编码助手里经常被忽略但极其好用的功能用户级别的记忆文件。简单说就是放在用户主目录下、不随项目走、全局生效的那份指令或上下文文件。它解决的痛点是让 AI 在每一个新项目中都默认记得你是谁、你怎么工作、你有哪些红线。这个内容适合正在重度使用 AI 编程工具、每天要切换多个仓库的开发者也适合刚入门、想从一开始就建立正确工作姿势的新手。1. 先搞清楚记忆的层级项目级、用户级与会话级1.1 三种记忆从哪里来、到哪里去这类 AI 编程工具的记忆机制我观察下来基本分三层。第一层是会话级记忆只活在你当前这个终端会话里。你跟 AI 说接下来我们用 pnpm 安装依赖它在这个会话里会照做但一旦关掉终端、重新启动这件事就忘了。会话级记忆是最脆弱的好处是灵活坏处是每次都要重新交代。第二层是项目级记忆活在当前项目目录里。表现形式通常是 CLAUDE.md、AGENTS.md 或者其他约定的文件名。你把这个项目使用 pnpm workspace、测试框架是 vitest、不要动 src/legacy 目录这类信息写进去只要在这个项目下启动工具AI 就能读到。项目级记忆解决了每次会话都要重复说的问题但解决不了跨项目复用的问题。第三层就是今天的主角用户级记忆。它放在用户主目录home 目录下对所有项目全局生效。这里写的不是某个项目的特殊情况而是你这个人的工作习惯、通用偏好、语言要求、工程底线。比如所有代码注释用中文、新依赖默认使用 pnpm、git 提交信息遵循 Conventional Commits——这些和项目无关只和你这个人有关。这三层不是互斥的它们会在 AI 读取上下文时按一定规则合并。最合理的关系是用户级打底项目级覆盖会话级微调。底层决定你这个人怎么工作项目层决定这个项目有什么特殊约束会话层解决临时的临时需求。1.2 为什么用户级记忆最容易被忽略很多人的记忆文件只写了项目级也就是每个仓库里放一个 CLAUDE.md。用了一段时间后会发现一个尴尬的场景新克隆一个项目AI 完全不认识你的工作习惯又回到了你说一句它做一句的状态。这不是工具的问题是记忆放错了层级。项目级记忆天然绑定仓库而你的偏好是跨仓库存在的。如果只靠项目级记忆你就要在每一个新仓库里复制同一份偏好内容一旦更新习惯还得同步改所有仓库。时间一长不同仓库的记忆内容必然出现漂移。另一个原因是很多人根本不知道用户级记忆文件放在哪里甚至不知道这类工具支持这个能力。结果就是要么忍受每次重复说明要么把全局偏好硬塞进某个项目里反而污染了项目级记忆的纯度。项目文件里塞满了我习惯用中文写注释这种和该项目的业务逻辑毫无关系的条目会把真正重要的项目约束稀释掉AI 容易抓错重点。2. 记忆文件放哪路径规划与工具差异2.1 Claude Code 的用户级记忆路径Claude Code 这类工具有一个从单文件演化到目录的清晰过程。早期版本的全局记忆是一个直接放在主目录下的点文件比如~/.claude.md。随着内容越来越复杂单文件模式逐渐不够用社区实践开始转向目录化在主目录下创建.claude/目录里面再放CLAUDE.md作为入口。也就是~/.claude/CLAUDE.md。这个路径我不是随便推荐的。之所以放在用户主目录而不是某个项目目录是因为主目录横跨所有项目。只要工具按约定路径加载你在任何目录下启动它它都能读到同一份记忆。目录化的好处是你可以把记录拆成多个文件主文件放通用偏好子目录放针对性规则再通过引用或读取规则把内容合并起来。实操上我第一次用的时候就是简单创建了一个文件后来内容多了才发现单文件太挤迁移到目录结构后清爽多了。如果你刚接触建议一步到位用目录结构不要走单文件的老路。2.2 openCode 及同类工具的自定义路径openCode 这类开源工具通常更强调可配置性。它的全局配置目录一般在~/.config/opencode/或类似的 XDG 风格目录下记忆文件也可能是 AGENTS.md 而不是 CLAUDE.md。关键是不要死记某个路径而是先看工具文档中关于全局指令或用户规则的部分确认它加载哪个路径。我见过有人写了一大堆记忆内容结果放错了文件工具根本没读白白浪费了几个小时。所以正确的做法是先找到路径再验证加载逻辑最后才写内容。验证方式很简单在记忆文件里写一句如果看到这句话请回复记忆文件已加载然后随便开个新项目测试能回就是通了。有一点值得注意不同工具的全局记忆名称和优先级规则并不完全一样。不要假设 A 工具的行为方式在 B 工具上完全适用。好在核心思想是一致的放主目录、全局生效、内容稳定。你只需要把内容文件复制到对应工具的路径下面再做少量格式调整就能完成一次迁移。2.3 加载与优先级合并时谁覆盖谁理解了路径还得理解合并规则。这类工具在读取记忆时通常遵循用户级为基础、项目级为覆盖、会话级为微调的优先级逻辑。也就是说当项目级记忆和用户级记忆出现冲突时项目级的说法更优先因为它更贴近当前上下文。我建议在用户级记忆里不要写绝对和一定这类词因为真实工作时项目约束经常比个人偏好更硬。比如你的全局偏好是所有函数都要写 JSDoc但某个项目明确规定不写任何注释代码即文档这时候如果全局记忆写得太强硬AI 就会在项目里反复纠结到底听谁的。另一个容易被忽略的事实记忆文件不是越大越好。加载逻辑意味着全部记忆内容都会进入 AI 的上下文窗口占用 token 配额。如果把所有历史经验都塞进去每次会话的固定开销会明显增大反而降低了实际可用上下文。所以在设计内容时少而准比多而全更聪明。3. 内容设计记忆文件里到底该写什么3.1 稳定偏好与临时需求先分类再写入写记忆文件之前先做一道分类题你要写的内容是一年后还成立的还是下周就变了的稳定偏好值得写入。例如你的母语不是英文要求所有 AI 输出用中文你坚持用 pnpm你习惯提交信息用 Conventional Commits你不希望 AI 在没有明确要求时自动重构代码。这些内容在三个月后依然成立放进用户级记忆是合理的因为它们确实跨项目、跨时间稳定。临时需求不值得写入。例如当前正在调试某个 bug希望 AI 记住暂时不要动 A 文件下周要交付某个功能希望 AI 优先完成某部分。这类内容是典型的会话级或项目级内容。写入全局记忆的后果是下次开一个完全不相干的新项目AI 还在念念不忘那个早就过时的调试限制。我个人的判断标准是一句话如果我换了公司、换了电脑、开始写一个完全不同领域的项目这句话我还希望 AI 知道吗如果答案是是就写进用户级记忆如果是否就放到项目级或直接不写。3.2 写作规范让机器读得懂的条目设计记忆文件的读者是模型的上下文解析器不是人。这意味着句式越直接越明确效果越好。我倾向于把每一条规则写成当 X 时执行 Y的结构减少歧义。比如不要写代码注释尽量写得清楚一些AI 会理解为可以自由发挥要写所有新增函数必须包含一行注释说明函数用途。前者是模糊形容词后者是可执行的条件与动作。另一个技巧是把否定式指令改成肯定式指令。与其说不要在代码里留无意义的注释不如说只保留与逻辑相关的注释删除复制粘贴痕迹明显的历史残留注释。我还会建议在记忆文件开头放一个简短的我的基本信息区块告诉 AI 你的语言偏好、常用工具、在意的事项。这个区块是整个文件里被读取最稳定、最频繁的部分值得花时间设计和维护。另外记忆文件内部可以用清晰的 Markdown 结构组织但不要用过于复杂的嵌套。AI 工具解析 Markdown 的能力不算弱但扁平的小节更容易被稳定命中。我的做法是用二级、三级标题分区每个区下列 3 到 10 条明确规则绝对不堆长段落。3.3 什么内容千万别写进全局记忆这里面有些坑踩过才长教训。第一不要写外部服务的账号、密钥、token 等敏感信息。记忆文件通常以纯文本形式存在任何能读到文件的人都能拿到内容。我见过有人在记忆文件里写数据库连接串这是非常危险的习惯。正确的做法是环境变量或专用密钥管理服务AI 工具如果需要读应该指向环境变量名而不是把明文写进记忆。第二不要写带有强烈情绪的命令式口吻。比如你怎么这么笨每次都把接口名搞错之类模型不太适合处理大量负面情绪暗示而且这些内容毫无信息价值只会浪费上下文空间。第三不要写大段示例代码。记忆文件不是代码片段库AI 有自身的代码生成能力你只需要写约束规则不需要把完整实现抄进去。如果要给示例应该给最小可复用模板而不是几十行的完整实现。第四不要写和特定项目强绑定的信息。某个仓库的目录结构、特殊依赖版本号这些属于项目级记忆的职责写进全局记忆后反而会让 AI 在无关项目中产生错误的路径预期。4. 实操一套可直接复制的用户记忆配置4.1 目录初始化与基础内容我提供一个经过多次验证的初始化方案你能直接照着操作。第一步创建目录结构。以 Claude Code 为例在终端执行mkdir -p ~/.claude touch ~/.claude/CLAUDE.md第二步写基础内容。以下是一个覆盖面比较全的模板你可以按自己的情况删减### 我的基本信息 - 语言偏好所有回复与代码注释默认使用中文。 - 包管理器优先使用 pnpm没有 pnpm 的项目再考虑 npm 或 yarn。 - 终端环境macOS zsh常用命令行工具包括 git、node、docker。 - 代码风格保持简洁避免过度设计优先使用函数式写法不强制。 ### 工作习惯 - 当我说检查一下代码默认动作是先做静态审查指出潜在问题再给修改建议。 - 当我说修复 bug默认动作是先定位根因解释清楚原因再提交代码。 - 在提交代码前主动运行相关测试如果测试时间过长提示我确认。 - git 提交信息遵循 Conventional Commits 规范格式为 type(scope): subject。 ### 红线清单 - 不要在没有明确要求时重构已有代码。 - 不要删除看起来没用的代码先询问再处理。 - 不要跳过测试直接声称功能可用。 - 不要伪造测试结果或编译通过信息。这段模板的真实感在于每一条都是可执行的规则不是空话。我实际使用时会根据具体场景不断增删但骨架保持稳定。第三步验证。打开任意一个不在项目级记忆覆盖范围内的仓库问 AI 一句我的全局记忆里代码注释默认用什么语言如果回答正确说明加载成功。4.2 记忆文件的渐进式维护写完基础版本后记忆文件会进入一个持续演进的过程。我的习惯是每次使用工具时如果发现它反复犯错且错误可归因于缺少规则我就记一条如果发现某条规则反而导致不良行为就立刻删掉。维护节奏上我建议以两周为一个周期专门抽时间翻一遍记忆文件。删除过时的条目合并重复的条目调整顺序让最重要的条目排在前面。很多时候你会发现自己当时写的一些规则已经内化了AI 不会被触发删掉也不会再犯错。这些条目就是过度规定该清就清。有一个细节不要害怕改动记忆文件。文件不是一次定稿的合同而是持续迭代的工作文档。我见过有人因为写了一份文件就再也不动AI 的行为也一直停在那个版本后来项目环境变了里面的规则已经跟不上实际反而变成了负担。4.3 多工具协同一份记忆多处引用如果你和我一样手上不止一个 AI 编程工具一定会遇到这份记忆能不能同时给 Claude Code 和 openCode 用的问题。我的经验是内容可以共用文件不要硬共用。不同工具加载逻辑和格式约定不同直接把同一个文件链接给多个工具可能导致某个工具解析异常。更好的做法是把一份主记忆放在一个自定义位置比如~/memory/global-rules.md然后在各工具的用户级记忆文件中通过引用指令指向这个主文件。实际效果是你只维护一个主文件各工具的入口文件只做转发。这样即使某工具格式升级你只需要调整它的入口文件主内容一笔不动。不过要确认你使用的工具确实支持引用外部文件如果不支持就只能做一次内容同步把主文件内容复制到各工具路径下。5. 踩坑记录记忆文件常见的四个问题5.1 内容过多导致上下文膨胀我把记忆文件从二十行扩到八十行后明显感觉到一个问题AI 的上下文窗口被占掉了一块尤其是长篇对话时留给业务信息的空间变少甚至出现了它记得我的规则却记不住我刚才让它改的代码的情况。这个问题最直接的解决办法是删。每一条记忆都要问自己这条价值大吗能稳定触发吗没有它会怎样我删掉一些锦上添花的条目后上下文压力明显缓解。如果内容实在删不下来可以尝试把低优先级的内容拆到另一个文件在需要时手动提及而不是全部预加载。5.2 全局偏好与项目要求打架有一次某项目明确要求代码注释用英文但我的全局记忆里写了注释用中文。AI 在生成代码时陷入两难一会儿中文一会儿英文逻辑分裂。更麻烦的是它可能会在中期切换策略导致最终提交的代码注释风格不一致。解决方案是在用户级记忆里加上一条兜底规则当项目级记忆与全局规则冲突时以项目级记忆为准如果仍有不确定先问我再行动。这样冲突从根源上被消解AI 不需要自己猜优先级。5.3 文件路径写错导致不生效这个问题发生的频率比我预想的高。有些工具的全局记忆路径不在主目录根下而在~/Library/Application Support/macOS或者%APPDATA%Windows下改错了文件自然不生效。还有工具改版后路径发生变化旧文档里的路径不再适用。排查方式很简单打开工具的输出日志看启动时加载了哪个路径或者直接在当前目录新建一个空项目在记忆文件里写一句测试指令看 AI 是否响应。这两种方式都比猜测可靠得多。5.4 依赖特定工具的语法导致迁移失效Markdown 是全球规则的好格式但不同工具对规则语法的延伸理解不同。有的工具支持metadata区块、有的支持import指令、有的对普通###标题和黑体做了特殊语义处理。写的时候图方便使用了 A 工具的专有语法迁移到 B 工具时那个语法完全不被识别规则失效。我现在的主力策略是只写最朴素的 Markdown 结构——标题、列表、短段落顶多使用粗体。任何带特殊前缀或自定义语法的格式除非确认所有目标工具都支持否则坚决不用。这样能保证记忆文件在多个工具之间的可移植性。我个人在实际使用中的体会是用户级记忆文件最大的价值不是让 AI 更聪明而是让 AI 更像我。它避免了我每一次对话都要从头解释的重复劳动也让我在切换项目、切换工具时有一种稳定感。刚开始写的时候不用追求完整从三五条最核心的偏好起步用两周时间跟着实际工作慢慢补比一开始就写一大堆要有效得多。如果你用的是这类 AI 编程工具建议现在就打开主目录建一个属于你自己的全局记忆文件——花半小时配置之后每天都会省回这半小时。