AI编程范式转换：用AGENTS.md构建可复用的项目长期记忆

接手这类AI项目时最常遇到的一个尴尬是模型本身能力很强但一进入实际工程环境它就变成“第一次见面的陌生人”。你之前告诉它的规范、偏好、业务逻辑只要会话一关全部清零。尤其做项目交接或跨模块协作时新来的模型实例不知道你的代码风格、不知道你的构建命令、不知道你踩过哪些坑一切都要重新“教育”一遍。这个问题困扰了我很久直到我把注意力从“提示词技巧”转向“Memory 工程”并开始系统性地使用 AGENTS.md 声明式配置整个局面才真正打开。这篇内容想和你聊的就是所谓 AI 编程范式转换背后那块最容易被忽视的基石记忆工程。从无状态模型的天然短板到 AGENTS.md 这种声明式配置如何为 AI 构建可复用的长期记忆我会拆解其中的设计思路、目录结构、实操步骤和踩坑记录。适合正在做 AI 辅助开发、维护多模块项目、或者想建立团队级 AI 协作规范的开发者参考。它不是一篇理论科普而是我个人在一线项目中反复调试后沉淀下来的做法。1. AI 编程范式的转换为什么“无状态”开始成为瓶颈1.1 模型本身没有记忆这不是缺陷而是架构事实做 AI 应用开发的人应该都体会过这种割裂感你可以让模型写出非常惊艳的代码但它对自己的“创作过程”毫无记忆。每一次对话都是白纸一张它不知道你十分钟前刚确认过接口命名规则也不知道你上个迭代已经废弃了某个模块。这不是模型“笨”而是它的底层架构决定了上下文窗口之外的东西对它来说就是不存在。以 Transformer 架构为例模型对输入的理解完全依赖于当前上下文窗口里放进了哪些 token。窗口就像一块移动的白板写满了就得擦掉旧的才能写新的。只要信息没有被写进这块白板模型就无从感知。哪怕你之前在某次对话里详细描述过项目的目录规范只要这次对话没有把那段描述带进来它就会按照自己的通用直觉重新发挥——结果就是它给出的方案可能从单点看非常合理放在你的项目里看却处处和既有约定打架。这种“无状态”特性在单次对话、单文件生成的场景下问题不大。可一旦面对真实的软件工程项目动辄几十个模块、多套构建脚本、若干种部署环境“无状态”就成了效率黑洞。每个模型实例都在重复理解你的项目就像每次来一个新人开发都得把项目文档从头读一遍。而且这个“新人”还特别聪明、特别有主见你如果不在上下文里明确约束它它会非常自信地给出各种“标准做法”——而“标准做法”往往和你的项目实际诉求相去甚远。1.2 传统 Prompt 工程的局限性临时记忆 vs 长期记忆很多人会下意识地认为那我每次对话多写点上下文不就行了把项目背景、代码规范、技术栈统统塞进系统提示词里模型总能记住吧。这种思路本质上是在“临时记忆”层面做文章——通过上下文窗口里的内容影响模型在当前会话中的行为。问题在于这种“临时记忆”有几个难以绕开的硬伤。第一上下文窗口容量有限塞进去的大段规范会挤占真正用于代码生成的空间处理长文件时往往顾此失彼。第二每次新建会话都要重新粘贴一遍粘贴的内容稍有出入模型的行为就会跟着波动。你很难保证今天贴的规范和上周贴的完全一致。第三多模块项目里每个模块的技术背景不同、规范侧重不同一份通用的系统提示词根本覆盖不过来。我试过一个比较典型的做法为项目写了一份非常详细的系统提示词涵盖目录结构、命名规范、测试要求将近两千字。第一次用效果很好模型产出的代码基本都能对上项目风格。但到第二个模块时我打开新会话复制的还是那份提示词却忘了一处关键的内容——那个模块的特殊部署约束。于是模型照着一份“过时”的记忆开始工作产出了一个在其他环境能跑、在那个特定模块里却完全跑不通的方案。这说明什么临时记忆本身没有任何“版本管理”可言它完全依赖每次输入时的复述质量。一个人为维护这份记忆的准确性成本高、易出错、不可扩展。真正可持续的做法是把这种“临时记忆”固化成项目的一部分让它随代码库一起存在、一起演进每次模型进入项目时自动加载。这就是所谓的“长期记忆”也就是 Memory 工程真正要做的事情。1.3 AGENTS.md 作为一种声明式的项目记忆载体提到 AGENTS.md 这种文件我不太想把它简单理解成“给 AI 看的 README”。因为 README 面向的是人类开发者它默认读者具备一定的理解能力和推断能力不需要把所有规则都写到绝对明确。但 AI 不一样它更像一个极度聪明但缺少项目常识的实习生——你如果不把“清单里每一项都要执行”“已废弃的接口不要使用”“测试必须跑通后才能提交”这些话说清楚它就不会主动遵守。AGENTS.md 的价值在于它用一套声明式的、可解析的格式把项目对 AI 代理的所有约束、偏好、任务边界、操作流程固化下来。模型进入项目工作目录时自动扫描并读取这份文件把它当作行为的最高优先级约束。它不再依赖一次性输入而是成为项目仓库中的一等公民——随代码提交、随版本演进、随团队维护。从这个角度说AGENTS.md 是给 AI 代理的一份“岗位说明书”它把人的经验、项目的事实、团队的约定沉淀成了机器可读的字符。我在实践中越来越感受到一个转变之前是“每次告诉 AI 你是谁、你要做什么、遵循什么规则”现在是“把规则写进项目结构里AI 进来自己看”。前者是程序化的、一次性的、不可复用的后者是声明式的、持久化的、结构化的。这种转变本质上就是从“对话式记忆”走向“文件化记忆”。不依赖任何人每次记得去灌输而是靠工程手段让记忆自动附着在项目之中。2. Memory 工程解析AGENTS.md 如何构建结构化记忆2.1 认知记忆与结构记忆项目记忆的两种形态在深入 AGENTS.md 之前我建议先理清一个概念框架项目记忆至少可以分成“认知记忆”和“结构记忆”两个层面。所谓认知记忆指的是那些存在于开发者头脑中、或者是沟通文化里的东西——为什么这个模块要这么设计、为什么那个接口要加这个参数、为什么线上环境禁用某些操作。这类记忆通常不会写进代码注释也不会出现在 README 里但真实项目的推进恰恰高度依赖它们。AI 代理没有人类的“行业经验”更不可能像同事那样靠闲谈获得上下文所以认知记忆如果不落地对 AI 来说就是不存在的。所谓结构记忆则是通过文件、目录、配置、脚本等形式固化下来的知识——目录怎么组织、构建命令是什么、代码风格规范有哪些、测试策略怎么执行。这类记忆天然适合用文本承载也天然适合被 AI 读取。AGENTS.md 做的就是后者的工程化把项目中可陈述、可约束、可执行的规则整理成结构化的记忆文件让模型在进入项目时能够“看到”这些约定。我见过不少开发者的误区试图让 AI 记住项目的全部“背景”包括各种隐含的业务逻辑和设计权衡。这种期望不现实也不必要。AI 真正需要的是那层“结构记忆”——它能够在进行代码修改、文件操作、命令执行时准确地知道自己该站在什么规则框架内行事。至于业务层面的深层理解那是人在迭代中不断传递的。AGENTS.md 的定位应该是项目协作的“规则层”不是“思维层”。2.2 AGENTS.md 的工作机制扫描、注入与约束理解了记忆分类再看 AGENTS.md 的机制就清晰多了。它的核心工作循环可以用三个词概括扫描、注入、约束。扫描发生在 AI 代理进入工作目录的时候。主流开发环境的 AI 工具都会自动检查当前项目根目录是否存在 AGENTS.md一旦发现读取并载入上下文。我碰到过一些开发者手动把 AGENTS.md 内容贴进系统提示词然后抱怨“为什么不自动加载”——其实就是没理解这个发现的机制。它不是一个需要手动附加的插件而是约定俗成、由工具原生支持的入口。注入指的是文件内容被加入本次会话的上下文。这个动作和读取普通文本文件没有本质区别但关键点在于它的“优先级”。AGENTS.md 通常被视为项目级指令其约束效力高于后续对话中的一般要求。打个不精确但形象的比方你可以在对话里让 AI 这次把注释写成中文但 AGENTS.md 里若明确了“注释统一英文”AI 通常会选择遵守项目文件里的规则。因为工具的底层逻辑里项目级配置就是对会话行为的基本约束。约束则是 AGENTS.md 真正发挥价值的地方。它允许你把项目里的“潜规则”显性化哪些命令是必须先跑的、哪些目录是不能动的、哪些命名是必须遵守的、哪些告警是必须消除的。AI 不再是自由发挥的“天才实习生”而是在明确边界内行动的“熟悉业务的开发者”。对于团队协作或开源项目来说这种约束能力尤其重要——它让 AI 产出的代码具备统一的项目指纹而不是十个会话产生十种风格。2.3 一个简单的 Memory 结构示例直接看一个最小化的 Memory 结构会更有体感。假设这是一个 Python 后端服务项目根目录的 AGENTS.md 可以长这样# AGENTS.md ## 项目概览 - 项目名称: marketplace-api - 技术栈: Python 3.11 FastAPI PostgreSQL - 核心目录: app/、tests/、scripts/ ## 开发命令 - 安装依赖: poetry install - 运行测试: poetry run pytest - 启动开发服务: poetry run uvicorn app.main:app --reload - 代码规范检查: poetry run ruff check . ## 代码约束 - 所有接口函数必须添加类型注解 - 数据库操作一律通过 SQLAlchemy 2.0 异步会话 - 禁止在 service 层直接操作数据库统一走 repository 层 - 对外 API 一律使用 Pydantic schema 定义请求/响应模型 ## 测试规范 - 新增功能必须配套单元测试覆盖率达到 90% 以上 - 集成测试统一放在 tests/integration/ 目录下 - 涉及外部服务调用时使用依赖注入方式 mock禁止修改真实请求 ## 禁忌事项 - 不要修改 migrations/ 下已发布的版本文件 - 不要向 app/core/config.py 中直接写入明文敏感信息 - 不要使用未被项目依赖的第三方库就这么一个文件AI 代理在进入项目时就有了“全局记忆”。它知道项目用什么技术栈、用什么命令测试、有哪些代码红线。不需要你反复在对话里强调更不需要担心对话窗口滚动后信息被冲掉。每次新会话它都能基于这份结构化记忆以相对稳定的行为标准开展工作。我把这种设计类比成给 AI 代理发了一本“项目员工手册”。手册不是为了限制它的能力而是为了确保它的能力能够在项目语境中正确释放。没有手册能力越强跑偏的破坏力就越大有手册能力才能沿着项目需要的方向精确释放。3. 实操从一个传统项目迁移到 AGENTS.md 工作流3.1 盘点存量项目的信息资产真正动手迁移的时候第一件事不是写 AGENTS.md而是盘点项目里到底有哪些“隐性规则”。这个步骤很多时候都会被跳过但恰恰是决定 AGENTS.md 质量的关键。打开项目仓库我会重点看几类东西一是 README 中给出的命令和架构说明二是 CONTRIBUTING 或开发规范文档中的硬性要求三是代码审查时反复被指出的共性问题四是 Makefile 或 CI 配置中暴露的构建流程。把这些散落在不同位置的信息集中起来你会发现项目其实已经有了不少“记忆”只是它们处于碎片化状态各自躺在不同文件里AI 代理没法高效地一次读完。比如我之前接手的那个项目README 里提了一句“开发环境用 docker compose 启动”但并没有写明数据库迁移要执行 alembic upgrade head。这条命令躺在 Makefile 的注释里人和人协作时靠口头传播AI 代理却无从得知。等我在 AGENTS.md 里显式写明所有命令序列后模型生成的部署脚本立刻变得更贴合项目实际了——很多之前“看起来还挺合理但完全没法用”的问题本质上就是因为缺失了这类“项目专属知识”。3.2 信息优先级设计与分层策略盘点完信息资产之后接下来要做的不是全塞进一个文件而是做优先级分层。我的做法是三个层次指令层、规范层、上下文层。指令层放最硬性的约束比如禁止命令、安全管理条款、不可修改的目录这些是 AI 无论如何都不能僭越的底线。规范层放风格、约定、流程类的条款比如命名规则、提交信息格式、测试策略这些影响产出的质量与一致性。上下文层则放项目背景、模块职责、依赖关系等解释性信息帮助 AI 理解当前工作的周边语境而不是直接规定行为。这三个层次中指令层的优先级最高规范层次之上下文层作为辅助。设计时我会有意识地控制层级之间的信息冗余——不要在同一份文件里既规定“测试必须用 pytest”又在上下文层解释“pytest 是一个 Python 测试框架”。后者对 AI 是常识多写反而稀释关键约束的权重。我最初犯过一个错误把所有信息揉成一团写了将近三千字。结果 AI 的行为不仅没有更可控反而因为信息太多指令间的优先级互相打架。后来我做了分层精简把内容控在一千五百字以内约束变得更少、更明确、更可验证效果反而大幅提升。做 AGENTS.md 如同写有效提示词少即是多关键不是“把自己知道的都告诉它”而是“把必须约束的都说清楚”。3.3 逐步迁移从最小可用版本到持续迭代落地的时候我建议不要一上来就追求完备的 AGENTS.md。更稳健的做法是从最小可用版本开始先写三块必选内容——项目概览、开发命令、核心约束每块控制在几个条目。让 AI 代理先跑起来观察它在哪些地方表现得不符合预期再针对性补充规则。我自己迁移时的节奏是这样的第一周先搭好最小版本的 AGENTS.md所有对话都通过工具自动加载这份文件。期间记录每次模型产出的问题是风格偏差、命令错误还是约束违反。第二周汇总这些问题把它们转化为 AGENTS.md 的补充条款。之后再持续迭代每周花十分钟根据新出现的问题微调文件。大约一个月后那份 AGENTS.md 已经相当贴合项目的实际工作流了。这里有一个很关键的细节AGENTS.md 不是“写完了就行”的一次性资产它应该和代码库一起演化。每次项目规则发生变化比如切换了测试框架、调整了目录结构、废弃了旧的接口规范都应该同步更新 AGENTS.md。我习惯于把 AGENTS.md 的变更作为独立 commit 提交并在提交信息里写明变更原因。这样项目的记忆演进就有了审计历史团队其他人也能通过 git 记录看到 AI 协作规范的调整脉络。4. AGENTS.md 的内容框架设计把规则写进项目骨髓4.1 项目级指令结构基于多轮实操我沉淀了一套比较好用的 AGENTS.md 内容框架。它不一定适合所有项目但可以作为起步模板根据自己项目的实际情况裁剪。核心部分包括项目身份一句话清楚项目是干什么的技术栈核心版本服务的用户或场景。快速开始从克隆到跑通本地开发全流程需要执行哪些命令按顺序列全。项目地图核心目录的职责说明标注哪些目录承载核心业务逻辑、哪些目录是基础设施代码。开发循环编码、测试、lint、构建的完整命令链确保 AI 知道开发中的每个环节该用什么命令验证。代码约定命名规范、注释要求、接口设计约定以及禁止事项。变更流程提交、代码审查、合并或者部署的相关要求。这套结构具备比较大的普适性因为它的设计逻辑是从“模型进入项目后最需要知道什么”出发的而不是从“项目文件里现有信息有什么”出发的。我见过一些 AGENTS.md 直接照搬 README 结构结果 AI 读完还是不知道一个功能从开发到上线要经过哪些步骤。真正的记忆工程重点不是信息的堆砌而是信息的组织逻辑必须围绕 AI 的任务执行链展开。4.2 从实际项目抽取的 AGENTS.md 模板拿一个我实际维护过的微服务项目举例这是我精简后的模板结构# AGENTS.md ## 项目概览 - 微服务架构核心服务拆分边界以 domain 划分禁止跨 domain 直接调用 - 技术栈Go 1.22 gRPC PostgreSQL Redis - 模块结构internal/domain、internal/service、internal/repository、internal/api、pkg/ ## 本地开发命令 1. 启动依赖服务: make infra-up 2. 编译并运行: make run 3. 执行单元测试: make test 4. 检查代码格式: make lint ## 新增接口流程 1. 在 proto 文件定义接口与消息结构 2. 运行 make proto 生成服务代码 3. 在 service 层实现业务逻辑禁止在 api 层写业务 4. 编写 repository 层数据库访问方法 5. 为新增接口添加单元测试和集成测试 6. 运行 make test make lint 确保全绿 7. 提交 MR描述变更内容与测试结果 ## 代码约束 - 所有错误必须显式返回 error禁止吞掉错误 - 日志统一使用结构化日志输出禁止裸 print - 数据库连接串、密钥等敏感信息必须从环境变量或配置中心读取 ## 命令执行须知 - make test 是整个测试套件新增功能必须保证能够通过 - make proto 在修改 proto 文件后必须执行否则编译会失败这个模板和我最初写的那版相比关键变化是什么它不再是一堆规则的清单而是一份“操作手册”。AI 代理拿到它能理解一个需求从提出到上线的完整动作序列并且在每个环节都知道自己应该调用什么命令、遵守什么约束。这种结构才是真正把无状态模型“变成”有项目记忆的协作者的关键。4.3 约束的可验证性设计AGENTS.md 的条款如果只是模糊的“保持良好的代码风格”对实际行为影响非常有限。AI 模型对模糊指令会倾向于做出它认为“最合理”的解释而这往往不是你的项目风格。所以在编写约束条款时我坚持一个原则每条约束都要能转化为可执行的检查动作。拿“禁止在 service 层直接操作数据库”来说这句约束本身不够可操作AI 在执行中可能仍然会犯。但如果加上“所有数据库访问必须定义在 repository 层service 层只可调用 repository 接口”并把目录结构注明清楚模型收到的就是一个清晰的行为边界看到需要访问数据库的请求就知道该改哪个文件、不该改哪个文件。更进一步可验证性还体现在命令层面。我会刻意在 AGENTS.md 里写明类似“完成代码修改后必须执行 make lint 并修复所有报错”这样带动作指向的条款。它让 AI 的行为终点是可检查的工具会看到模型调用了 lint 命令并且基于命令结果调整后续动作。如果约束仅是“保持代码风格良好”工具没有任何检查手段行为就完全不可控。还有一个容易忽略的设计点每一条约束之间不能相互冲突。我踩过的一个坑是某次我在 AGENTS.md 里同时写了“模块间通信禁止直接调用内部方法”和“为快速迭代可直接复用 internal 包中的辅助函数”。AI 代理每次遇到跨模块复用场景就开始犹豫或者直接选择了报错的路径。理由是它无法判断哪一条约束在当前场景下拥有更高优先级。后来我把约束改为带例外条件的单一表述问题立刻消失。设计 AGENTS.md本质上就是在为模型构建一套无歧义的行为决策树任何可能产生分支歧义的表述都要在写入之前消解掉。5. 在真实开发循环中落地 Memory 工程5.1 会话开始让 AI 先读项目记忆再动手流程化的落地方式通常是在每次会话开始时先让 AI 代理确认它已经读取了 AGENTS.md 的内容。有些环境会自动加载有些可能需要显式触发。我更习惯的做法是在会话第一轮就向模型发出明确请求“请先阅读项目根目录的 AGENTS.md并复述你理解的项目约束然后我们再开始任务。”这一步看起来多余其实价值很大。第一它强制模型把项目记忆从“被动的上下文存在”提升为“主动的工作准备”。模型要复述约束就必须真正理解那些条款而不是仅仅在上下文中扫过。第二通过模型的复述我可以立即发现 AGENTS.md 里哪些部分会让它产生误解。之前有次模型复述时把我写的“建议使用依赖注入”理解成了“必须全部重构成依赖注入容器”这正是表述歧义导致的执行偏差。借由复述环节这种问题能很快暴露并修正。对于复杂任务我还会在 AGENTS.md 的基础上补充一份“会话任务清单”把当前这次迭代的具体目标、范围边界、自检测试要求单独列出来。AGENTS.md 提供长期记忆的稳定框架任务清单则提供单次迭代的动态目标。二者结合模型既不会迷失在项目规则里也不会完全不知道本次改动的重点是什么。5.2 维护项目记忆的演化节奏长期使用 AGENTS.md 后最大的变化是它会自然地“长大”。初期版本可能只有一两百字经过几轮迭代后会稳定在千字左右。这个过程中需要控制几个节奏问题。第一个是容量控制。AGENTS.md 不是越长越好。当它超过两千字时模型在上下文中的注意力会被稀释真正关键的约束反而容易被“淹没”。我给自己定了一条线如果新增条款导致文件接近两千字必须先删掉或合并一些不再重要的旧条款。持续保持“精炼、可验证、无冗余”的状态。第二个是变更同步。项目记忆必须跟上项目现实变化。每次技术栈升级、目录调整、流程变更后第一件要做的事就是检查 AGENTS.md 是否仍然准确。过时的记忆比没有记忆更糟糕因为它会驱动模型按照已经废弃的规则去工作。我会在项目的 CI 中加一道轻量检查AGENTS.md 的变更与代码变更必须成对出现防止记忆文件因缺乏维护而腐烂。第三个是团队共识。AGENTS.md 不只是给 AI 看的也是给团队所有人看的。这个文件本质上把团队对项目的共识显性化、结构化。新成员加入项目时让他先读 AGENTS.md比让他啃几个月的代码再感悟来得快得多。而老成员在代码审查时也可以基于 AGENTS.md 来约束 AI 生成代码的质量。团队协作和 AI 协作在这个文件上形成了一个统一的参照系。5.3 多模块场景下的 Memory 组织策略真实项目很少是单体仓库里一份 AGENTS.md 就能覆盖的。一旦项目拆成多个模块或微服务记忆的组织方式就需要重新设计。我的策略是“根级治理 模块级细则”的双层结构。根目录的 AGENTS.md 放全仓统一约束技术栈基线、通用的代码风格、提交规范、CI 流程。每个模块各自维护自己的 AGENTS.md存放模块特有的命令、依赖关系、架构约束。模型在处理某个模块任务时既能读取根级规则掌握全局底线也能读取模块级文件了解局部约束。举个例子一个仓库里同时有 Python 数据管道模块和 Go 微服务模块。根级 AGENTS.md 只写“测试数据库统一使用容器化环境”“提交信息必须遵循规范”。Python 模块的 AGENTS.md 写明“依赖管理使用 poetry新增依赖必须更新 pyproject.toml”。Go 模块的 AGENTS.md 写明“对外 API 必须带 protobuf 注释生成代码不得手动编辑”。AI 代理取相应模块时拿到的记忆便是既精准又不失全局观。这种分层方式能避免一个严重的坑把所有项目约束都堆在根级文件里不同模块的信息互相干扰。之前没有分层时AI 在处理 Go 模块时读到了 Python 模块的依赖管理规则居然有几次试图通过 pip 安装 Go 工具链的依赖场面非常混乱。分层之后这种跨模块规则污染基本消失。项目越大分层策略带来的收益越明显。6. 绕过那些坑AGENTS.md 实操中的高频问题与排查技巧6.1 问题速查当 AI 不按规则办事时先查哪个文件就算 AGENTS.md 写得再完善实操中也总会遇到 AI 行为偏离预期的情况。以我个人的经验遇到这种时候排查顺序大概是这样先看文件本身有没有被正确加载。很多工具需要在项目目录下启动才能自动识别 AGENTS.md如果你在某个子目录或者通过临时文件发起会话文件可能根本没进入上下文。怎么确认直接问模型“你读取到的 AGENTS.md 内容里有哪些命令”如果回答和你写入的内容对不上就是加载链路出了问题。再看文件里的表述是否够“死”。我最初写的一些条款类似“尽量使用依赖注入”“建议避免全局变量”这种措辞给模型留下了太大的自由裁量空间。它会把“建议”理解成“可选”把“尽量”理解成“看情况”。后来我把这些全部改成硬性表达“必须使用依赖注入”“禁止使用全局可变状态”。AI 对“禁止”“必须”的响应强度远高于“避免”“尽量”。如果文件加载和表述都没问题接下来就要检查是不是约束与约束之间打架。模型会在内部自行判断哪条规则优先而这种判断往往和你预期的并不一致。排查方法很直接把 AGENTS.md 里所有条款通读一遍标记出可能出现冲突的两个条目重新消歧。有时候是前后表述重复但范围有细微差异导致模型无法确定谁覆盖谁。6.2 几个典型的记忆污染场景与规避手段我在不同项目里遇到过几种非常典型的“记忆污染”场景在这里整理出来供大家参考。第一种是跨项目的会话污染。有些 AI 开发工具支持多个项目目录切换如果在同一会话里先处理 A 项目再处理 B 项目模型可能会把 A 项目的约束带到 B 项目中。规避手段是处理不同项目时强制开启新会话并在新会话开始时先让模型确认读取的是哪个 AGENTS.md。第二种是用户对话中的临时规则覆盖项目规则。有人会在对话里补充“这次例外一下不用跑测试了”模型可能直接放弃测试流程。针对这个问题我在 AGENTS.md 里增加了一条说明“AGENTS.md 中的约束为项目基线除非用户明确说明临时覆盖否则始终生效。”这能大大降低模型被单次对话带偏的概率。第三种是 AGENTS.md 文件内容的无意污染。比如某些 AI 工具会自动把打开过的文件内容加入上下文模型如果 AGENTS.md 里混入了无关的调试内容或旧版本残留模型就可能在执行时参考这些垃圾信息。我养成了一个习惯AGENTS.md 每次修改后立即关闭并重新打开会话确保模型读取的是最新的、干净的文件版本。6.3 当你发现 AGENTS.md 越写越长从膨胀到重构最后聊一个几乎每个人都会遇到的问题——AGENTS.md 的“膨胀”。随着项目规则越来越多文件里塞进了各种边界情况、例外条款、历史教训。写到两三千字之后模型的行为不仅没有更好反而开始出现一些莫名其妙的保守倾向因为限制太多它不敢正常做决定了。我经历过一轮很典型的膨胀期当时 AGENTS.md 里已经有四十多条约束覆盖了包括异常日志格式、注释语言、缩进宽度、依赖版本范围、函数最大行数在内的各种细节。模型产出的代码语法上没问题但感觉“像被绑住了手脚”宁可写一堆防御性的冗余代码也不敢按直觉实现功能。后来我做了一次大重构原则只有一个把所有约束按“发生频率”和“代价严重度”排序。发生频率高且违反代价大的保留发生频率低且代价可控的删除或者挪到模块级文件。那次重构砍掉了将近一半条款剩余的每一条都是高收益的“硬约束”。重构之后模型的产出质量反而显著上升——因为它在核心约束上更专注了。这也提示我一个更底层的事实AGENTS.md 的编撰本质上是在做人机协作的“最小必要规则集”设计规则太少会让模型跑偏规则太多会让模型僵化。找到那个动态平衡点需要根据项目的实际迭代情况持续校准。没有一劳永逸的完美文件只有不断逼近、持续演进的项目记忆。这一整套方法对存量项目和从零开始的新项目都适用只不过迁移路径不太一样。新项目可以从第一天就铺好记忆框架每次规则变化随时代入存量项目则需要先完成一轮信息盘点和重构把散落在文档、注释、代码审查里边的隐性规则捞出来再逐步固化到 AGENTS.md 里。我自己更建议团队里指定专人负责记忆文件的维护——可以是技术负责人也可以是基础设施方向的开发者。因为这份文件本质上是在整理团队对项目怎么做的共识它需要有人持续跟踪项目演化持续优化文件的约束质量。一个人负责整理团队所有人和所有 AI 代理共同受益这笔投入的长期回报相当可观。