让AI Coding Agent真正懂你：规则文件与记忆库构建实战

同一个Agent为什么在别人手里像并肩作战多年的搭子到你手里就成了一个记性差得要命的新实习生这是我在好几个团队里反复观察到的问题。很多人以为AI Coding Agent的能力差距来自于模型本身其实大部分时候瓶颈出在“它根本不了解你”。它不知道你习惯用函数式还是类不知道你讨厌魔法数字不知道你提交信息喜欢用哪种规范更不知道这个项目里哪个模块是碰都不能碰的雷区。“让AI Coding Agent记住你”这件事听起来玄乎拆开来看就是一套工程方法把个人偏好、项目约定、历史决策、代码风格这些东西用一种Agent能读、能理解、能长期跟随的方式固化下来。这篇文章我把自己在几个项目里反复试过、踩过坑、最终沉淀下来的一套方法完整写出来包含规则文件的组织方式、记忆库的搭建思路、以及一套可复现的验证流程希望能帮你也把Agent调教成真正“懂你”的搭档。1. 先搞清楚一件事Agent永远比你想象的更容易“失忆”在动手配置之前我建议你先花五分钟想清楚一件事——Agent的“记忆”到底存在哪里。很多人的误区是把Agent当成一个人以为它聊过一次就能记住所有约定。实际上绝大多数Coding Agent的记忆机制是会话级的每次新开对话它基本就是一张白纸能看到的只有当前打开的代码文件、你的提问以及它底层自动加载的那点系统提示词。我自己做过一个很简单的实验同一个项目我在会话A里告诉Agent“表名请统一用snake_case”它照做了关掉会话第二天在会话B里让它写一个新表结构结果它给我返回了camelCase。这个现象不是偶然而是上下文隔离导致的必然结果。想明白这一点你就会理解“让Agent记住你”真正的含义——不是靠多聊而是把记忆写入它每次都能读到的地方。顺着这个思路往下推Agent能“读到哪里”无非四层信息源系统级提示词、项目规则文件、项目文档、代码仓库历史。系统提示词你动不了那是工具内置的代码仓库历史虽然信息量巨大但Agent在短上下文内很难主动翻完所有commit。真正可控、可塑、能沉淀下来的就是规则文件和项目文档这两块。所以整套方案的核心就是在这两层里构建一个能让Agent“按图索骥”的信息体系。另外一个容易忽略的点是“上下文窗口”的物理限制。Agent单次能处理的信息量就那么大如果你把记忆库写得又臭又长它反而会抓不住重点。我见过有人把项目背景写了上万字塞进规则文件结果Agent每次回答时都在背景故事里打转核心约定反而被稀释了。好的记忆不是“多”而是“准”——让Agent在有限的注意力里第一眼就能看到最关键的那几条铁律。这个认知是整个方案的地基。理解了“会话级记忆 有限上下文”的本质你才能明白接下来要做的每一件事本质上都是在给Agent设计一个低噪声、高信噪比的记忆入口。2. 规则文件怎么写得“够劲”全局配置与项目约定的分工明确了原理接下来就是动真格的时候。我习惯把规则文件拆成两层一层是全局用户规则管“你这个人的口味”一层是项目级规则管“这个项目的规矩”。两层各司其职缺一不可。2.1 全局规则先把你这个人立住全局规则回答的是“我合作的人是谁”。它写在你的用户配置文件里能被所有项目和所有会话共用。这份文件的核心是个人代码风格与偏好不是功能清单更不是备忘录。写的时候有两个原则具体、可执行。我自己全局规则里的几个片段给你参考# 代码风格偏好 - 命名变量/函数使用camelCase类名/类型名使用PascalCase常量使用UPPER_CASE - 函数长度单个函数不超过50行超过则需要拆分 - 类型偏好TypeScript项目中禁止使用any使用unknown并在边界处收窄 - 提交信息遵循Conventional Commits格式为 type(scope): subject - 不喜欢魔法数字所有业务数值必须提取为具名常量你可以发现这里面的措辞相当“命令式”没有“尽量”“通常”这类模棱两可的词。Agent在解析这类规则时确定性表达的执行概率远高于模糊表达。写完之后注意一点全局规则不要超过200行控制在100行左右最好。你想想看Agent每次回答都要把这堆提示消化一遍塞太满会影响它对当前任务的注意力得不偿失。2.2 项目规则把项目自己的脾气立出来项目级规则放在项目根目录作用范围仅限于这个仓库。全局规则解决“你惯用的写法”项目规则解决“这个项目特有的约束”二者必须分开否则换个项目时个人偏好会跟项目硬性约束混在一起经常出乱子。项目级规则我一般包括这几块技术栈清单、目录结构约定、数据流约束、命名规范、以及“禁区明细”。特别注意“禁区明细”——这是我踩坑之后总结出来的项目里总有那么几个文件或模块是Agent不该碰的比如自动生成的ORM映射文件、经过人工大量调优的SQL语句、以及某些只能手工改的配置文件。不明确写出来Agent就敢大动干戈地重构最后只能靠git找回场子。举个例子一个Spring Boot项目我常年在项目规则里写这么一段# 项目禁区 - src/main/resources/mapper/*.xml 为MyBatis手写SQL修改前必须与项目负责人确认 - src/main/java/**/entity/*.java 为自动生成代码禁止手动修改 - 涉及数据库索引变更必须先写迁移脚本禁止直接修改生产库另外还有个细节项目规则文件必须放在Agent默认会读取的位置。不同工具的约定不太一样你最好查一下你用的工具找一下哪几个文件是它启动时就自动加载的。如果你的工具支持自定义规则文件名我建议起一个一看就懂的名字别用什么“rules_temp_v3”之类的自己都记不住。2.3 规则文件的优先级顺位与防冲突设计文件和文件之间可能会打架比如全局规则让你用camelCase项目规则却规定数据库字段映射必须用snake_case。这不是bug是必然出现的场景。所以设计规则体系时一定提前想好优先级并且在规则文件开头写清楚。我的习惯是定义一个“就近优先”原则规则文件离代码越近优先级越高。也就是项目级规则覆盖全局规则目录级规则覆盖项目级规则。同时不同维度最好错开命名空间比如全局只管命名习惯、代码风格这类通用偏好项目只管技术栈、目录结构、数据约束这类项目专属内容互相少交叉冲突自然就少了。当你改了规则之后记得重启会话或者触发一次上下文重建否则Agent还是按老规矩办事。规则的修改必须和会话的开始对齐这个坑我踩过好几次后面会详细说。3. 给Agent搭一个记忆库项目上下文的持久化方案规则文件能承载的信息密度是有限的每个规则都只能是“纲领性的一句话”。但一个真实项目的约束远不止一句话能说清楚——为什么这个模块用了消息队列而不是直接调RPC为什么那张表冗余了三个字段为什么这里不做缓存这些历史决策对一个想深度协作的Agent来说价值比任何风格规范都大。我把这类“为什么”级别的信息固化在一个专门的记忆库里。3.1 记忆库的物理形态与目录规划所谓记忆库不是一个什么神秘的数据库而是项目仓库里的一个特定目录。我给它的标准命名是docs/agents/原因有两个一是“agents”这个名字能让不同AI工具一眼看出这里面是给它们读的二是放在docs下可以跟普通面向人类的文档做物理隔离避免Agent把面向新人的入门文档和面向自己的决策上下文搞混。在这个目录下我习惯维护三个核心文件docs/agents/ ├── MEMORY.md # 项目核心事实技术栈、模块地图、关键路径 ├── FACTS.md # 项目历史决策为什么选了A而不是B代价是什么 └── RULES.md # 项目专属规则比根目录的AGENTS.md更详细的操作级约定3.2 MEMORY.md把项目的地图画清楚MEMORY.md回答的是“这个项目长什么样”。我建议按模块来组织而不是按技术文档的方式写流水账。每个模块需要说清楚三件事这个模块的职责边界、它的主要入口和出口、以及它跟其他模块的依赖方向。写的时候有个很实用的技巧把那些“凡是新来的Agent大概率会问”的问题提前写进去。比如## 订单模块 - 职责订单创建、状态流转、超时关闭 - 入口OrderController#create、OrderEventConsumer#onPaid - 关键规则状态流转只能通过OrderStateMachine禁止直接setStatus - 依赖用户模块查询用户信息、库存模块锁定库存 - 常见坑创建订单时必须先锁库存再落订单顺序反了会出现超卖这段描述看起来简单但你仔细想想Agent拿到这份地图之后至少不会再面对“给你一个订单接口你应该去改哪个文件”这种问题还要靠猜。它更不可能去在你项目里乱翻一气之后自作主张把状态机跳过了。3.3 FACTS.md把“为什么”沉淀成资产FACTS.md是记忆库里最值钱的文件。它记录的不是现状而是演化过程。一个项目里到处都有的“现状”是从一堆“为什么”里长出来的Agent如果不知道这些“为什么”就很容易写出一个技术正确但架构走样的方案。我写FACTS.md的习惯是每条决策记五件事日期、背景、选项、选择依据、代价。例如## 2025-03-12 订单超时处理方案选型 - 背景订单创建后30分钟未支付需要自动关闭早期用定时任务扫表 - 选项A. 定时任务批量扫表 B. RocketMQ延迟消息 C. Redis过期监听 - 选择B - 依据订单量增长后定时任务扫描延迟高且扫表对DB压力大延迟消息可靠性优于Redis过期监听 - 代价引入了MQ依赖需要处理消息堆积的场景延迟精度受MQ调度影响当Agent在写新代码时看到这段记录它就知道“为什么不能走定时任务”不用你反复交代。这个文件还有一个额外作用当你自己回来维护一个半年没动的老项目时翻一翻FACTS.md比自己翻commit历史高效太多了——这算是额外福利。3.4 RULES.md: 操作级约定补全最后一块拼图前两个文件偏重“理解”RULES.md偏重“执行”。它跟根目录那个规则文件的区别在于RULES.md可以写得更细、更长因为它只在记忆库范围内被加载不会被Agent当成全局约束反复检索。我会把那些“要花三五句话才能说明白”的约束放到这里比如安全编码规范、特定库的使用限制、错误处理的统一风格、日志打点的字段规范。说句实在话这三个文件加在一起基本上就是Agent版本的“团队新人手册”。写一次之后它每一次新会话都会自己读一遍相当于你请了一个永不离职、记忆永不消退的新人。前提是——你得记得维护它项目演进了文档落伍了它会反噬成误导。4. 一个让记忆真正生效的完整实操演示前面把原理和框架讲清楚了但我知道光看理论不动手大部分人看完就忘。这一章我用一个完整的例子带你走一遍从零到一让Agent记住项目约定的实操流程。4.1 准备阶段先盘点现状假设我现在接了一个新的TypeScript后端项目用Fastify框架没有配置过任何Agent记忆相关的文件。第一步我不会急着写规则而是先花十分钟过一遍项目结构尤其关注三个点用了什么ORM、路由是怎么组织的、错误处理有没有统一封装。因为这些信息会直接决定规则怎么写写错了还不如不写。快速盘点之后我得到了几个关键事实项目用Prisma作为ORM路由按模块拆在src/routes/下没有统一错误处理中间件每个路由自己try/catch。这些观察结果就是记忆库的第一批素材。4.2 配置阶段三件套安排上我先把项目级规则放进根目录的AGENTS.md# 项目规则 - 技术栈Fastify Prisma PostgreSQL - 路由文件必须放在 src/routes/ 目录下文件命名按模块小写如 order.ts - 所有数据库访问必须通过Prisma Client禁止写裸SQL - 错误处理不能在每个路由里try/catch统一在全局错误处理中间件里处理 - 响应格式统一为 { code: number, message: string, data: T }然后建立记忆库目录并创建MEMORY.md和FACTS.md把盘点时发现的“现状”写成事实# FACTS.md ## 2025-04-10 错误处理现状盘点 - 背景当前每个路由独立try/catch重复代码多错误响应格式不统一 - 决策后续新代码统一走全局错误处理中间件 - 影响已有路由代码后续逐步迁移新路由必须遵守这个看起来简简单单的步骤恰恰是Agent能否“记住你”的关键分水岭。之前它只看到一堆代码现在它能看到“代码为什么长这样”的上下文行为会有本质变化。4.3 验证阶段用测试对话检验记忆是否生效配置写完不算完必须验证。我习惯用三个测试问题来确认Agent真的读进了这些记忆第一个问题请写一个创建订单的路由。观察它是否把路由文件放到了src/routes/下是否用了Prisma访问数据库是否没有在路由里自己写try/catch。第二个问题这个项目为什么没有在每个路由里做错误处理观察它是否能从FACTS.md里找到答案而不是瞎编。第三个问题如果我要加一个用户查询接口你会先看哪些文件观察它给出的文件列表是否跟项目实际结构匹配。如果三个问题都答对了说明记忆体系已经生效。如果答错了不要急着改规则先检查一下Agent有没有重新加载记忆库是不是命名空间不对规则文件有没有语法问题导致解析失败排查思路我在下一章展开。我刚配置完这套方案后做了一次测试让它写一个新接口它给出的代码不仅放在了对的目录、用了对的ORM、没有自己写错误处理甚至还在注释里标注了一句“错误处理统一走全局中间件不在路由内处理”——那一刻我确实有点感慨这个Agent是真的“记住”这个项目的逻辑了。5. 常见问题与排查技巧实录配置记忆体系的时候我几乎把能踩的坑都踩了一遍。这一章把最常见的五种状况整理成一个速查表并补上一些排查思路希望能帮你少浪费几个晚上的时间。症状可能原因排查思路Agent完全不读规则文件规则文件命名或位置不符合工具的加载规范查看工具文档确认默认加载的是AGENTS.md还是其他文件名检查文件是否在仓库根目录规则生效了但不是全部生效某个Markdown段落解析失败或规则之间有冲突逐段精简规则用最小化测试法找到问题段落确认是否存在全局规则与项目规则冲突Agent读了规则但行为不变当前会话仍是老上下文没有加载新规则重新打开会话或手动触发上下文重建确保新规则进入Agent的初始提示记忆库越来越长响应质量反而下降记忆文件过度膨胀噪声覆盖关键信息精简MEMORY.md把不再重要的“为什么”归档把最核心的约束控制在300行以内Agent把记忆库自己的内容改得面目全非规则文件命中了可编辑范围被Agent当成了普通代码在AGENTS.md中明确声明“docs/agents/目录下的文件仅供阅读禁止修改”必要时将该目录设置为只读除了表格里这些还有两个更隐蔽的问题值得单独拿出来说。第一个是记忆的时效性维护。项目不是静止的技术栈会升级、架构会调整记忆库如果长期不更新里面的“事实”就会变成“谎言”。我给自己的强制约定是每次做架构级变更时同步更新FACTS.md每次新模块落地时同步修改MEMORY.md。这个习惯养成了记忆库的可靠性会一直在线。第二个是不要在规则里写“过程性描述”要写“结果性约束”。比如“你应该先去理解订单状态机再修改状态”这种话Agent读了等于没读但如果你写“订单状态修改必须通过OrderStateMachine禁止直接setStatus”它就非常清楚边界在哪里。前者描述路径后者定义边界Agent对边界的执行力远强于对路径的理解力。还有一个很容易被忽视的问题就是规则文件里的语气词。我测试过“请使用xxx”和“必须使用xxx”对Agent行为的影响结果是后者在代码生成时的遵守率明显更高。不是说“请”字会让它叛逆而是公文式的命令句在语义上更接近“硬约束”而礼貌句式更像“建议”。想让它100%执行就用词干脆一点。最后再分享一个小技巧当你怀疑规则文件没生效时最有效的排查方式不是反复改规则而是直接在对话里问Agent“我们这个项目约定里有没有要求路由不允许自己try/catch”。它的回答能让你一眼看出它有没有读到相关记忆比你猜来猜去快得多。这套方法我用到现在成功率很高很大程度上就是靠这种“直接查它记了什么”的排查思路。