1. 从一次科研翻车说起为什么我开始给 AI Agent 写项目文档去年冬天我在做一个材料计算方向的文献复现项目。当时手头同时开着三个 AI Agent 会话一个用 Codex 帮我重构数据清洗脚本一个用 Claude Code 帮我梳理实验流程还有一个在跑文献摘要的批量提取。三个会话各自跑得挺欢直到某天晚上我发现——数据清洗脚本里用的字段命名和实验流程文档里定义的完全对不上。一个叫sample_id一个叫specimen_no还有一个干脆用了material_key。三个 Agent 各自为政谁也没错但合在一起就是一团乱麻。那天我花了整整四个小时做人工对齐。四个小时够我跑完一轮完整的 DFT 计算了。这件事之后我开始认真思考一个问题我们花大量时间研究怎么搭 AI Agent、怎么调 prompt、怎么接模型却很少花时间研究怎么让 Agent 理解这个项目到底是什么。Agent 的能力再强如果它不知道你的项目结构、命名规范、数据流向、约束条件它就只能靠猜。而猜在科研场景里是致命的。于是我开始在项目根目录放一个PROJECT.md。一开始只是随手记几行项目说明后来越写越细逐渐变成了一套完整的项目上下文协议。现在我的每个科研项目根目录下都有这个文件Agent 一进来先读它读完再干活。效果立竿见影命名冲突没了重复解释没了跨会话的上下文断裂也基本消失了。这篇文章就是把我这套做法完整拆开讲清楚。不管你是刚接触 AI Agent 的新手还是已经在用 Codex、Claude Code 做开发的老手只要你的项目需要多个 Agent 协作、或者需要 Agent 在多次会话之间保持一致性这套方法都能直接抄作业。我会讲清楚PROJECT.md到底该写什么、为什么这么写、怎么和AGENTS.md配合、以及我在实操中踩过的那些坑。2. 先搞清楚AI Agent、LLM、AI 模型到底差在哪2.1 三层概念的生活化拆解很多人一上来就混淆这几个词导致后面配置 Agent 的时候概念对不上。我用一个做菜的类比来讲AI 模型比如 DeepSeek、GPT 系列、Claude 系列就像一本菜谱。它知道怎么做菜知识都在里面但它自己不会动。你问它红烧肉怎么做它能给你写出完整步骤但它不会去开火。LLMLarge Language Model大语言模型是 AI 模型里专门处理语言的那一类。DeepSeek 属于 LLMClaude 属于 LLMGPT 也属于 LLM。它们擅长理解和生成文本但本质上还是菜谱——你问它答你不问它不动。AI Agent则是那个真正下厨的厨师。它手里拿着菜谱LLM但它还会去冰箱拿食材调用工具、尝味道执行代码看结果、根据味道调整多轮迭代、最后端菜上桌输出成果。Agent 的核心特征是自主性和工具使用能力——它能自己决定下一步做什么而不是等你一步步指令。所以当你听到Codex 接入 DeepSeek这种说法时意思是用 DeepSeek 这个 LLM 作为 Codex 这个 Agent 的大脑。Codex 负责决策和工具调用DeepSeek 负责语言理解和生成。两者是协作关系不是同一个东西。2.2 为什么这个区分对写 PROJECT.md 很重要理解了这个分层你就能明白PROJECT.md到底在解决哪一层的问题。LLM 那一层你控制不了太多——模型的能力是固定的你只能通过 prompt 影响它。Agent 那一层你能控制它的工具、它的循环逻辑、它的终止条件。但项目上下文这一层是你可以完全掌控的而且它同时影响 LLM 的理解和 Agent 的决策。PROJECT.md就是项目上下文层的核心载体。它不改变模型能力也不改变 Agent 架构但它改变了 Agent看到什么。Agent 看到的信息越结构化、越准确它的决策质量就越高。这就像给厨师一张清晰的厨房布局图——食材在哪、调料在哪、哪些锅不能用一目了然做菜效率自然高。2.3 常见 Agent 产品的能力边界目前科研场景里用得比较多的 Agent 产品我按使用频率排一下Agent 产品核心优势典型科研用途对 PROJECT.md 的依赖度Claude Code长上下文、代码理解强重构脚本、梳理流程高Codex代码生成快、工具调用灵活批量数据处理、自动化高通用对话 Agent上手快、门槛低文献摘要、思路整理中自建 Agent完全可控、可定制特定流程自动化极高依赖度越高说明这个 Agent 越需要项目上下文才能发挥价值。自建 Agent 依赖度最高因为它没有预设的领域知识全靠你喂。Claude Code 和 Codex 虽然有一些通用能力但在科研这种高度专业化的场景里没有PROJECT.md照样抓瞎。3. PROJECT.md 的整体设计思路它不是 README 的替代品3.1 为什么 README 不够用很多人第一反应是我不是已经有 README 了吗问题在于README 是写给人看的PROJECT.md是写给Agent看的。这两者的信息需求完全不同。README 通常包含项目简介、安装步骤、使用示例、贡献指南。这些对人有用但对 Agent 来说太粗了。Agent 需要知道的是这个项目的目录结构长什么样、每个目录放什么、命名规范是什么、哪些文件不能动、数据从哪来到哪去、当前处于什么阶段。举个具体例子。README 里可能写运行python main.py启动项目。但 Agent 需要知道的是main.py依赖哪些环境变量、输出写到哪个目录、如果报错先检查什么、有没有已知的坑。这些信息 README 不会写因为人可以通过试错解决但 Agent 试错成本很高——它可能跑偏很远才回来。3.2 PROJECT.md 的四个核心作用我总结下来PROJECT.md在科研项目里承担四个作用第一定义边界。告诉 Agent 哪些能动、哪些不能动。科研项目里经常有原始数据、中间结果、最终成果三层Agent 如果不知道边界可能把原始数据覆盖了那就出大事了。第二统一语言。科研项目涉及大量专业术语和自定义命名。PROJECT.md里定义好术语表和命名规范Agent 就不会各说各话。第三传递状态。项目进行到哪一步了、当前在解决什么问题、下一步计划是什么。Agent 知道这些才能给出有针对性的建议而不是从头开始问。第四约束行为。明确告诉 Agent 什么不能做。比如不要修改raw_data/下的任何文件、生成代码必须带类型注解、所有输出必须用 UTF-8 编码。这些约束能避免大量返工。3.3 和 AGENTS.md 的分工这里要特别说一下AGENTS.md。这两个文件经常被混淆其实分工很明确PROJECT.md描述的是项目本身——这个项目是什么、结构如何、规范如何。它是相对静态的项目不变它就不怎么变。AGENTS.md描述的是Agent 的工作方式——你希望 Agent 怎么干活、用什么风格、遵循什么流程。它是相对动态的你可以针对不同任务调整。打个比方PROJECT.md是厨房布局图AGENTS.md是菜谱。布局图告诉你厨房有什么、东西放哪菜谱告诉你今天做什么菜、按什么步骤做。两者配合Agent 才能既知道环境又知道任务。我通常的做法是PROJECT.md放在项目根目录所有 Agent 共享AGENTS.md可以放在根目录也可以放在子目录针对特定任务定制。如果项目简单一个PROJECT.md就够了如果项目复杂、任务多样两个都上。4. PROJECT.md 的核心内容模块与写法4.1 项目概览让 Agent 三秒进入状态开头部分要极其精炼让 Agent 快速建立认知。我通常写三段第一段一句话说清楚项目做什么。比如本项目复现 XX 材料在不同温度下的热导率计算使用 VASP 和 LAMMPS 双引擎交叉验证。第二段说清楚当前阶段。比如当前处于数据预处理阶段已完成 60% 的原始数据清洗下一步进入计算参数标定。第三段说清楚关键约束。比如所有计算必须在集群上运行本地只做数据处理和结果分析。这三段加起来不超过 200 字但 Agent 读完就能知道我在做什么、做到哪了、有什么限制。这比让它自己翻文件猜要高效得多。注意项目概览不要写太长。我见过有人把项目背景写了 2000 字Agent 读完前面忘了后面。概览就是概览细节放到后面的模块里。4.2 目录结构给 Agent 一张地图这是PROJECT.md里最实用的部分。我通常用代码块画一棵目录树然后在每个关键目录后面加注释project_root/ ├── raw_data/ # 原始数据只读禁止修改 ├── processed_data/ # 清洗后的数据可读写 ├── scripts/ # 所有脚本按功能分子目录 │ ├── preprocessing/ # 数据预处理脚本 │ ├── calculation/ # 计算相关脚本 │ └── analysis/ # 结果分析脚本 ├── results/ # 计算结果输出按日期分子目录 ├── docs/ # 文档包括本文件 └── PROJECT.md # 项目上下文文件这棵树看起来简单但信息量很大。Agent 一看就知道原始数据不能碰、脚本按功能分类、结果按日期组织。没有这棵树Agent 可能把脚本扔到根目录或者把结果写到raw_data/里那就麻烦了。我还会在树后面补一段说明解释几个容易混淆的目录。比如processed_data/和results/的区别前者是清洗后的输入数据后者是计算产生的输出数据不要混用。4.3 命名规范统一语言的关键科研项目里命名混乱是常态。同一样东西有人叫sample有人叫specimen有人叫material。Agent 如果不知道统一规范就会跟着乱。我在PROJECT.md里会明确写样本 ID 统一用S加三位数字如S001、S012温度参数统一用T加数值加单位如T300K、T500K文件命名统一用下划线分隔全小写如sample_s001_clean.csv变量命名统一用蛇形命名法如sample_id、temperature_k这些规范看起来琐碎但能省掉大量对齐成本。我实测下来有了命名规范之后Agent 生成的代码和文档一致性提升了非常多基本不需要人工修正命名。提示命名规范要写具体例子不要只写规则。Agent 对例子的理解比对规则的理解更准确。比如用蛇形命名法不如用sample_id这种格式不要用sampleId或SampleID。4.4 数据流向让 Agent 知道数据从哪来到哪去科研项目的数据流通常比较复杂原始数据经过清洗变成中间数据中间数据经过计算变成结果数据结果数据经过分析变成图表。Agent 如果不知道这个流向可能在中途插一脚把流程打乱。我会用一段文字加一个简单的列表来描述raw_data/下的原始文件由实验设备导出只读scripts/preprocessing/下的脚本读取原始文件输出到processed_data/scripts/calculation/下的脚本读取processed_data/输出到results/scripts/analysis/下的脚本读取results/生成图表到results/figures/这样 Agent 就知道要改数据先改预处理脚本要看结果去results/要加分析写新脚本放analysis/。每个环节的输入输出都清清楚楚。4.5 当前状态与待办让 Agent 接得上手这部分是动态更新的我通常每周更新一次。内容包括当前正在解决的问题已经尝试过的方案和结果下一步计划已知的阻塞点比如当前正在标定计算参数已尝试ENCUT400和ENCUT500前者结果偏差 3%后者偏差 1.5%下一步尝试ENCUT600。阻塞点集群队列排队时间较长单次计算等待约 2 小时。Agent 读到这些就能直接接着干而不是从头问你做到哪了。这在跨会话场景里特别有用——今天用 Codex 跑了一半明天换 Claude Code 继续只要PROJECT.md更新了新 Agent 就能无缝接手。5. 实操从零搭建一套 PROJECT.md 工作流5.1 第一步初始化项目结构假设你刚拿到一批实验数据准备开始一个科研项目。先别急着写代码先把目录结构搭好mkdir -p project_root/{raw_data,processed_data,scripts/{preprocessing,calculation,analysis},results,docs} touch project_root/PROJECT.md然后把原始数据放进raw_data/确保它是只读的chmod -R 444 project_root/raw_data/这一步很关键。Agent 有时候会好心帮你修改原始数据如果你没设只读它可能真的改了。设了只读之后它想改也改不了只能来问你。5.2 第二步写第一版 PROJECT.md第一版不用写太细把四个核心模块填上就行项目概览、目录结构、命名规范、数据流向。我通常花 15 分钟写第一版后面根据实际使用情况逐步补充。写的时候有个技巧假设 Agent 是一个刚入职的实习生。它聪明、能干但对你的项目一无所知。你要告诉它什么才能让它第一天就能干活按这个标准写基本不会漏。5.3 第三步配置 Agent 读取 PROJECT.md不同 Agent 的配置方式不一样。以 Claude Code 为例你可以在项目根目录放一个.claude/目录里面配置上下文文件路径。Codex 则可以通过项目配置文件指定上下文。通用做法是在 Agent 的启动配置里把PROJECT.md加入上下文加载列表。这样每次 Agent 启动都会先读这个文件。如果你用的是自建 Agent那更简单——在系统 prompt 里直接引用PROJECT.md的内容或者让 Agent 启动时先调用文件读取工具读它。注意不要让 Agent 每次都全文读取PROJECT.md。如果文件很长可以拆成多个文件按需加载。比如PROJECT.md只放概览和目录结构详细规范放到docs/naming_conventions.mdAgent 需要时再读。5.4 第四步和 AGENTS.md 配合使用AGENTS.md我通常写这几块Agent 的角色定位比如你是一个科研数据助手专注于数据清洗和计算脚本编写工作流程比如先读 PROJECT.md再检查当前状态然后提出方案等我确认后再执行输出规范比如所有代码必须带注释所有输出必须说明依据禁止事项比如不要修改 raw_data/不要删除任何文件不要跳过确认步骤PROJECT.md和AGENTS.md配合起来Agent 就既有环境认知又有行为约束干活就靠谱多了。5.5 第五步迭代优化第一版写完不是结束而是开始。每次 Agent 犯错你就想是不是PROJECT.md里没写清楚如果是就补上。这样迭代几轮PROJECT.md会越来越完善Agent 的错误率会越来越低。我自己的PROJECT.md从第一版到现在改了大概 20 多次。每次改动都对应一个实际踩过的坑。比如有一次 Agent 把结果写到了processed_data/里我就在数据流向里加了一句结果数据只能写到 results/禁止写到 processed_data/。之后再没犯过。6. 常见问题与排查技巧实录6.1 Agent 不读 PROJECT.md 怎么办这是最常见的问题。原因通常有三个一是配置没生效二是文件路径不对三是 Agent 的上下文窗口满了读不进去。排查顺序先确认配置文件里路径写对了再确认文件确实存在且可读最后检查 Agent 的上下文使用情况。如果上下文满了就精简PROJECT.md或者拆成多个文件按需加载。我遇到过一次配置都对但 Agent 就是不读。后来发现是文件编码问题——PROJECT.md存成了 GBKAgent 按 UTF-8 读读出来是乱码就跳过了。改成 UTF-8 之后正常。6.2 Agent 读了但理解偏了有时候 Agent 确实读了但理解和你预期不一样。这通常是表述问题。比如你写结果写到 results/Agent 可能理解成结果可以写到 results/ 也可以写到别处。改成结果只能写到 results/禁止写到其他目录就明确了。我的经验是约束性表述要用只能、禁止、必须这类强词不要用建议、最好、可以这类弱词。Agent 对强词的遵循度明显更高。6.3 多个 Agent 之间上下文不一致这是跨会话协作的经典问题。Agent A 改了PROJECT.mdAgent B 还在用旧版本。解决办法是把PROJECT.md纳入版本控制每次修改都提交Agent 启动时先拉最新版本。如果做不到版本控制至少要在PROJECT.md里加一个最后更新时间字段Agent 启动时检查这个时间如果太旧就提醒你更新。6.4 PROJECT.md 写多长合适我的经验值是 500 到 1500 字。太短了信息不够太长了 Agent 读不完或者读了后面忘前面。如果确实需要更多信息就拆文件。拆文件的逻辑是按使用频率拆高频信息放PROJECT.md低频信息放docs/下的子文件。Agent 每次必读PROJECT.md需要时再读子文件。6.5 常见问题速查表问题现象可能原因排查方法解决方式Agent 不读文件配置错误/路径错误/编码错误检查配置、路径、编码修正配置统一 UTF-8Agent 理解偏差表述模糊检查是否用了弱词改用强约束词跨会话不一致文件未同步检查更新时间纳入版本控制读不完文件过长检查字数拆分文件读了没用信息太泛检查是否具体补充具体例子6.6 几个我踩过的坑坑一把 PROJECT.md 写成了日记。一开始我什么都往里写包括每天的进展、遇到的问题、临时想法。结果文件越来越长Agent 读起来效率很低。后来我把日记部分拆出去PROJECT.md只保留结构化信息效果好多了。坑二忘了更新。有次项目阶段变了我忘了更新PROJECT.mdAgent 还在按旧阶段干活白跑了一轮。后来我养成了习惯每次项目阶段变化第一件事就是更新PROJECT.md。坑三规范写得太死。有次我写所有文件必须用 CSV 格式结果后来需要存 JSONAgent 就卡住了。规范要留余地写默认用 CSV特殊需求可协商。坑四忽略了 Agent 的反馈。Agent 有时候会问PROJECT.md 里没写 XX我该怎么处理这其实是它在提醒你补充。我一开始忽略这些反馈后来发现这些正是PROJECT.md需要完善的地方。7. 进阶让 PROJECT.md 成为科研协作的中枢7.1 和版本控制结合把PROJECT.md纳入 Git 管理每次修改都有记录。这样不仅能追溯变更还能让多个 Agent 通过 Git 同步上下文。我现在的做法是PROJECT.md和代码一起提交commit message 里注明更新项目上下文。7.2 和自动化流程结合如果你用 Jenkins 之类的工具做自动化可以在流水线里加一步检查PROJECT.md是否存在、是否更新。如果项目阶段变了但PROJECT.md没更新就报警提醒。7.3 多项目场景下的管理如果你同时跑多个项目每个项目一个PROJECT.md。Agent 切换项目时先读对应项目的PROJECT.md。我通常会在 Agent 配置里加一个项目切换命令一键加载对应上下文。7.4 团队协作场景如果是团队项目PROJECT.md就是团队共识的载体。每个人都可以补充但要有审核机制。我建议指定一个人负责维护其他人提修改建议。这样能保证文件的一致性和准确性。8. 我个人的几点体会这套方法我用了大半年最大的感受是AI Agent 的能力上限很大程度上取决于你给它的上下文质量。同样的 Agent喂饱了上下文和饿着肚子干活效果天差地别。PROJECT.md看起来只是个文档但它实际上是人和 Agent 之间的接口。你把这个接口定义得越清晰Agent 就越能发挥价值。反过来如果你指望 Agent 自己猜那它猜错的概率远大于猜对。还有一个体会是写 PROJECT.md 的过程其实也是梳理自己项目思路的过程。很多时候我以为自己想清楚了一写才发现有漏洞。这个文件逼着我把项目结构、命名规范、数据流向都想明白对项目本身也是好事。最后分享一个小技巧如果你不知道怎么开始写就先让 Agent 帮你写一版。你告诉它项目大概情况让它生成PROJECT.md初稿然后你在它基础上改。这样起步快而且 Agent 写的版本往往更符合它自己的阅读习惯。