如果你也试过让 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 一问三不知、答非所问、改代码不打招呼这些老毛病不妨花一个下午把这两份文件搭起来。我猜你会回来感谢这个习惯的。