你有没有遇到过这种情况AI Agent 刚帮你跑完一轮数据清洗转头问它下一阶段的特征筛选思路它却好像完全失忆又从头问你一遍字段含义和文件路径。我前前后后被这种问题折磨了小半年才慢慢意识到问题不在模型能力而在我的工作方式——我把 Agent 当成了聊天对象而不是当成一个需要持续汇报、持续交接的协作者。后来我开始用一份项目文档 PROJECT.md 管理所有跨会话上下文整个科研辅助流程才算真正有了骨架。这篇文章就聊一聊我为什么坚持用 PROJECT.md以及怎么把它从零到一搭起来。适合正在用 AI Agent 做科研、写代码、做分析的人尤其是被“说完就忘”问题折腾过的人。1. 为什么 AI Agent 需要一份项目文档1.1 上下文窗口不是记忆是临时工作台很多人误以为 LLM 的上下文窗口变大就等于模型有了记忆。这个理解是我踩坑的根源。上下文窗口本质上是你给模型搭的一张临时工作台上面能摆多少张纸视窗口大小而定但只要会话一关、窗口一清桌上的东西全都没了。科研任务往往是长周期、多阶段、强依赖历史结论的昨天确认过的数据版本、上周定下来的评估口径、上次实验失败的教训这些东西如果只存在于聊天记录里那每次新开会话就是一次彻底的“失忆”重来。还有一个更隐蔽的问题叫“上下文淹没”。当会话里堆了几百条历史消息模型实际能稳定利用的信息反而会下降尤其是中间部分的细节容易被忽略。哪怕你用的模型上下文再大让它在海量闲聊记录里准确找出“我上个月说过数据源在 /data/raw_v2”也是不大靠谱的。科研里面一个字段名写错整条分析链就歪了这种风险不能靠运气。1.2 PROJECT.md 到底是什么简单说PROJECT.md 是一份长期维护、结构化、面向 Agent 的项目事实清单。它不像 README 那样只介绍项目是什么也不像论文笔记那样只记录文献观点它的核心定位是“当前这个科研项目的事实快照”项目目标、数据描述、已确认的方法约定、运行命令、验证标准、已知的坑、下一步计划全部写在一份 Markdown 文件里。我把它理解成给临时工准备的工作交接手册。你雇了一个很聪明但对项目一无所知的新助手他每次上班都忘记之前的一切但你给了他一本手册里面把关键背景、流程、约定、禁忌写得清清楚楚。他每次上手前翻一下手册就能快速进入状态。这个类比虽然朴素但非常准确。模型不会主动记住你上周说了什么但它非常擅长按照清晰文档的指示来行事。1.3 哪些场景最离不开它我从实际项目里总结了几类必须上 PROJECT.md 的场景。第一类是多阶段长周期任务比如一个从数据收集、清洗、建模到论文写作的完整课题中间跨越几周甚至几个月每次和 Agent 交互的目标都不一样。第二类是跨会话协作后一次会话要复用前一次会话的结论比如昨天做过特征重要性分析今天要基于这个结果做模型调参。第三类是多个 Agent 并行参与同一个项目一个处理数据、一个写代码、一个整理文献如果没有统一事实来源每个 Agent 都会给出自己的“正确版本”最后对不上号。我自己的转折点发生在一次分子构效关系预测的小项目上。最开始我每次会话都要重新讲一遍数据集字段、目标变量含义、试过的模型清单、当前的痛点光是这个重复解释的开销就占掉了大量时间。有一天我实在受不了花了半小时把实验记录整理成 PROJECT.md第二天让 Agent 读了一遍之后它主动提了一句“按照文档记录上轮已经确认 RandomForest 在这个任务上过拟合严重我不再重复试它了”。那一刻我就知道这条路走对了。2. PROJECT.md 的写作结构这样写Agent 才看得懂2.1 我一直在用的核心章节框架这份文档不是随便写写就可以的结构设计直接决定 Agent 能不能快速定位关键信息。我用过好几版结构最终沉淀下来一套比较稳的框架分享出来供参考。章节核心内容解决的问题项目目标研究问题、核心假设、成功标准防止 Agent 在细枝末节里跑偏当前状态当前进度、正在做的事、阻塞项让新会话快速接续不需要从零解读数据说明数据路径、字段定义、单位、已知问题避免每次重新解释字段含义方法与协议模型选择理由、固定参数、评估口径保证跨会话方法一致性命令清单跑通全流程的脚本入口让 Agent 直接给出可执行命令验证与复盘已完成实验记录、结论、对比让 Agent 基于历史结论而不是重复试错坑与教训数据坑、方法论坑、Agent 坑防止同样的错误反复发生下一步计划最近要完成的任务给 Agent 明确优先级每个章节都有明确的消费对象。比如“当前状态”是给下一次会话看的“验证与复盘”是给 Agent 提供决策依据的“坑与教训”是给所有后续环节做风险提示的。整份文档的核心逻辑是把你脑子里的隐性知识显性化让模型不必猜测直接读取。2.2 写文档的三个核心原则第一个原则是写“事实”不写“想法”。文档里写的每一句话都应该是当前已确认的信息不要写“我觉得可能”“也许应该试试”这类模糊表述。模糊表述对模型来说是灾难它会把它当作事实参与推理。我自己的做法是只有验证过的东西才写进文档新想法一律记录到单独的“想法暂存区”或者在会话里讨论不混入事实层。第二个原则是写“行为指令”不写“状态描述”。“数据集中有缺失值”是状态描述Agent 看了只知道有这个情况。“缺失值对应字段为 age 和 income目前策略是删除缺失比例超过 30% 的字段其余用中位数填充此结论经交叉验证确认”才是行为指令Agent 看完就知道下一步怎么处理。状态描述给人看可以给模型看效率太低。第三个原则是保持“可引用性”。给章节编号对关键结论打上日期标记比如“2026-05-12 确认LR 基线 AUC 0.71特征标准化后 0.74提升显著”。这样在和 Agent 对话时可以直接引用具体条目它也能在回答时准确指向文档里的事实来源方便我自己复查。2.3 篇幅控制与模块拆分PROJECT.md 不是越长越好。我刚开始写过一份 3000 多字的超级文档结果发现 Agent 虽然能读但在回答问题时经常被次要信息干扰反而不如一份精简的文档效果好。后来我学会了分层控制PROJECT.md 只放稳定、全局的事实大约 800 到 1200 字那些临时的、细节性的信息放进单独的模块文档里比如 DATA.md、EXPERIMENTS.md按需引用。这就像一个知识库的分层缓存顶层的 PROJECT.md 是高频访问的全局信息底层的模块文档是低频访问的细节信息。Agent 每次会话只需要把顶层文档吃透遇到具体任务时再按命令去查对应的模块这样既不会上下文爆炸也不会信息缺漏。3. 从 0 到 1 搭建自己的 PROJECT.md 配置3.1 初始化模板先跑起来再说很多人在开始之前会纠结“写什么、写多细、用什么工具管理”其实不用想那么多先拿一份模板就用起来用两三天你就会知道自己项目里最常被重复问的信息是什么再针对性地调整结构。我目前的初始化模板长下面这样你可以直接复制改。# PROJECT.md ## 1. 项目目标 - 研究问题一句话说清楚 - 核心假设我们假设什么成立 - 成功标准什么指标达到多少算完成 ## 2. 当前状态 - 阶段数据收集 / 预处理 / 建模 / 验证 / 写作 - 正在做的事当前聚焦任务 - 阻塞项当前卡住的点以及需要的帮助 ## 3. 数据说明 - 数据源路径、来源、版本 - 关键字段字段名、含义、单位 - 已知问题缺失、异常、清洗策略 ## 4. 方法与协议 - 方法选择用了什么模型为什么选它 - 固定协议随机种子、数据划分、评估指标 - 命令清单完整跑通流程的脚本入口 ## 5. 验证与复盘 - 已完成实验日期、变更内容、结果、结论 - 对比表每次实验之间的差异和效果变化 ## 6. 坑与教训 - 数据坑哪些字段容易出错 - 方法论坑哪些判断需要谨慎 - Agent 坑Agent 犯过的错下次如何规避 ## 7. 下一步计划 - 近期任务按优先级排列 - 需要 Agent 协助的具体事项这套模板最大的优点是“每一条都有明确消费场景”。你自己写的时候只要觉得某条信息在多次会话里被反复给 Agent 解释过就值得写进文档。反过来哪些信息从没被用到过下次更新时就删掉。3.2 让 Agent 真正“认识” PROJECT.md 的三种方式文档写好只是第一步让 Agent 每次都知道去读它才是关键。我在实践里试过三种方式效果各有不同。第一种是在系统提示词里强制规定。把工作流程写进 System Prompt每次会话开始先阅读项目目录下的 PROJECT.md涉及数据、方法、结论的讨论必须引用文档中已确认的事实如果发现文档信息和当前对话冲突先停下来向用户确认任务结束时输出“文档更新建议”小节。这种方式适用于绕不开 Model 提供的固定行为设置的场景稳定、零额外成本。第二种是在工具调用环节动态注入。如果项目引入了工具调用机制可以定义一个 read_project_doc 函数让 Agent 根据任务需要主动读取特定章节。这种方式更灵活适合模块文档比较多的情况避免每次全量读入造成的上下文浪费。第三种是“人肉粘贴”最笨但最有效。重要任务开始前我直接把 PROJECT.md 的关键章节粘贴进对话作为任务上下文的一部分同时在对话开头说“以下为项目当前事实请基于此完成后续任务”。这种方式等于把事实直接摆在模型面前完全不存在它“想不想读”的问题。对于每一次性的关键任务我基本都用这个方案。3.3 迭代维护文档救不了懒人PROJECT.md 最忌讳的是“写一次就不再更新”。模型帮你完成了任务、得出了新结论如果你不把结论同步回文档下次会话依旧会失忆。我一般会遵循一个比较轻量的维护节奏每次会话结束时多花三分钟让 Agent 自己输出“本次会话产生的关键变更”小结我再确认后合并进文档。这样可以保证文档跟着项目走不至于变成一份过时的历史档案。每个周末我还会做一次系统性的文档复盘把这一周跑过的实验、踩过的坑、做出过的决定记录进对应章节清理掉那些没被实际消费过的内容。项目进入新阶段时比如从数据预处理切到建模我会主动修订“当前状态”和“下一步计划”确保新阶段开始时有全新的事实基础。3.4 我的一次完整实操回顾拿我最近的文本分类项目举例。项目开始时我照着模板建好了 PROJECT.md数据说明、方法协议、命令清单都是提前填好的。第一天我让 Agent 做数据探索它在看完文档后直接给出了数据概况还主动提到“文档里写了 label 分布不均衡建议先看一下是否需要分层采样”省去了我重复解释的功夫。第三天做特征工程时我新开会话、贴上“验证与复盘”章节Agent 基于上一轮已确认的统计特征实验结论直接跳过了低效的特征组合稳当地进入了下一轮筛选。整个过程中 PROJECT.md 就像一条贯穿项目的记忆线把每次会话的成果沉淀下来Agent 站在历史实验的肩膀上干活重复试错的次数明显减少。4. 我在实际使用中踩过的坑4.1 Agent 不读文档怎么办最让人抓狂的问题莫过于文档写好了它就是不读。后来我分析下来原因无非两种一种是我没在系统提示词里做强制规定它觉得多读一步是多余操作另一种是文档太长它对“在读文档”这个动作产生了路径依赖上的取巧。解决办法很粗暴把“请先阅读 PROJECT.md”直接写进任务描述的首句并附上文档路径。绑定工具的情况下可以在工具描述里明确写“该项目的事实来源见 PROJECT.md回答任何项目问题前必须调用此工具”。4.2 文档太长导致上下文爆炸怎么办当文档超过 1500 字以后全量注入开始变得不划算会挤占实际任务处理的空间。我的解法是双层结构PROJECT.md 只放最核心的全局信息详细实验记录移到 EXPERIMENTS.md数据细节移到 DATA.md让 Agent 通过按需读取的方式访问。还有一个备用方案是“摘要轮换”每次会话只贴上一轮的会话摘要而不是全部原始对话这样能把上下文占用压到很低但代价是会丢掉一些细节适合不太复杂的流程。4.3 Agent 理解出现偏差怎么纠正Agent 在读取文档后经常表现出的问题有两个。一个是过度泛化文档里写了“年龄字段有缺失”它可以推演成“所有字段都有缺失”导致后续处理完全跑偏。另一个是无视边界条件文档写了“AUC 提升显著”它可能理解为“可以结束调参了”实际上那只是在某个特定数据子集上提升显著。面对这种偏差我现在会在“坑与教训”章节专门写边界条件和禁忌比如“注意上述高于 0.75 的 AUC 仅限在标准化处理后的验证集上有效未经标准化处理的数据不具备此结论”并在提示词里要求 Agent 在引用实验结论时同时引用其适用条件。4.4 高频问题排查速查表症状可能原因解决方法Agent 回答与项目背景无关提示词未要求阅读文档在系统提示词或任务描述首句强制要求引用的信息是旧的文档未同步最新结论每次会话结束后更新文档回答时忽略约束条件文档里没写边界条件在结论后写出适用条件和已知限制对话上下文过长、处理变慢全量注入太长的文档采用分层模块化文档按需读取Agent 拒绝基于文档回答文档路径不对或格式混乱检查路径精简格式确保章节编号清晰5. 从个人科研到团队协作PROJECT.md 的扩展思路5.1 多 Agent 协作时的“共享黑板”当项目复杂到需要多个 Agent 分工时PROJECT.md 的价值会进一步放大。比如一个 Agent 做数据清洗一个写建模代码一个管文献归纳如果它们各聊各的最后拼起来很容易对不上。我现在的方法是让它们共同维护同一份 PROJECT.md数据 Agent 更新“数据说明”建模 Agent 更新“验证与复盘”文献 Agent 更新“方法选择”的背景补充。通过这一份共享事实源所有 Agent 虽然在物理上是隔离的但在逻辑上共享同一套上下文。那感觉就像几个协作者共用一块黑板各自把自己干完的事贴上去其他人不用再反复问“你那边现在什么进度”。5.2 和 Git、CI 流程配合起来PROJECT.md 放在项目的 Git 仓库里效果会更好。每次更新会留下 diff 记录这本身就是一份项目演进日志。过去我在调试一个数据版本问题的时候就是靠回看 PROJECT.md 的历史 diff精确找到“数据版本切换”是在哪一次更新里发生的才定位到根因。更进一步的话可以在 CI 流程里加一个校验任务检查 PROJECT.md 的格式和完整性防止团队协作时有人忘记更新关键章节。研发团队维护的项目知识库也可以基于这个思路搭建流水线。5.3 给新手的几个建议如果你刚开始接触这个思路我有几条实在的建议。第一不要追求一步到位的完美文档先写一份 500 字的粗糙版用起来再迭代。第二每次和 Agent 的会话结束时逼自己回答一句“刚才这次对话有哪条结论值得写进文档”哪怕只有一个字段定义积少成多。第三别把文档写得像自嗨笔记每一条信息都要站在“未来的 Agent 读到这句话后能做出什么正确决策”的角度来写写不下去的时候问自己这句话值不值得模型读取。我在实际使用中还有个体会PROJECT.md 表面上是写给 Agent 看的其实是逼着我自己把一个模糊的科研想法逐步变成清晰、结构化、可执行的事实。这个过程带来的认知提升可能比 AI Agent 的辅助本身更有价值。每次更新文档我都对项目的理解更深一层到写论文或技术报告的时候整份文档几乎可以直接当素材库用。最后再分享一个小技巧每次更新文档都走 Git diff让 Agent 帮你审一遍“本次更新有没有引入和文档原结论冲突的表述”。这相当于给文档加了二道复核尤其适合那些长期项目——多一道检查就少一次翻车。这套方法我已经用了大半年项目越复杂越能体会到它的好处。