每次开新会话AI 编程助手就当你是陌生人。上午刚跟 Claude Code 讲清楚项目用的是什么框架、测试命令是什么、哪些目录不能乱动下午新开一个会话它又问一遍“这是什么项目”。这个场景我用过多少次就烦了多少次后来终于想明白一个事不是这些工具笨是我从来没给它们留过一张“项目交接便签”。今天要聊的就是给 Claude Code、Codex、VS Code 里挂的 AI 扩展以及 Qoder 这类 AI IDE 配一份“长久记忆”。原理不复杂操作也快核心就一件事在固定的位置放一个规则文件每次 AI 启动时会自动读取把项目背景、技术栈、编码偏好、常用命令一次性装进它的上下文。我实测下来只要知道文件放哪、写什么、怎么写两分钟真的能搞定。下面把这个过程从原理到实操完整拆开讲顺便把我踩过的坑也一并交代清楚。1. 先搞明白AI 的“记忆”到底存在哪1.1 会话记忆和文件记忆是两回事很多人在对话里反复叮嘱 AI“记住我们项目用的是 Vue3”当时它是记住了可会话一关这个记忆就没了。原因很简单AI 的上下文窗口是临时的它只对当前这轮对话负责不会把内容自动写盘。你指望聊天记录能跨会话生效等于指望一个临时工不靠交接文档就能续上上一个员工的工作——偶尔行大部分时候不靠谱。真正能做到“长久记忆”的是文件系统。AI 助手在启动时会主动去固定的位置读一些规则文件把这些文件里的内容当作“项目交接班记录”来看待。Claude Code 读的是 CLAUDE.mdCodex 读的是 AGENTS.mdQoder 有内置的规则配置VS Code 里取决于你挂的是哪个 AI 扩展。换句话说你要做的不是让 AI 记住你而是给 AI 一份它每次上班都能看到的交接文档。这个机制理解起来像什么像给新员工入职第一天准备一份“岗位说明书”。你不可能指望新员工靠入职那天的聊天记住所有流程但一份写在纸上的说明他随时能翻不会忘。CLAUDE.md 就是 AI 的那份岗位说明书。1.2 四种工具各自的“记忆入口”不同工具读的文件不同但思路是一模一样的。我先把我验证过的入口列出来后面每个工具的配置细节再单独展开。工具记忆文件/入口作用范围Claude Code项目根目录的 CLAUDE.md项目级Claude Code~/.claude/CLAUDE.md全局级所有项目生效Codex项目根目录的 AGENTS.md项目级Codex~/.codex/AGENTS.md全局级VS Code Claude Code 扩展读取同一份 CLAUDE.md跟随项目Qoder设置中的 Rules/规则配置全局或项目粒度看清楚这个表你就明白了很多人在 VS Code 里装了一堆 AI 插件却不知道怎么配记忆其实就是没找到对应插件读的是哪个文件。下面我从最常用的 Claude Code 讲起把每一个工具的配置过程都过一遍。2. 两分钟起步给 Claude Code 建一个 CLAUDE.md2.1 最小可用的记忆文件长什么样先说最简单的情况。你已经装好了 Claude Code在终端里敲claude能正常启动然后你想让它记住项目的基本信息。操作如下进入项目根目录新建一个文件名字必须叫 CLAUDE.md注意大小写。打开文件写几行最核心的信息# 项目名称 ## 项目概述 这是一个电商后台管理系统面向内部运营人员当前处于功能迭代阶段。 ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js Express - 数据库PostgreSQL 15 ## 常用命令 - 启动开发环境npm run dev - 运行测试npm test - 构建生产包npm run build ## 代码规范 - 组件文件用 PascalCase 命名 - API 请求统一走 src/api/client.ts 封装 - 数据库变更必须写迁移脚本不允许直接改表保存退出重新启动 Claude Code随便问一句“这个项目用什么技术栈”它就能准确回答你。整个过程真的不到两分钟。这个文件的值不在于长而在于准。我见过不少人一开始就写上千字的记忆文件结果 AI 被一堆信息淹没关键内容反而抓不住。CLAUDE.md 的定位是“速记”不是“文档库”。写它的时候问自己一个问题如果明天一个新人来接手这个项目最需要知道的那三五件事是什么把这些写进去就够了。2.2 应该写在记忆文件里的几类信息根据我这段时间整理多个项目的经验一份高质量的 CLAUDE.md 通常覆盖这么几块第一项目概述。一句话能说清楚的事情不要写背景论文。比如“这个项目是给仓库管理人员用的进销存系统后面要对接财务模块”这就够了。AI 有了这个定位回答问题的角度就不会跑偏。第二技术栈和目录结构。技术栈决定了 AI 写出来的代码风格目录结构决定了它改文件时去哪找。这两样是 AI 的“地图”没有地图它就只能瞎猜。第三常用命令。启动、测试、构建、代码检查这些命令写清楚AI 就能在你让它“跑一下测试”的时候直接给出正确指令不用你再去纠正。第四编码约定和约束。这是最容易被忽略但最有价值的部分。比如“错误处理必须走统一的异常类”“样式用 CSS Modules 不要用 Tailwind”“第三方 API Key 禁止硬编码放环境变量”。AI 遵守了这些约定产出的代码质量会明显不一样。第五当前待办或近期计划。这个不是必需但有奇效。比如你最近在迁移老接口把这个写进去AI 写新代码的时候会自动避开老接口优先用新的。2.3 写记忆文件的几个原则写一份好的记忆文件比我上面说的“能说清项目是什么”要多花点心思。我有几个原则一直按这个来每条尽量短。能一句话说清就不写两句话AI 的上下文窗口是有限的被废话占满就亏了。用具体命令和文件名不要用模糊描述。写“构建产物在 dist 目录”比写“构建后在输出目录里”强一百倍。事实和偏好分开。事实是“数据库在 PostgreSQL”偏好是“所有表名用蛇形命名”。AI 对两者都会采纳但你自己回顾维护的时候分开放更好改。不要写 AI 自己知道的事。比如“Python 是一种编程语言”这种废话写了只是浪费一个 token。还有个小技巧Claude Code 自带一个/init命令你在项目目录里敲这个它会根据现有代码自动生成一份 CLAUDE.md 草稿。草稿不一定准确但可以作为起点你再手动修正补充。自动生成加人工校验比我纯手写要省不少时间。3. Codex、VS Code、Qoder 的记忆配置对照3.1 Codex 的 AGENTS.md 怎么配Codex 用的记忆文件名叫 AGENTS.md作用和 CLAUDE.md 几乎一样都是放在项目根目录作为项目级指令。你把我刚才那份模板里的内容拷贝到一个新文件改名为 AGENTS.md放在项目根目录Codex 启动时就会自动读取。全局记忆方面Codex 会读取用户主目录下~/.codex/AGENTS.md这个文件。注意Codex 对不同层级文件的优先级处理是离当前工作目录越近的规则文件优先级越高。所以如果全局文件里写了“代码注释用中文”项目文件里写了“代码注释用英文”那在项目里工作时以项目文件为准。这个优先级设计挺合理全局管习惯项目管特例。我实际用下来的感受是Codex 对 AGENTS.md 的加载历史比 Claude Code 短但它是认真对待这个文件的尤其是在执行任务前会先读一遍。所以你把项目背景和常用命令写得清楚它的整体表现会有肉眼可见的提升。3.2 VS Code 里装 Claude Code 扩展后怎么共用记忆很多人是在 VS Code 里用的 Claude Code而不是在终端里直接敲命令。这个场景下扩展本质上还是在读取项目目录下的 CLAUDE.md所以你只需要照常维护项目根目录的 CLAUDE.md 文件VS Code 里的 Claude Code 一样能读到不需要额外配置。至于 VS Code 里的其他 AI 扩展情况稍微有些不同。Continue 这类插件通常有自己的 rules 配置入口在扩展设置里可以找到GitHub Copilot 有专门的 instruction 文件。这些和 CLAUDE.md 不能互通但思路是一样的在设置里指定一个文件路径AI 启动时加载。我给 VS Code 配置记忆的通用方法是先看这个扩展有没有“Rules”“Instructions”这类设置项有就直接指定到你维护的 CLAUDE.md 文件上这样你只需要维护一份多个扩展共享。3.3 Qoder 的规则配置与记忆恢复Qoder 作为 AI IDE不需要像命令行工具那样创建特定命名的文件它是在设置里提供规则配置的地方。我在 Qoder 里用的方法是打开设置找到全局规则或项目规则配置入口把记忆内容粘贴进去。全局规则适合放个人偏好比如“回答尽量简洁”“代码优先用 TypeScript”这类项目规则就放具体项目相关的比如技术栈、目录结构、注意事项。和 CLI 工具相比Qoder 这类 IDE 的规则配置有一个优点它有图形界面不容易出现“文件名打错导致文件没被读取”的问题。但也有一个坑不同版本的入口名称可能不一样有的叫 Rules有的叫 AI 设置有的叫提示词配置。如果你找不到直接在设置里搜“规则”或者“rule”一般都能定位到。另外我建议在 Qoder 的新建项目中直接预置一份自己的项目规则模板这样每次开新项目不用从零写复制一份改改项目名就能用。这个小习惯能帮你在换工具的时候少掉很多头发。4. 一份可以直接抄走的长久记忆模板4.1 项目级记忆文件模板写了不少原则直接给一份我最近在用的项目级模板。这份模板覆盖了最常见的需求你复制到 CLAUDE.md 或 AGENTS.md 里把内容替换成你自己的项目信息就行# 项目名称 ## 项目概述 一句话说清楚这个项目是做什么的给谁用当前在什么阶段。 ## 技术栈 - 前端React 18 TypeScript Vite - 后端Node.js Express - 数据库PostgreSQL 15 - 部署Docker Nginx ## 常用命令 - 安装依赖npm install - 启动开发环境npm run dev - 运行测试npm test - 代码检查npm run lint - 构建生产包npm run build ## 目录结构要点 - src/components通用UI组件 - src/pages路由页面 - src/api接口请求层 - src/hooks自定义 Hooks - 不要把业务逻辑直接写在组件里统一放到 src/services ## 代码规范与约定 - 组件文件用 PascalCase 命名变量和函数用 camelCase - 样式用 CSS Modules不使用 Tailwind - API 请求统一走 src/api/client.ts 里的封装禁止直接 fetch - 错误处理顺序先捕获、再记录日志、最后抛给上层 - 数据库表结构变更必须写迁移脚本禁止直接改表 ## 已知约束和注意事项 - 第三方接口的 API Key 统一放环境变量禁止硬编码 - 线上环境日志级别是 warn开发环境是 debug - 老接口 /api/v1 正在迁移中新代码请优先使用 /api/v2 - 项目里有一些历史遗留代码在 legacy/ 目录不建议继续扩展 ## 当前待办 / 近期计划 - 迁移老接口到新网关 - 完善错误码文档 - 准备 2.0 版本的上线检查清单这份模板的核心逻辑是“AI 干活前需要知道的上下文”。你仔细过一遍每一条都是能直接指导 AI 行动的而不是介绍性废话。我建议你把责任人和日期也加到文件末尾方便之后维护的时候知道是谁在什么时候改的。4.2 全局记忆文件模板项目文件管项目全局文件管个人习惯。这里放一份适合放在用户主目录的全局模板Claude Code 是 ~/.claude/CLAUDE.mdCodex 是 ~/.codex/AGENTS.md# 全局工作偏好 ## 沟通方式 - 回答问题先给结论再展开细节 - 不确定的信息要明说不要编造 - 给出的代码要能直接运行不要留伪代码 ## 代码风格 - 前端优先选 TypeScript不要用 JavaScript 裸写 - 组件和函数尽量小拆开写方便测试 - 复杂逻辑必须补注释注释说清楚为什么而不是是什么 - 依赖包要克制能不用新依赖就不用 ## 项目操作习惯 - 修改代码前先给出简要方案再动手 - 大改动要分步骤提交不要一次性替换整个文件 - 改动完成后总结改了哪些文件、影响范围是什么 - 遵守项目的既有风格不按个人偏好硬改代码 ## 工具偏好 - 优先使用项目自带的命令执行测试和构建 - 命令行工具多用 git status 确认当前状态不要盲目操作 - 遇到报错先看日志再猜测原因全局文件的威力在于不管你开哪个项目AI 都会先读这一层再进项目。我经常给不同项目配不同的 CLAUDE.md但这个全局文件从配好那天起就没怎么动过因为它管的是“我怎么跟 AI 协作”这件跨项目通用的事。4.3 记忆文件的版本管理与团队共享CLAUDE.md 和 AGENTS.md 本质上就是普通文本文件所以它们也应该纳入 Git 管理。项目级的记忆文件建议提交到仓库里这样团队成员拉下代码的同时就拿到了项目的 AI 配置大家调教 AI 的经验也能沉淀到代码库里。我见过一个团队把 CLAUDE.md 写成了一个活的运维手册新人进来先让 AI 教他项目结构体验比看几十页旧文档好太多。全局记忆文件不建议提交到仓库它是高度个人化的东西放自己电脑就行。如果你有多个设备可以用云同步工具同步 ~/.claude 和 ~/.codex 这两个目录不用手动复制。这里有个建议项目级的规则文件改动要走 review。因为它会影响所有用这个仓库的 AI 行为如果某人写了一条“所有接口都用 mock 数据”这种临时规则没及时删除后面所有 AI 生成的代码都会被带偏。让更新走一次 code review能省掉不少返工的时间。5. 进阶玩法让记忆从“能用”到“好用”5.1 用子目录记忆文件控制生效范围Claude Code 和 Codex 都支持在子目录里再放规则文件作用范围限定在该目录及其子目录。这个特性特别适合项目里有多个模块、不同模块约定不一致的情况。我举个实际例子。有一个项目的根目录 CLAUDE.md 写的是“技术栈 React”但项目里有个 tools/ 目录里面是 Python 脚本。你可以在这个 tools/ 目录下放一个 CLAUDE.md写上# tools 目录专用规则 - 本目录是 Python 脚本不是前端项目不要在此目录执行 npm 命令 - 脚本运行方式python3 tools/xxx.py --envdev - 代码风格遵循 PEP 8但行宽可以放宽到 120 字符 - 不要在这个目录里引用前端的代码规范这样当 AI 在分析 tools 目录下的文件时会自动加载这一层规则不会被根目录的 React 规范误导。这相当于给 AI 配了一张“分层地图”到哪块区域看哪块规则。我实测下来对多语言混排仓库效果特别明显。5.2 用 引用保持记忆文件轻量记忆文件不设限地长下去早晚会因为占满上下文窗口拖累 AI 性能。我的解法是用 引用把细节挪到外部文档。Claude Code 的 CLAUDE.md 支持路径语法比如你在文件里写一行## 详细接口文档 docs/api-conventions.md启动时 Claude Code 会把引用的这个文件内容一并加载进来。更灵活的是引用路径可以是 glob 模式比如docs/*.md。用这种方式CLAUDE.md 本身保持精简详细信息放独立文档按需加载不占每一轮对话的上下文。实际操作中我会做一个分级策略核心信息技术栈、命令、规范直接写在 CLAUDE.md 里不管什么场景都要用扩展信息接口约定、部署流程、权限说明放在 docs 目录下用 引用。这样记忆文件始终保持在 80 到 120 行以内AI 加载得快执行也稳。5.3 把对话历史沉淀成记忆的“复盘”流程前面说的都是“事前配置”这里讲一个“事后维护”的习惯。每次和 AI 合作完成一个任务后花两分钟复盘一下这次对话里有没有哪些信息是下次还会用到的如果有就追加到相应的记忆文件里如果没有就保持原样。比如有一次我让 Claude Code 帮我排查一个上传功能的问题折腾了半天最后发现是 Nginx 的 client_max_body_size 太小。这个信息太有用了我直接追加到 CLAUDE.md 的“已知约束”里上传接口部署后如果报 413先检查 Nginx 配置。之后再有类似问题AI 第一反应就能想到这个方向排查时间缩短了一半。这个习惯比任何技术方案都重要。记忆文件不是写一次就能一劳永逸的它需要跟着项目的演化持续更新。我会在每个迭代周期结束的时候统一 review 一次记忆文件删掉过时的补充新发现的坑。一个项目的 CLAUDE.md 从最开始写的那天起会被我反复改很多次每一版都比前一版更接近“AI 一看就懂”的状态。5.4 更自动化的思路借助记忆服务如果你想更进一步不想手动整理记忆文件现在的生态里有一些专门做 AI 记忆的服务和 MCP 组件。它们的思路是把每次对话的关键信息自动抽取出来存到向量数据库里下次对话时根据当前上下文检索并注入相关记忆。这种方案的优点是完全自动不依赖你主动维护缺点是需要额外搭一套服务对于大多数单项目场景来说有点重。我的建议是先把 CLAUDE.md 这类文件式记忆用好它零成本、全局生效、可控可改。等你的记忆量真的达到手动维护不过来时再考虑上记忆服务不迟。小项目用文件大项目上服务这才是不走弯路的路线。6. 常见问题与排查实录6.1 记忆文件为什么不生效遇到最多的问题是文件名或位置不对。CLAUDE.md 就认这个大小写拼写你写个 claude.md 或者 Claude.md 它就完全不认。位置方面项目文件必须放在项目根目录放子目录只对子目录生效。全局文件要放在用户主目录下Windows 上是 C:\Users\你的用户名.claude\CLAUDE.mdmacOS 和 Linux 上是 ~/.claude/CLAUDE.md。还有一个容易忽略的点改了记忆文件之后已经启动的会话不会自动重新加载。你必须重启一下工具或者新开一个会话改动才会生效。很多人改完文件发现没效果不是改错了是没重启。6.2 记忆文件太长会拖垮 AI 表现记忆文件越长AI 的上下文窗口被占用的就越多。我之前有一次把整个项目的架构文档全塞进去结果 AI 写代码时上下文不足经常出现“忘了自己的输出格式”的情况。所有规则文件加在一起建议控制在 150 行以内超过这个量就要考虑分层了。判断记忆文件是否过长的标准很直接你问 AI 一个项目里很简单的问题如果它回答的内容里混入了大量无关的细节那多半是记忆文件太杂。这时候把不常用的内容挪到 引用的外部文档里或者直接删掉。6.3 多个工具之间记忆不互通怎么办如果你同时用 Claude Code 和 Codex维护两份记忆文件确实烦人。我的做法是维护一份母版放到项目根目录比如叫 AI_CONTEXT.md然后 CLAUDE.md 和 AGENTS.md 都引用它# CLAUDE.md 内容 此文件是入口实际内容见 AI_CONTEXT.md# AGENTS.md 内容 此文件是入口实际内容见 AI_CONTEXT.md这样你只需要维护 AI_CONTEXT.md 一份文档两个工具都能加载到。对于 Qoder 这类有自己的规则配置工具的可以把同样的内容粘贴到它的规则设置里没法自动同步但至少内容来源是同一个。6.4 记忆被“过度遵守”怎么办记忆文件写得太绝对有时候会反过来害你。比如你写了“样式用 CSS Modules不使用 Tailwind”结果后来项目引入了 TailwindAI 还是会遵守旧规则拒绝使用 Tailwind这时候你就得手动修正。我一般给规则加有效期特别是那些临时性很强的约束。比如“当前在迁移老接口新代码请优先使用 /api/v2”后面补一句“迁移完成后删除此条”。或者定期清理每次项目有大变动就过一遍记忆文件把所有过时的、不再适用的规则删掉。记忆文件的价值在于它是“活的”跟项目同步演化而不是一份写了就封存的历史档案。6.5 常见问题排查速查表症状可能原因解决办法记忆文件完全不生效文件名拼写或者位置不对检查文件名是否为 CLAUDE.md/AGENTS.md位置是否为项目根目录改了文件但没有反应当前会话没有重新加载重启工具或新开一个会话不要继续用旧会话记忆文件内容没完全被采用文件太长部分内容超出加载范围精简到 150 行以内关键信息往文件前部放多个工具回答不一致各工具读取的是不同文件统一出一份母版让不同规则文件都引用它AI 坚持旧的过时规则记忆文件里有过期条目定期 review删除临时性规则给规则加有效期某一子目录的规则覆盖了全局子目录规则优先级更高确认子目录规则确实是你想要的否则删除该文件本地模型接入时AI 回复不稳定本地推理服务未正常启动或配置不对检查本地服务的监听端口和配置重启后重新测试每次排查这类问题我都有一个固定套路先确认文件有没有被读到再确认读到的内容是不是最新版最后确认是不是被某个更高优先级的规则覆盖了。按这个顺序走大部分问题都能在几分钟内定位。我个人在实际操作中越来越觉得配置记忆文件这事的收益被严重低估了。它不花什么钱不占什么资源却直接决定了你每次和 AI 协作的起始水平。与其天天在对话里反复叮嘱同样事情不如花两分钟把它写下来。真正用顺手之后你会发现这些工具不像是“每次都失忆的新人”反而更像一个越用越懂你的老搭档。
