如果你也试过让 AI 助手帮你写科研代码，大概率经历过这种场面：上午刚让它改完数据预处理脚本，下午接着聊，它却忘了你项目的存储路径、变量命名习惯，甚至把核心实验假设理解偏了。我踩了无数次这种坑之后，开始认真琢磨一件事——怎么给 AI 配一份“不会过期的记忆”。最后用得最顺手的组合，就是 AGENTS.md 和 PROJECT.md 这两份文件，一配合，长期项目的维护立刻轻松了不少。
先说清楚，这东西不是只给程序员用的。做科研、做数据分析、跑实验、写论文的，只要你会用 AI 帮你写脚本、整理结果、生成图表，都值得试一试。它的本质是：把你脑子里的项目背景、规则和当前进度，用文档形式固化下来，让 AI 每次接手都像读了一份“项目简报”，而不是靠你反复口头喂。
1. 为什么长期项目需要“给 AI 写说明书”
很多人的第一反应是：我已经在对话里跟 AI 说清楚了啊，为什么要多写两份文件？我一开始也是这么想的，后来才发现，AI 对话模式的上下文管理，根本撑不起一个跨几周、几十次迭代的科研项目。
1.1 AI 助手的“金鱼记忆”与上下文窗口限制
聊天式 AI 看起来能记住一整段对话，但它记住的只是当前会话里出现过的内容。窗口有限，聊得越长，前面的细节被“挤掉”的概率就越大。哪怕平台支持超长上下文，很多时候也会因为内容太多，导致它分不清哪些是重点、哪些是闲聊。
这就像你雇了一个能力很强的实习生，但这个实习生的记忆力只能维持半小时。你上午跟他讲完数据在哪个目录、用什么版本，下午再问，他全忘了。你不能怪他笨，只能怪自己没有把关键信息写在工作手册里。AGENTS.md 和 PROJECT.md 就是那个工作手册。
如果你只是临时写一个小脚本，一次对话能搞定，那确实不需要这东西。但科研项目动辄持续几个月，中间要不断改数据、换模型、调参数、更新结果。每一次切换任务，AI 都得重新理解上下文。没有文档，你会发现同样的话说了三遍、五遍，它还是会犯同样的错。
1.2 长期项目的文档断裂和技术债
做科研项目和做软件工程有个相似之处：代码越写越多，知识却越来越分散。你的 README 可能是给合作者看的，写得比较正式；代码注释只针对某一行；实验记录散落在不同文件夹；论文草稿在另一处。这些信息对 AI 来说都是“碎片”，它没法主动把它们拼成一个完整的项目图景。
于是我试过把项目背景一次性全部贴进对话。结果更糟，AI 瞬间被大量细节淹没，开始抓不住重点，回答变得又长又空。问题不在于信息不够，而在于缺少一个“结构化入口”。AGENTS.md 和 PROJECT.md 分别承担了“行为守则”和“项目事实库”这两个角色。前者告诉 AI 该怎么干活，后者告诉 AI 项目到底是什么。
很多人把这两份文件混为一谈，这其实是最大的误区。行为守则和事实库分开写，才能让 AI 在每次交互时优先读取规则，再按需查看事实。一旦混在一起，文件会越写越长，AI 反而不知道该记住什么。
1.3 AGENTS.md 和 PROJECT.md 到底解决什么问题
简单来说，AGENTS.md 回答的是“你该怎么与我协作”，PROJECT.md 回答的是“我们这个项目在做什么、目前进展如何”。一个是流程，一个是内容。
我用一个类比：AGENTS.md 相当于公司的新员工入职手册，写的是行为规范、汇报方式、禁忌事项；PROJECT.md 相当于项目交接文档，写的是项目目标、当前情况、历史决策和待办任务。员工入职第一天，先看手册，知道公司怎么运转；再读交接文档，知道项目做到哪了。AI 也一样。
实际体验中，AGENTS.md 对代码风格的影响最大。比如我会在里面写“修改实验脚本前必须列出改动清单”“涉及数据文件时禁止直接覆盖原文件”。有了这种明确约束，AI 就不敢乱来了。PROJECT.md 则主要解决“它不知道自己在做什么”的问题。我会把核心假设、数据来源、当前尝试方向写进去，AI 提建议时明显更有针对性。
2. 我如何设计两份文件的边界
这里要强调：AGENTS.md 和 PROJECT.md 并不是什么高深概念，它们最初来自一些开源项目里的规范，后来被 AI 编程工具广泛支持。重点是，你不能直接照搬别人的模板，而要结合自己的项目把边界划清楚。
2.1 AGENTS.md 的定位：行为准则和交互协议
AGENTS.md 是写给 AI 看的操作手册。它不需要很长，但每条规则都应该是可执行的。我见过有的 AGENTS.md 写得像讣告，全是空话，比如“请确保代码质量高”“请遵循良好的编程习惯”。这种东西 AI 看了等于没看，因为没法判断什么叫质量高。
我的做法是写具体规则，每条都对应一个实际场景。举个例子：
# AGENTS.md 你是本科研项目的长期协作助手。 ## 工作准则 - 修改任何脚本前，先用最多 5 句话说明你的改动方案。 - 涉及数据处理时，优先使用项目 data/ 目录下的相对路径，不要写绝对路径。 - 文件命名一律使用 snake_case，实验版本号用 YYYYMMDD 格式。 - 删除或覆写文件前，必须先确认备份存在。 - 新增依赖必须写入 environment.yml，并在回复中高亮说明。 - 生成图表时，默认使用项目主题色和 300dpi 导出。你看，规则不需要面面俱到，只需要把你最在意的事写进去。AI 是概率模型，写清楚了，它的输出才能稳定。如果你不写“禁止覆写原文件”，它很可能就在代码里直接df.to_csv('result.csv')把你辛苦处理好的数据覆盖了。
还可以加入一些交互协议，比如“当需求不明确时，列出 3 个可能的假设并询问确认”“当任务超过 30 分钟时，先输出阶段小结”。这些内容听起来不像技术文档，但对长期项目特别有用，因为它让 AI 在一个相对稳定的人机协作节奏里工作。
2.2 PROJECT.md 的定位：项目事实和决策记录
PROJECT.md 更像一个折叠起来的事实库。我会把项目里“不太会频繁变化但仍需要随时查阅”的内容放进去。它不需要记录每一次对话的流水账，只需要记录那些“换了人来看也必须知道”的背景信息。
下面是我习惯的结构：
# PROJECT.md ## 项目目标 一句话说清楚要回答什么问题。 ## 数据说明 - 原始数据位置：data/raw/ - 处理脚本：scripts/preprocess/ - 关键字段：采样时间、实验组别、浓度值 - 缺失值处理约定：数值型用 interpolate，类别型用 "unknown" ## 核心假设 1. 该指标在不同实验组之间服从正态分布。 2. 采样频率对最终结果影响不显著。 ## 关键决策记录 - 2025-03-12：改用滑动平均滤波，原因：原始信号噪声过大。 - 2025-03-20：剔除 3 号样本，原因：记录仪故障。 ## 当前任务 - [ ] 完成特征选择并输出 baseline 结果 - [ ] 更新论文方法部分的数据分析流程我不建议写成论文式的长篇大论。PROJECT.md 的关键是“增删改查”，你可以在每次任务前后花五分钟更新它。最重要的是“当前任务”这一栏。它相当于给 AI 一个进度指针，每次打开文件都知道该从哪个方向帮你。
2.3 一个可以直接抄的模板组合
如果你还不想从零开始，可以用下面这个极简组合。先把 AGENTS.md 控制在 10 条以内，PROJECT.md 控制在 5 个小节。写多了反而没人维护，写少了起不到引导作用。
AGENTS.md - 你是长期参与本科研项目的 AI 助手。 - 先读 PROJECT.md 了解背景，再开始回答。 - 涉及修改代码时必须先给方案。 - 所有路径使用项目相对路径。 - 禁止覆写原始数据。 - 生成实验报告时，包含关键参数、结果文件路径和复现命令。PROJECT.md - 项目目标 - 数据与目录结构 - 核心假设与约定 - 关键决策记录 - 当前任务这套组合的精髓在于，AGENTS.md 告诉 AI “先读 PROJECT.md”，等于给了一个强制读取动作。如果你不写这一条，AI 可能压根不会主动去看项目文档。加了之后，哪怕它每轮对话要消耗一点上下文来读文档，也远比在对话里重新描述全部背景要节省。
3. 从零搭建的完整流程与实操细节
很多人问：我是先写 PROJECT.md 还是先写 AGENTS.md？我的建议是，先写 PROJECT.md，因为事实比规则更基础。如果连项目背景都没整理清楚，空谈行为规范只会变成一张没人看的废纸。
3.1 第一步：用半小时整理项目事实
挑一个没有实验安排的时间，打开项目文件夹，把所有信息集中到一份文档里。你可以从这几个问题开始：
- 这个项目在解决什么问题？
- 数据放在哪里？格式是什么？哪些文件是中间产物，哪些是最终产物？
- 我做过哪些关键决策？原因是什么？
- 接下来最重要的三件事是什么？
这个过程不用追求完美，写一半也行。重点是逼自己把散落的信息结构化。我印象最深的是，有一次我整理 PROJECT.md 时，发现自己对某种缺失值的处理方式根本没说清楚，连自己都快忘了为什么当初选 interpolate 而不是删掉那一行。这就是长期项目的典型问题——大脑会美化记忆，文档不会。
3.2 第二步：把 AGENTS.md 写成你自己的规矩
接下来，回想你平时最想吐槽 AI 的地方。比如“它总是喜欢把代码改成我完全不认识的写法”“它会自作主张改数据范围”“它回答得很长但没重点”。这些都是最好的 AGENTS.md 素材。
我一般会先列出最想解决的 5 个问题，然后针对每个问题写一条规则。比如，我不想让 AI 在未确认的情况下自由安装新包，就写“新增依赖必须写入 environment.yml，并在回复中高亮说明”。这条规则后来帮我省了很多环境冲突的麻烦。
还要注意语气。AGENTS.md 不是写给人类看的温情提示，而是给 AI 的行为约束。用“必须”“禁止”“先……再……”这种祈使句，效果比“请尽量……”好得多。AI 阅读指令时，明确的否定句式比模糊的肯定句式更容易被执行。
3.3 第三步：把文件接入常用的 AI 工作流
不同 AI 工具读取这两份文件的方式并不完全一样。以我常用的编程类 AI 工具为例，它们通常会自动扫描仓库根目录下带特定名称的文件。你需要确认你的工具支持哪些文件名，然后在项目根目录放好即可。
如果你用的是通用对话型 AI，没法自动读文件，也有办法。我的习惯是开场白固定写一句：“请先阅读项目根目录下的 PROJECT.md 和 AGENTS.md，然后我们再讨论任务。”然后把文件内容贴一次。这样至少能让 AI 在当前对话里建立完整上下文。
对于支持 repo 扫描的 AI 编程工具，你甚至可以只写一个很薄的 AGENTS.md，然后在里面加一句“全部项目背景见 PROJECT.md”。这样每次新会话它都会先加载这两份文件，不会漏。实测下来，这种搭配在长期代码维护中的稳定性，比纯靠对话记忆高很多。
3.4 科研场景下还需要扩展什么
科研项目比普通软件项目多三类东西：实验数据、分析脚本、论文产出。这三类东西都需要在文档里说明。比如 PROJECT.md 里要写清楚“实验结果存在 results/ 目录，子目录按日期命名”，这样 AI 生成的代码才会自然地按这个结构存取文件。
另外，建议在 AGENTS.md 里加一条关于“复现性”的规则：“每次提交结果时，必须附上运行该结果所需的命令或脚本路径。”这一条对科研项目特别重要。有一次我让 AI 帮忙处理一批数据，它给了漂亮的图表，但完全没留下生成过程。图表挂进论文的时候，我愣是翻日志翻了半天才确认参数。后来我就在 AGENTS.md 里强制要求所有结果必须带复现命令，再也没出过这种问题。
还可以把论文写作的辅助规则写进去，比如“生成文字内容时，避免使用模糊评价词，改用具体数据和实验结果描述”。你会发现，AI 写初稿的可用率会明显上升。
4. 实际使用中的常见问题、排查思路与避坑技巧
用了大半年 AGENTS.md 和 PROJECT.md 的组合之后，我踩过不少坑，也总结了一些调试心得。这里你可以当做一个“问题速查表”来用。
4.1 常见问题排查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| AI 完全不理会 AGENTS.md 里的规则 | 文件名称不被当前工具识别，或文件放在错误目录 | 确认工具支持的文件名，放在仓库根目录；对话里显式要求它先读取 |
| AI 读了文档但还是答非所问 | PROJECT.md 内容太长或太抽象，AI 抓不住重点 | 精简 PROJECT.md，把最重要的信息放到最前面，用列表和加粗突出 |
| 规则和实际任务冲突 | AGENTS.md 写得太死，导致 AI 卡在规则上 | 增加“如遇冲突，先询问确认”的兜底条款 |
| 文档更新跟不上项目进展 | 更新流程太繁琐，或没有养成习惯 | 固定每天结束前用 5 分钟同步“当前任务”和“关键决策记录” |
| AI 总是读文档导致上下文溢出 | AGENTS.md 和 PROJECT.md 加起来太长 | 控制 AGENTS.md 在 10 条以内，PROJECT.md 不超过 300 行；细节部分可以链接到更细的文档 |
这张表只写了最常见的情况。实际使用中你会发现，大部分问题根本不在文件内容本身，而在使用习惯。我自己最大的教训是：把 PROJECT.md 当成了“写一次就完事”的档案，而不是“每次任务都维护”的活文档。连续两周不更新，AI 就会拿着过时的背景给你提供建议，效果甚至比没有文档更差，因为它会给你一个自信但错误的方案。
4.2 避坑技巧一：规则要具体到能执行
AGENTS.md 里最忌讳的就是“确保代码可靠”“提高分析效率”这种无法衡量的表述。AI 对这些词的理解很模糊，它根本无法验证自己是否做到了。换成“所有输出文件必须包含生成时间戳”“脚本运行结束后打印耗时和显存占用”这类明确指令，效果立刻不一样。
我自己写过一句“不要过度设计”，结果 AI 每次给我重构代码时依然东拉西扯，后来改成“保持现有函数和模块结构，只做必要的修改”，立竿见影。因为前者是评价，后者是动作。
4.3 避坑技巧二：把“为什么”写进决策记录
PROJECT.md 里的“关键决策记录”是所有科研项目最容易被忽略但又最宝贵的部分。AI 无法从最终代码里看出当初为什么选了 A 方案而不是 B 方案。如果你不写原因，过两周你再问它“这个滑动平均窗口为什么取 5”，它只能瞎猜。
我会给每个决策记录加一条“原因”字段，比如：
- 2025-03-20：剔除 3 号样本 原因：记录仪故障导致数据前半段异常，保留会造成基线漂移误判。这一行字看似简单，但在写论文讨论部分的时候帮了我大忙。AI 读完这个记录，能自动理解数据筛选逻辑，而不是对着异常样本一脸茫然。
4.4 避坑技巧三：给文件留一个“动态入口”
AGENTS.md 和 PROJECT.md 本身应该是稳定的，但项目状态是动态的。我最后的建议是，在 PROJECT.md 末尾放一个“最近进展”区域，每一轮任务结束后只更新这一段。这样，AI 每次读取时只需要聚焦到最后的部分，就能快速跟上最新进度。
如果你和团队协作，还可以把这两份文件作为 Git 提交说明的“小抄”。在 AGENTS.md 里写一句“生成提交信息时，参考 PROJECT.md 的关键决策记录”，你会发现 AI 帮你生成的 commit message 很有上下文，而不是空洞的“fix bug”。
最后再分享一点个人体会
我用了很久之后才意识到，AGENTS.md 和 PROJECT.md 表面上是写给 AI 看的，实际上是逼我梳理自己的科研过程。文档越清晰，AI 越聪明，我自己对项目全局的把握也越来越稳。最明显的变化是，我不用再费口舌反复解释背景，AI 也不会因为聊到一半上下文丢失而“失忆”。
如果你还在忍受 AI 一问三不知、答非所问、改代码不打招呼这些老毛病，不妨花一个下午把这两份文件搭起来。我猜你会回来感谢这个习惯的。
