1. 科研场景下 AI Agent 的真实困境1.1 从“能跑通”到“能复现”之间的鸿沟我接触 AI Agent 辅助科研这件事最早是从跑通一个文献综述的小流程开始的。当时用 Codex 和 Claude Code 分别试了一遍让 Agent 帮我读一批论文摘要、提取方法段落、归类到预设的标签体系里。第一次跑完结果相当漂亮我甚至觉得这套东西可以立刻推广给组里所有人用。但第二次换了一台机器、换了一个项目目录同样的指令丢进去Agent 给出的分类标准完全变了提取的字段也少了两三个。那一刻我才意识到问题不在模型能力而在于我从来没有把“这个任务到底要怎么做”写清楚过。科研工作和普通脚本任务最大的区别在于科研任务的可复现性要求极高。你今天让 Agent 按某种规则筛了一批文献明天合作者要接着做后天审稿人问你这个筛选标准是怎么定的你都得能说清楚。如果所有规则都只存在于你上一次对话的上下文里那这套流程就是一次性的换个人、换个时间、换个 Agent 工具结果就对不上。这不是 Agent 不行是我们没有给它一个稳定的“任务说明书”。1.2 为什么上下文窗口解决不了这个问题很多人第一反应是那就把要求写详细一点塞进对话里不就行了。我一开始也是这么干的把筛选标准、字段定义、输出格式全部写在一段超长的 prompt 里每次开新会话就粘贴一遍。短期看确实有效但很快暴露出三个问题。第一上下文窗口是消耗品。你把两千字的任务说明塞进去Agent 真正能用来处理论文内容的“注意力预算”就被压缩了。尤其是处理长文档时前面塞的规则越多后面越容易“忘记”或者“选择性执行”。第二规则会漂移。同一个 prompt 在不同会话里Agent 的理解可能微妙地不同。你今天说“方法段落要包含实验设置”它可能理解为包含数据集名称明天同样的表述它可能只提取了模型结构。这种漂移在单次任务里不明显但积累到几十篇文献的规模分类体系就乱了。第三协作时无法交接。你把 prompt 发给合作者合作者复制粘贴时可能漏掉一段或者用的 Agent 版本不同对同一段话的解析不一样。更麻烦的是如果合作者想在你基础上改一条规则他改在哪里改完怎么同步给你没有载体全靠聊天记录迟早出事。1.3 PROJECT.md 出现的必然性正是在这种反复踩坑的过程中我逐渐意识到Agent 辅助科研需要的不是更长的 prompt而是一个独立于对话之外、可版本管理、可协作编辑的任务定义文件。这个文件要放在项目根目录下Agent 每次启动时自动读取人类协作者也能直接打开看、直接改。它不依赖某一次对话的上下文也不绑定某一个具体的 Agent 工具。这就是 PROJECT.md 的定位。它和 AGENTS.md 是同一类思路的产物——用 Markdown 文件给 Agent 提供项目级的上下文。但 PROJECT.md 更偏向“科研项目”这个场景它要描述的不只是代码规范还包括数据来源、字段定义、筛选标准、输出格式、复现步骤。你可以把它理解成一份写给 Agent 看的“实验操作手册”同时也是写给合作者看的“项目说明书”。一份文件两个读者这是它最核心的价值。2. PROJECT.md 到底该写什么2.1 最小可用结构五个必填区块我试过很多版 PROJECT.md 的写法从最初只有三行字到后来膨胀到几千字最后稳定在一个相对精简的结构上。对于科研项目我认为有五个区块是必须有的缺一个都会在后续使用中出问题。第一块是项目目标。用两三句话说明这个项目要解决什么问题、产出什么。不要写“研究 AI 在科研中的应用”这种空话要具体到“从 200 篇摘要中提取方法名称、数据集、评价指标输出为结构化表格”。Agent 读到这句话才知道自己要做的是信息抽取而不是文献综述。第二块是数据说明。数据放在哪个目录、什么格式、编码是什么、有没有缺失值、字段分隔符是什么。科研数据往往来源杂有的是 CSV有的是 JSON有的是从 PDF 转出来的文本。如果不写清楚Agent 可能用错解析方式把制表符当空格处理结果全乱。第三块是任务规则。这是最核心的部分要写清楚“怎么做”。比如筛选文献时纳入标准是什么、排除标准是什么、遇到边界情况怎么处理。规则要写成可执行的判断逻辑而不是模糊的描述。“相关性高”这种词 Agent 没法执行“标题或摘要中出现至少两个预设关键词”才是可执行的。第四块是输出格式。输出文件叫什么、放在哪里、有哪些列、每列的类型和取值范围。最好给一个示例行。Agent 对格式的理解很依赖示例你给一个具体的行比写十句描述都管用。第五块是复现步骤。从干净环境开始按顺序列出要执行的操作。这一步是给合作者看的也是给未来的自己看的。写的时候假设读者完全不了解这个项目每一步都要能独立执行。2.2 规则怎么写才不会被 Agent 误解这是我在实操中踩坑最多的地方。Agent 不是人它对自然语言的理解有很强的“补全倾向”——你写得不完整它会自己脑补而且不同工具脑补的方向还不一样。所以规则部分要尽量消除歧义。我总结了几条经验。能用数字就不用形容词。“提取前三个关键词”比“提取主要关键词”稳得多。能枚举就不要概括。“数据集名称包括 SQuAD、GLUE、SuperGLUE”比“常见 NLP 数据集”可靠。能写判断条件就不要写主观评价。“如果摘要中同时出现‘准确率’和‘提升’两个词则标记为性能类”比“判断是否与性能相关”可执行。另外规则之间要有优先级。科研场景里经常遇到一条记录同时符合纳入和排除标准的情况。这时候必须明确排除优先还是纳入优先边界情况归到哪一类这些不写清楚Agent 每次遇到都会随机选一个结果就不稳定。2.3 和 AGENTS.md 的分工AGENTS.md 和 PROJECT.md 经常被放在一起讨论我的做法是让它们各管一摊。AGENTS.md 管“怎么干活”——代码风格、提交规范、测试要求、工具链配置。PROJECT.md 管“干什么活”——项目目标、数据、任务规则、输出格式。两者有重叠的地方比如都涉及目录结构但侧重点不同。实际使用中我会在 PROJECT.md 开头写一句“本项目的通用开发规范见 AGENTS.md”然后在 AGENTS.md 里写“具体任务定义见 PROJECT.md”。这样 Agent 读到任何一个文件都知道另一个文件的存在需要时会去读。两个文件都放在项目根目录版本管理一起走改任务规则改 PROJECT.md改工具配置改 AGENTS.md职责清晰。注意不要让两个文件的内容互相矛盾。我遇到过 PROJECT.md 里写“输出 CSV”AGENTS.md 里写“输出 JSON”的情况Agent 直接卡住不动了。定稿前一定要交叉检查一遍。3. 实操从零搭建一个科研 Agent 工作流3.1 环境准备与工具选型我目前的主力组合是 Claude Code 做交互式任务Codex 做批量处理。Claude Code 的优势在于对长上下文的理解比较稳适合处理需要反复推敲的规则类任务Codex 在批量执行和文件操作上更顺手适合跑那种“读一百个文件、写一个汇总表”的活。两者都支持读取项目根目录下的 Markdown 文件作为上下文这是 PROJECT.md 能生效的前提。安装方面Claude Code 和 Codex 都有各自的桌面版和命令行版本。我建议科研场景用命令行版本因为要配合脚本做批处理图形界面反而碍事。安装完成后第一件事是在项目根目录建两个空文件PROJECT.md和AGENTS.md。不用急着写内容先把框架搭起来。目录结构我习惯这样组织data/放原始数据output/放 Agent 产出的结果scripts/放辅助脚本docs/放项目文档。PROJECT.md 和 AGENTS.md 放在根目录和data/、output/平级。这样 Agent 启动时工作目录就是项目根目录相对路径不容易出错。3.2 写第一版 PROJECT.md 的完整过程我拿一个真实的文献筛选任务来演示。假设要从一批摘要中筛选出与“大模型推理优化”相关的条目并提取方法名称和评价指标。第一步写项目目标。我写的是“从data/abstracts.csv中筛选与大模型推理优化相关的摘要提取方法名称和评价指标输出到output/screened.csv。”这句话包含了输入、处理、输出三个要素Agent 读完就知道边界在哪。第二步写数据说明。我打开 CSV 看了一眼确认编码是 UTF-8分隔符是逗号有id、title、abstract三列没有缺失值。然后写“数据文件为 UTF-8 编码的 CSV逗号分隔包含 id、title、abstract 三列无缺失值。摘要字段可能包含换行符解析时需注意。”第三步写任务规则。这是最花时间的部分。我先列纳入标准“标题或摘要中出现‘推理’且出现‘优化’‘加速’‘压缩’‘量化’‘蒸馏’中任意一个词。”再列排除标准“纯理论分析不涉及具体方法的排除仅提及推理但未涉及优化手段的排除。”然后写边界处理“如果摘要同时符合纳入和排除标准以排除为准。”最后写提取规则“方法名称取摘要中第一个出现的模型或技术名称评价指标取摘要中出现的所有指标名称用分号分隔。”第四步写输出格式。我定义了三列id、method、metrics。给了一个示例行001,FlashAttention,吞吐量;延迟。并注明“输出为 UTF-8 CSV逗号分隔首行为表头”。第五步写复现步骤。我写了四条安装依赖、确认数据文件存在、运行 Agent 指令、检查输出行数。每条都具体到可执行。写完这五块PROJECT.md 大概八百字。不算长但信息密度足够。我把它提交到 Git打了一个 tag方便后续对比修改。3.3 让 Agent 真正读取并执行文件写好了接下来是让 Agent 用起来。Claude Code 和 Codex 的读取方式略有不同但核心逻辑一样在项目根目录启动Agent 会自动扫描根目录下的 Markdown 文件。如果没自动读可以在指令里明确说“请先阅读 PROJECT.md然后按其中的规则执行任务”。我实测下来Claude Code 对 PROJECT.md 的遵循度比较高尤其是规则部分写得具体的时候。Codex 在批量处理时更稳但偶尔会“偷懒”——比如输出格式里写了三列它可能只输出两列。这时候不要急着改 PROJECT.md先检查是不是规则里有歧义。我遇到过一次输出格式写的是“id, method, metrics”但任务规则里没明确说 metrics 用分号分隔Codex 就用了逗号导致 CSV 列数对不上。把分隔符规则补进任务规则后问题就解决了。还有一个细节Agent 读取文件时对 Markdown 的标题层级不敏感但对列表和代码块敏感。所以规则部分尽量用有序列表输出格式用代码块包起来Agent 解析起来更准。3.4 版本管理与协作交接PROJECT.md 最大的好处之一就是可以进 Git。每次改规则都提交一次写清楚改了什么、为什么改。合作者拉下来看到的就是最新版规则。如果合作者想改他改完提交我 review 后再合并。整个过程和代码协作一模一样。我还会在 PROJECT.md 末尾加一个“变更记录”区块用表格记录每次修改的日期、修改人、修改内容。这个习惯是从代码项目里带过来的用在科研项目上同样有效。审稿人问“你的筛选标准有没有变过”直接翻变更记录就行。交接的时候我把整个项目目录打包发给合作者里面包含 PROJECT.md、AGENTS.md、data/、scripts/。合作者装好 Agent 工具在根目录启动读一遍 PROJECT.md就能复现我的流程。不需要我额外解释也不需要他猜。4. 踩坑记录与排查手册4.1 Agent 不读 PROJECT.md 怎么办这是最常见的问题。表现是Agent 启动后直接开始干活完全无视 PROJECT.md 里的规则。原因通常有三个。一是启动目录不对。Agent 只在当前工作目录及子目录里找 Markdown 文件。如果你在data/目录下启动它就读不到根目录的 PROJECT.md。解决办法很简单始终在项目根目录启动。二是文件名不对。有些 Agent 工具对文件名有约定比如只认AGENTS.md或CLAUDE.md。PROJECT.md 是我自己的命名习惯如果你的工具不认可以在指令里明确指定“请阅读 PROJECT.md”。或者建一个软链接把 PROJECT.md 链接到工具认的文件名上。三是文件内容格式有问题。Agent 解析 Markdown 时如果标题层级混乱、列表嵌套过深可能解析失败。我建议 PROJECT.md 只用两级标题列表不超过两层嵌套代码块用标准的三反引号。排查顺序先确认启动目录再确认文件名最后检查文件内容。三步走完基本能定位。4.2 规则执行不一致的排查思路同一个 PROJECT.md两次运行结果不一样这是最让人头疼的。我的排查思路是先看差异在哪再定位是规则问题还是 Agent 问题。如果差异集中在某一类记录上大概率是规则有歧义。比如“提取主要方法名称”Agent 第一次取了第一个第二次取了最长的那个。这时候要把规则改具体“提取摘要中第一个出现的、以大写字母开头的技术名称。”如果差异是随机的每次都不一样可能是 Agent 的随机性导致的。Claude Code 和 Codex 都有一定的随机性尤其是温度参数没调的时候。解决办法是在 PROJECT.md 里加一句“输出必须确定相同输入必须产生相同输出”并在指令里要求 Agent 不要引入随机选择。如果差异是格式层面的比如列顺序变了、分隔符变了那基本是输出格式定义不够明确。把示例行写进去格式问题会少很多。4.3 常见问题速查表问题现象可能原因排查方法解决措施Agent 完全无视 PROJECT.md启动目录错误检查当前工作目录在项目根目录启动Agent 读到了但规则没执行规则有歧义对比两次输出差异把规则改成可执行判断输出格式不对格式定义不明确检查输出文件列数补充示例行和分隔符说明两次运行结果不同Agent 随机性重复运行三次对比加确定性要求调低随机参数协作时结果对不上版本不一致对比 PROJECT.md 哈希统一 Git 版本后再运行Agent 卡住不动文件间规则矛盾交叉检查两个 md 文件消除矛盾表述4.4 几个让我少走弯路的实操心得心得一PROJECT.md 不要写太长。我一开始写了两千多字结果 Agent 读到后面就“忘”了前面的规则。后来压缩到八百字左右遵循度明显提升。科研任务的定义不需要面面俱到把核心规则和边界情况写清楚就够了。心得二规则要写成“如果……则……”的形式。这种条件句 Agent 解析起来最准。我现在的 PROJECT.md 里任务规则部分几乎全是条件句执行稳定性比之前用描述性语言高了一个档次。心得三每次改完 PROJECT.md先跑一个小样本验证。不要直接跑全量数据。我习惯从data/里抽十条记录跑一遍确认输出符合预期再跑全量。这样改错的成本很低。心得四把 Agent 的输出和 PROJECT.md 一起提交。这样任何时候都能回溯当时用的什么规则、产出了什么结果。审稿人问起来直接给 commit hash。心得五不同 Agent 工具用同一份 PROJECT.md但可以微调指令。Claude Code 和 Codex 对同一份 PROJECT.md 的理解有细微差别我会在指令里针对性地补一句。比如对 Codex 说“严格按 PROJECT.md 的输出格式执行不要自行调整列顺序”。这套东西我用了大半年从最初的单机实验到现在组里三个人共用一份 PROJECT.md最大的感受是Agent 辅助科研的瓶颈从来不是模型能力而是任务定义的清晰度。PROJECT.md 就是把“清晰度”固化下来的载体。它不复杂但缺了它整个流程就是沙上建塔。
