让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. 常见问题与排查技巧实录

配置记忆体系的时候，我几乎把能踩的坑都踩了一遍。这一章把最常见的五种状况整理成一个速查表，并补上一些排查思路，希望能帮你少浪费几个晚上的时间。

除了表格里这些，还有两个更隐蔽的问题值得单独拿出来说。

第一个是记忆的时效性维护。项目不是静止的，技术栈会升级、架构会调整，记忆库如果长期不更新，里面的“事实”就会变成“谎言”。我给自己的强制约定是：每次做架构级变更时，同步更新FACTS.md；每次新模块落地时，同步修改MEMORY.md。这个习惯养成了，记忆库的可靠性会一直在线。

第二个是不要在规则里写“过程性描述”，要写“结果性约束”。比如“你应该先去理解订单状态机，再修改状态”这种话，Agent读了等于没读；但如果你写“订单状态修改必须通过OrderStateMachine，禁止直接setStatus”，它就非常清楚边界在哪里。前者描述路径，后者定义边界，Agent对边界的执行力远强于对路径的理解力。

还有一个很容易被忽视的问题，就是规则文件里的语气词。我测试过“请使用xxx”和“必须使用xxx”对Agent行为的影响，结果是后者在代码生成时的遵守率明显更高。不是说“请”字会让它叛逆，而是公文式的命令句在语义上更接近“硬约束”，而礼貌句式更像“建议”。想让它100%执行，就用词干脆一点。

最后再分享一个小技巧：当你怀疑规则文件没生效时，最有效的排查方式不是反复改规则，而是直接在对话里问Agent“我们这个项目约定里有没有要求路由不允许自己try/catch？”。它的回答能让你一眼看出它有没有读到相关记忆，比你猜来猜去快得多。这套方法我用到现在，成功率很高，很大程度上就是靠这种“直接查它记了什么”的排查思路。