做实验、写代码、整理数据的科研人员应该都体会过这种崩溃一个项目忙了三个月回头再看当初的代码完全想不起某个函数为什么要那么写中途换一台机器或者让师弟接手光是交代“项目到哪一步了”就能讲上一个下午。更麻烦的是现在大家习惯用 AI 辅助写代码、跑分析但 AI 没有记忆每次对话都要重新解释背景效率低不说还经常给出和项目现状脱节的建议。我自己摸索出了一套比较顺手的组合用一份 PROJECT.md 管项目全貌用一份 AGENTS.md 管 AI 的行为规范。前者像项目简报让任何人和任何 AI 都能快速知道“我们在做什么、做到哪了”后者像员工手册告诉 AI “遇到问题该怎么想、该守什么规矩”。两个文件搭配起来长期项目的维护成本能明显降下来。这篇文章就把我踩过的坑、总结出的写法、实际使用中的细节全部摊开讲适合正在用 AI 辅助写实验代码、做数据分析、跑深度学习的同学参考。1. 为什么长期科研项目需要“双文档”架构1.1 长期项目的记忆力难题科研项目的周期通常以月甚至年为单位。一个典型的深度学习实验项目前期要处理数据、写预处理脚本中期设计模型、调参、写训练循环后期做评估、画图、整理结果中间还穿插着各种实验记录和 bug 修复。这个过程中产生的代码量动辄几千行涉及的决策点更是多到数不清。人类的大脑本来就不擅长长期记忆这些琐碎的上下文AI 工具更是如此——大模型的上下文窗口再大也不可能自动记住你上周在终端里跑过的命令更不会知道你某个实验组的随机种子为什么设成 42。我见过很多同学习惯把注释写在代码里或者靠 GitHub commit 记录来复盘。但代码注释表达不了“为什么我放弃了 ResNet 改用 ViT”这类战略决策commit message 也说不清楚“当前跑到的实验进度”。等到项目中期代码里的关键信息散落在 readme、notebook、论文草稿、聊天记录里想找的时候怎么也找不到。AI 辅助编程工具的出现反而放大了这个问题跟 AI 对话的时候它经常因为缺乏上下文而给出“看起来对但实际不合时宜”的代码比如把旧的 API 用法套到新版本库上或者忽略了你已经写好的数据处理逻辑。这就是我引入文档化管理的原始动机。与其依赖 AI 的临时记忆不如主动帮它建立“项目级记忆”。两份 markdown 文件成本极低收益却很稳定。1.2 AGENTS.md 和 PROJECT.md 的分工定位先明确这两个文件各管什么。PROJECT.md 的读者既包括人类也包括 AI它回答的是“项目是什么、目标是什么、现在状态如何、有哪些关键约定”。它是一份动态更新的项目状态说明书类似实验室里的实验记录本但更结构化。AGENTS.md 则几乎完全为 AI 设计它回答的是“你作为这个项目的协作方应该遵循什么规则”。里面可以写代码风格、测试要求、禁止事项、命令用法、文件组织偏好等等。它更像一个 prompt 模板每次 AI 进入项目时自动加载这些规则从而让输出更贴合项目预期。从命名也能看出来PROJECT 是全局视角AGENTS 是行为视角。前者管“事实”后者管“行为”。两者有重叠但侧重点不同组合起来恰好覆盖了长期项目维护的两个维度我知道项目在哪我也知道该怎么做事。1.3 双文档协同的整体逻辑这两个文件不是割裂的它们要互相引用。PROJECT.md 里可以写“代码风格和提交规范见 AGENTS.md”AGENTS.md 里也可以写“当前项目优先级最高的事项见 PROJECT.md 中的『当前状态』部分”。这样设计的好处是AI 读完两个文件后既能把握全局又能知道具体执行时的边界。我用一个比喻来理解这个结构PROJECT.md 是行军地图AGENTS.md 是作战条例。地图告诉你战场在哪、敌人分布、我方兵力部署条例告诉你什么情况下可以开火、弹药怎么管理、俘虏怎么处理。没有地图AI 只能瞎撞没有条例AI 可能用很野蛮的方式完成任务。两样都配齐AI 才像一个靠谱的副官而不是一个莽撞的实习生。2. 手把手搭好你的 PROJECT.md2.1 PROJECT.md 应该包含哪些核心模块不要一上来就长篇大论 PROJECT.md 的价值在于“快速获取关键信息”所以需要精练。我自己的项目里通常包含下面几块项目定位用一两句话说明这个项目要解决什么问题属于哪个研究领域。让阅读者包括未来的你迅速想起背景。核心目录结构列出代码、数据、实验结果、文档分别放在哪里最好配一段注释说明设计逻辑。当前实验状态这是最重要的部分记录正在跑的实验、已经完成的实验、结果摘要、待办事项。最好带上日期方便追踪变化。关键决策记录不用事无巨细只记录影响项目走向的决策比如“为什么选择 AdamW 而不是 Adam”“为什么数据划分采用 stratified split”。这些信息是 AI 和同事理解项目逻辑的钥匙。依赖与环境python 版本、关键库版本、是否需要 GPU、是否需要特殊环境变量。这部分能避免大量“在我的机器上明明能跑”的悲剧。索引链接到更详细的文档如实验日志、论文草稿、PPT。刚开始写的时候不需要面面俱到内容优先格式自然生长。我见过有人一开始就折腾完美的模板结果没写两行就放弃了。先写起来再逐步完善。2.2 一个科研项目 PROJECT.md 的示例框架下面是我给一个典型图像分类实验项目准备的 PROJECT.md 骨架可以直接抄作业# 项目名称基于半监督学习的医学影像分类 ## 项目定位 研究半监督方法在少量标注数据下的分类性能预期发表一篇会议论文。 ## 目录结构 - src/源代码按模块组织 - data/raw/原始数据只读 - data/processed/预处理后数据 - experiments/每个实验一个文件夹包含配置、日志、输出 - docs/详细文档、调研笔记 ## 当前实验状态更新日期XXXX-XX-XX - 实验ABaseline ResNet50 训练完毕Acc 0.812待验证 - 实验BFixMatch 训练中当前 epoch 40/100 - 待办 - [ ] 完成 FixMatch 训练后做超参搜索 - [ ] 对比不同置信度阈值的影响 - [ ] 整理结果图表 ## 关键决策记录 - 使用疑难度图而不是原始图像做增强原因是避免失真。 - 所有实验固定 seed42确保可复现。 ## 依赖与环境 - Python 3.10 - PyTorch 2.1.0CUDA 11.8 - 运行入口python src/train.py --config experiments/xxx.yaml这个框架的核心是“当前实验状态”和“关键决策记录”。前者让 AI 知道代码要接在哪个进度上继续写后者让 AI 知道为什么有些代码长这样避免“好心”帮你重构掉一个关键部分。我在实际使用中AI 看到决策记录后基本不会再把一个设计得很奇怪的“临时方案”改得干干净净——因为它知道那是故意留下的 workaround。2.3 更新节奏与版本管理技巧PROJECT.md 最忌讳的就是写完之后再也不动。我的习惯是每天开始工作前花两分钟浏览一下结束时花五分钟更新“当前实验状态”。实验跑完一个阶段、决定换一个方向的时候立刻在“关键决策记录”里追加一条顺手标上日期。这个习惯听起来很简单但坚持下来项目复盘会非常舒服。如果你想更严谨可以把 PROJECT.md 纳入 git 版本管理提交信息尽量语义化比如“更新实验结果FixMatch 达到 0.835”。这样后面想看项目演进过程直接翻项目文档的 commit 历史就行。我自己的做法是连实验配置文件也做成带版本的快照这样 PROJECT.md 里引用的内容和代码库中的实际状态严格对应。3. 把 AGENTS.md 做成 AI 的操作手册3.1 AGENTS.md 是给 AI 看的“员工守则”如果说 PROJECT.md 是项目地图那么 AGENTS.md 就是给 AI 员工写的上岗培训材料。每个 AI 工具在进入项目目录时如果能读到 AGENTS.md就会把这个文件的内容作为默认上下文的一部分。不同工具的实现细节不一样但思路一致通过一个项目文件传递 AI 需要遵守的规范。为什么要单独给 AI 写守则因为有太多人类默认“不用讲”的常识AI 并不了解。比如人知道“src 目录下的代码不要乱动”AI 如果不被告知可能会在你让它修 bug 时顺手改掉另一个模块的接口。人知道“测试数据不能用”AI 可能为了凑指标无意中把测试集信息泄露到训练过程里。写清楚规则相当于给 AI 划了一条安全线减少不必要的返工。3.2 编写 AGENTS.md 的关键规则我总结了几条特别实用的编写原则指令要具体不要抽象。比起“请写高质量代码”不如写“所有函数必须包含类型注解和 docstring公共函数必须说明输入输出”。AI 对具体指令的执行效果远好于抽象要求。明确优先级。如果遇到规则冲突听谁的可以写明“当 PROJECT.md 中的『当前状态』与新需求冲突时先基于当前状态向用户确认”。这样避免 AI 盲目执行矛盾指令。给出“禁止”事项。AI 倾向满足用户提问即使要求不合理。你可以在 AGENTS.md 里写“禁止修改 experiments 文件夹下的历史实验结果”“禁止删除任何数据文件”。保持精简。AGENTS.md 过长会导致 AI 抓不住重点。通常 30 行以内比较合适只关心高频的、影响大的规则。定期复盘。跟项目演进一样AGENTS.md 也要跟着团队习惯和工具变化更新。每次发现自己需要反复纠正 AI 同一种错误时就把那条规则补进去。3.3 针对科研场景的 AGENTS.md 示例下面这个示例我实际用在几个科研项目上你可以根据自己的场景调整# AGENTS.md ## 角色与目标 - 你是本科研项目的 AI 协作助手目标是根据项目当前状态提供代码、建议和排查帮助。 - 所有建议必须参考 PROJECT.md 中的项目定位和实验进度。 ## 通用规范 - 代码风格遵循 PEP8函数必须带类型注解和 docstring。 - 不要在 src/ 中直接修改已有接口。如需修改先说明影响范围。 - 训练脚本支持通过 yaml 配置参数新增参数需加到对应默认配置。 - 每次修改代码后同步检查是否需要在 PROJECT.md 中更新说明。 ## 实验相关 - 所有实验固定 seed42禁止在未确认的情况下修改。 - 禁止使用测试集数据做训练或验证调参。 - 生成实验报告时必须同时汇报训练 loss、验证指标和可复现命令。 - 不要删除或覆盖 experiments/ 下的历史结果。 ## 对话行为 - 当用户询问不明确时先追问清楚需求再给出方案。 - 涉及数据敏感操作如删除、覆盖前必须二次确认。 - 建议优先使用项目内已有的函数和工具类减少重复造轮子。光看内容可能觉得平淡但实际效果非常明显。我用了一个月后AI 给出的代码很少有“顺手改了别的模块”的情况写实验脚本时也懂得从configs/里读参数而不是把超参数硬编码在代码里。4. 双文档在实际工作流中怎么配合4.1 典型工作流从想法到实验再到论文配合 AI 做科研的完整流程我大致分成三个阶段每个阶段双文档的侧重点都不同。第一阶段是项目启动。这个阶段 PROJECT.md 内容最少但必须把“项目定位”和“核心目录结构”写好。我通常会让 AI 根据我的想法生成初始的项目结构和基础实验框架顺便生成一份 PROJECT.md 初稿。AI 生成了初稿之后我再手工删改把它整理成符合自己习惯的版本。为什么不自个儿从零写因为启动阶段最缺的是框架思路AI 能提供比较全面的目录建议省掉很多从空白开始的犹豫。第二阶段是实验迭代。这是双文档价值最大的阶段。每次开始新的实验我在 PROJECT.md 的“当前实验状态”里写清楚本次要跑什么然后把指令发给 AI“在src/train.py中加入一个新模型参考已有实验的配置种子固定为 42。”AI 读取 AGENTS.md 的规则后会按照项目规范写代码并且不会乱动其他部分。实验跑完我再把结果更新进 PROJECT.mdAI 下次就能基于这个新状态继续工作。整个过程形成闭环文档越积越厚但项目的复杂度不增反降。第三阶段是总结和写论文。这个阶段 PROJECT.md 里的“当前实验状态”和“关键决策记录”直接变成论文相关章节的素材。我会让 AI 阅读 PROJECT.md 并生成实验汇总表再根据汇总表写方法描述。因为决策记录里写了大量“为什么这样做”论文的 related work 和 ablation study 部分会顺畅很多。AGENTS.md 在这里继续发挥约束作用比如汇报结果时必须带日志路径这样论文中的每个数据都可追溯。4.2 如何让 AI 遵守文档约定光有文档还不够还要保证 AI 真的会去读。我在实践中积累了三个有效手段。首先把文档放在项目根目录。绝大多数 AI 工具会自动加载根目录下的 AGENTS.md如果你的工具支持自定义最好在系统提示里加上“请首先阅读根目录的 PROJECT.md 和 AGENTS.md”。我在使用 Cursor、Claude Code 时都会在项目初始化时进行首次对话让 AI 确认自己已读文档并简要复述项目要点相当于给 AI 做一个“入职考试”确认它能准确理解规则。其次对话中主动引用文档。当 AI 给的方案偏离轨迹时我会直接问它“你看到 PROJECT.md 里『当前实验状态』了吗那里面说明当前实验用的 batch size 是 64你刚才推荐的 128 是基于什么”这样不仅纠正了 AI也是在训练它更重视文档。最后把关键规则做成强制奇点。比如在 AGENTS.md 里写“如果 PROJECT.md 中未提及某配置先询问用户而不是猜测。”这个规则能让 AI 不太会自作主张。实战中一旦发现 AI 频繁猜测我都会把对应场景写进“禁止/必须”列表几次迭代后AI 的表现会稳定很多。4.3 配合工具使用的实用技巧我主要用的 AI 工具是 Cursor 和 Claude Code两个工具对 AGENTS.md 的处理方式稍有不同但搭配起来都不错。在 Cursor 里注意让项目根目录的 AGENTS.md 保持精简因为 IDE 类的工具还会读取 .cursorrules 等文件如果规则太多AI 可能无所适从。我更倾向于在 AGENTS.md 里写全局规则在子目录里放局部的 .cursorrules比如src/目录主要管代码风格docs/目录主要管文档写作格式。这种分层方式更适合大型项目。Claude Code 会自动加载根目录的 AGENTS.md并且也支持在子目录里放局部版本。我一般只用根目录版因为科研项目规模不大全局规则足够。如果项目里包含多个独立子项目比如一个数据处理子项目和一个模型训练子项目我会在子项目目录里各放一份简化版 AGENTS.md只写与该子项目相关的规则然后让根目录版引用它们。使用过程中还有个细节AI 对文档的读取并不总是在每次对话开始时重新加载。如果你修改了 AGENTS.md 或 PROJECT.md最好在对话里主动提醒 AI “文档已更新请重新阅读”。比如我会说“我先更新了 PROJECT.md 里的实验状态你再看看”。这样避免 AI 使用旧上下文。5. 常见问题与避坑实录5.1 AGENTS.md 越写越长该怎么办几乎每个人都会遇到这个问题。AGENTS.md 写得太短约束不够写得太长AI 抓不到重点。我现在的做法是分级维护根目录的 AGENTS.md 只放全局性规则字数控制在 40 行以内细节规则放在子模块的局部文件中或者写成单独的规范文档在 AGENTS.md 里用一行链接指引 AI。比如“所有关于数据增强的细节请参考 docs/data-augmentation.md”。这样做既保持精简又保留了可扩展的深度。另外定期清理过时规则也很重要。项目初期可能要求 AI“每次提交代码前运行所有测试”但后来测试脚本变得很重这个要求已经不现实。如果不删掉AI 每次都会尝试浪费大量时间。我的习惯是每个月花十分钟全文读一遍 AGENTS.md一条一条问自己“这条我还需要吗”不需要的立刻删。5.2 文档和代码不同步怎么办文档不同步是所有文档策略的最大杀手。我记得有一次 PROJECT.md 里写着“当前使用 ResNet50”但代码库已经改成了 ViTAI 基于旧文档给我生成了 ResNet50 的优化建议浪费了半天才排查出来。解决这个问题靠纪律而不是工具。我自己的规矩是代码一变更就顺手在 PROJECT.md 的“当前状态”里改动一行每天收工前做一次“文档巡检”把新增的模块、改动的接口记录进去。如果你觉得自己纪律性不够可以把“在修改代码后更新相关文档”写成 AGENTS.md 里的强制要求然后让 AI 每次对话之前帮你检查“代码与 PROJECT.md 是否一致”。AI 最怕的就是项目状态描述不准所以它自己也会主动保持文档同步。5.3 不同 AI 工具对文档的读取差异如果你同时用多个 AI 工具要注意它们对 AGENTS.md 的读取规则并不完全相同。有的工具自动加载根目录的 AGENTS.md有的需要你手动在系统提示中引用有的支持多文档嵌入有的只认固定文件名。在我使用过程中Claude Code 对 AGENTS.md 的支持最直接Cursor 则需要结合 .cursorrules 使用。一个稳妥的做法是在 AI 工具的全局设置里写上一句固定指令“每次你必须先检查项目根目录是否存在 PROJECT.md 和 AGENTS.md如果存在先阅读它们再回答。”这样不管工具本身怎样你的要求都能生效。如果工具支持 rules 或 memory 功能也可以把两个文档的路径写入其中。5.4 几个值得保留的实践经验踩过不少坑之后我总结了几条随时能用的经验。第一PROJECT.md 里的日期是你的朋友。每次更新实验状态时记得写日期哪怕只是“更新了 xx 实验的结果”。否则过一段时间你会分不清两个版本的结果哪个是最新的。第二关键决策记录要敢写“不好听”的原因。比如“这个模型我用了很奇怪的数据增强因为当时实验发现普通增强不收敛虽然理论解释还不清楚但先留着。”这种记录对未来自己或 AI 的帮助远大于只写技术方案。第三用 AI 帮你生成 AGENTS.md 初稿是可行的但最终打磨要自己完成。因为 AI 不知道你真正的痛点在哪儿它生成的规则可能很全面但不切要害。你只需要把过去一周里反复纠正过 AI 的同类错误列出来提炼成规则即可。第四不要指望这些文档能替代实验记录。它们更像是“结构化摘要”详细的过程、日志、原因分析还是要记录在实验笔记或日志文件里。PROJECT.md 只需要保留“接下来怎么办”和“为什么这么办”就够了过度编码同样会让项目变得沉重。这套双文档策略本质上是给长期科研项目建立一套轻量级的外部记忆系统。有了它AI 不再每次都是“新人”项目也不会因为时间拉长而变得一团乱麻。我目前维护的三个项目都用这个模式个人感觉精力节省最明显的地方是每次切换任务时的“上下文重建”成本大幅降低。如果你也正在被中长期项目的上下文问题困扰不妨按这个思路搭一下再根据自己的习惯微调。试过之后会发现维护文档的速度比想象中快得多而它给你省下来的时间远超投入。
