PROJECT.md：给AI Agent一份稳定的项目记忆

我最近养成了一个习惯：不管接手什么科研项目，第一件事不是跑代码，不是读论文，而是先把项目的所有关键信息写进一个叫 PROJECT.md 的文件里。然后，在我用 AI Agent 辅助干活的时候，让它先把这份文档完整读一遍。说实话，这个习惯改变了我对 AI 辅助科研的整个体验。

之前的一段时间里，我对 AI Agent 的印象很矛盾。一方面，它确实能帮我写代码、解释概念、整理文献；另一方面，它在多轮对话里经常“失忆”，有时候会一本正经地编造不存在的实验参数，甚至把 A 项目的结论嫁接到 B 项目上。直到我搞清楚了背后的原因——LLM 的上下文窗口是有限的，模型不会自动记住你上个礼拜聊了什么——我才意识到，问题不在模型，在我没有给它一套稳定的“项目记忆”。这也是 PROJECT.md 出现的原因。

如果你正在用 AI 辅助科研、写论文、做实验，或者正在搞 AI Agent 开发，这篇内容可以帮你省掉不少弯路。我会讲清楚为什么一份项目文档能显著提升 Agent 的可用性，以及我踩过哪些坑、最后是怎么把文档和 Agent 组织起来的。

1. 科研场景下 AI Agent 的“失忆”和“幻觉”，都源于上下文窗口有限

1.1 一个真实的翻车现场

举个我自己遇到的例子。当时我在做一个关于数据清洗的实验，先跟 AI 聊了两轮，确定了数据集是某个传感器日志，时间字段的格式是 ISO 8601，单位是毫秒。然后我让它写一段数据异常的检测逻辑，结果它给出的代码里，默认时间字段是 Unix 时间戳，单位是秒。我质问它：刚才不是说了毫秒吗？它的回复很礼貌：抱歉，我记错了。

这种“记错”不是偶然。很多人在用 AI 做科研时都遇到过：明明已经交代过的背景，它转头就忘；明明告诉过它某些术语的定义，它还是会按照自己的理解来。原因很简单：多轮对话中，模型能看到的 token 数量是有限的。当对话越来越长，早期的信息会被截断或者被压缩，模型只能“凭感觉”补全。这时候你看到的“AI 记错了”，本质上不是态度问题，而是技术机制问题。

1.2 上下文窗口的物理限制

这里要稍微解释一下 token 的概念。LLM 处理文本时不是按词，而是按 token 切分。一个 token 大约对应半个到一个汉字，或者四分之三个英文单词。不同模型窗口大小不同，从几万 token 到上百万 token 都有。但即便窗口再大，也存在两个问题：第一，塞满之后，模型在生成时对后续内容的注意力会下降；第二，成本会随 token 数量暴涨。

所以，指望靠“加大窗口”来解决 Agent 的记性问题，并不现实。更务实的做法，是把最重要的信息放在一个固定的地方，每次对话开始时主动喂给模型。这个固定的地方，就是项目管理里的 PROJECT.md。

1.3 幻觉的根源：信息缺口

再说幻觉。很多人以为幻觉是模型“撒谎”，其实更接近的比喻是：一个读过万卷书但不知道你实验细节的助手，在信息缺失时，会用他最顺手的知识来填补空白。比如它不知道你的样本量是多少，就会给你一个“常见的”样本量；不知道你的采样频率，就会假设成 1 Hz。这些假设从语言上看很流畅，所以容易被当作真话。

PROJECT.md 解决的就是这个信息缺口。把项目目标、数据格式、术语表、当前进度、已知限制全部写清楚，模型就不需要猜了。它不是让模型变得更聪明，而是让模型少一些“自由发挥”的空间。这个思路，其实跟带新人是一个道理。你不可能指望一个新同事心里有你过去三个月的所有决策，但如果你给他一份写清楚的 handbook，他上手的速度会快得多。

1.4 外置记忆 + 事实锚点

本质上，PROJECT.md 是给 Agent 的一份“外置记忆”。人和 Agent 协作时，最稳定的默契是：所有关于项目的事实，都以文档为准。每次会话开始前，我会让 Agent 读一遍 PROJECT.md；每次项目有重大变化，我会更新 PROJECT.md并保留历史版本。这样一来，无论开了多少次会话，Agent 都能快速进入状态。

我对这个机制的定位是“事实锚点”。模型可以对世界有无数种理解，但一旦某个事实被明确写进项目文档，它在回答时就有了可以引用的依据。研究越往后走，越会发现“你能让 AI 依据什么来工作”比“AI 本身多强”更重要。

2. PROJECT.md 不是 README：我如何组织这份“Agent 项目说明书”

2.1 为什么 README 不够

很多开源项目都有 README，但它一般是写给人类维护者看的，重点在“怎么跑起来”。而 PROJECT.md 是写给 AI 和人类共同看的“上下文手册”，重点在“这个项目的关键知识是什么”。两者的目标完全不同。

我见过不少人直接把 README 改名成 PROJECT.md 丢给 Agent，效果很一般。因为 README 里大多是安装步骤、命令行参数，而 Agent 做科研辅助时需要的是：目标、术语、数据字典、实验状态、结论记录。所以 PROJECT.md 需要为“喂给 LLM”这个场景重新设计。

2.2 PROJECT.md 和 README 的核心区别

这张表基本解释了我为什么单独维护一个 PROJECT.md，而不是在 README 里顺手补一段。因为用途完全不同，放一起会导致“人类觉得啰嗦，AI 觉得不够”。

2.3 五段式结构模板

我实践下来觉得比较好用的结构是五段式：

1. 项目目标：用两三句话说清楚要解决什么问题、成功的标准是什么。
2. 术语表：项目里所有不能被“常识”替代的定义。
3. 关键约束：包括数据格式、硬件限制、必须遵守的规范。
4. 当前状态：实验进行到哪一步，哪些结论已验证，哪些还在尝试。
5. 下一步计划：接下来最需要 AI 协助的事项。

五段里面，术语表和当前状态最重要。术语表可以减少模型的曲解；当前状态可以避免模型把过期结论当最新结论。

下面是一个完整示例，你可以直接抄：

# PROJECT.md ## 项目目标 研究某传感器在不同环境温湿度下的测量漂移，建立校正模型。 成功标准：校正后 RMSE 降低 30% 以上。 ## 术语表 - **测量漂移**：在相同输入下，传感器的输出随使用时间缓慢偏移的现象。 - **RMSE**：均方根误差，本项目中特指校正后残差的标准差。 ## 关键约束 - 数据来源：data/raw/*.csv - 时间格式：ISO 8601，单位毫秒 - 采样率：统一重采样到 1 Hz - 硬件限制：本地单卡 24G 显存 ## 当前状态 - 已完成：数据清洗管道 v1 - 进行中：特征工程，重点关注温度梯度特征 - 已验证：线性校正模型在恒温条件下的有效性 - 待验证：温度梯度与漂移之间的非线性关系 ## 下一步计划 - 完成特征工程，跑 baseline 模型 - 对比多项式校正与分段线性校正 - 优先请 AI 协助检查特征提取代码的边界条件

这个文档看起来平平无奇，但给到 Agent 之后，效果非常明显。比如你问“帮我检查一下训练代码”，它首先会看数据格式约束对不对，再看时间字段单位对不对，而不是凭直觉写一段通用代码。

2.4 写作技巧：让 LLM 更容易“读出”关键信息

有了模板，还需要注意表达方式。我总结了几条经验：

• 用短句，少用嵌套修饰。模型在长句上的理解能力虽然不差，但短句更不容易产生歧义。
• 尽量用精确数字替代模糊描述。“样本量 12,000 条”比“样本量很大”有用得多。
• 对每个术语给显式定义，哪怕你觉得“这还用说吗”。
• 把最重要的内容放前面。LLM 对文档开头和结尾的关注度通常高于中部。
• 避免使用“大概”“差不多”“可能”这类词汇写在约束部分。约束一模糊，模型就会自己补一个“大概”。

这些技巧基本都是“金字塔原理”的变体：结论先行，细节后补。和人类阅读习惯很相近，所以 PROJECT.md 同时对人和 AI 都很友好。我常跟人开玩笑，写 PROJECT.md 最好的标准是：让一个第一天来实习的人看了能干活，让一个 AI 看了不乱编。

3. 从 PROJECT.md 到能干活的项目 Agent：一套可以照搬的搭建流程

3.1 先分清：Agent、LLM、AI 模型到底是什么关系

在讲搭建流程之前，必须先花一分钟把概念理清楚。很多刚接触的人会把 AI Agent 和 LLM 混为一谈，比如问“DeepSeek 是 Agent 还是模型”。答案很明确：DeepSeek 属于 LLM，也就是大语言模型，它本身不是 Agent。AI Agent 是一个更大的概念，通常由“模型 + 规划 + 记忆 + 工具”组成。模型是大脑，Agent 是把大脑接到手脚和记忆上的系统。

用一张表来看会更直观：

所以，当你说“我要搭建一个 AI Agent”时，你做的事情其实是：选一个 LLM 作为核心，再在它外面包上任务规划、项目管理文档、工具调用这些环节。PROJECT.md 在这里扮演的角色，就是 Agent 的记忆层——它不参与计算，但决定了 Agent 的“世界观”。

3.2 最小可用架构

基于 PROJECT.md 的科研 Agent，最简化的架构是这样的：

• 系统 Prompt：告诉 Agent 它的角色、工作方式、输出要求。
• PROJECT.md：项目的静态事实源，每次会话开始加载。
• 工具调用：比如读文件、执行 Python 脚本、查文献数据库等。
• 工作日志：每次交互的记录，用于多轮会话之间的衔接。

这里我特别强调“工作日志”要和 PROJECT.md 分开。PROJECT.md 是经过整理的稳定信息，工作日志是临时记录。两者混在一起会让文档膨胀。日志是流水账，缓存；PROJECT.md 是索引，主干。别混。

3.3 实操：如何跑通一个能阅读 PROJECT.md 的科研 Agent

因为我自己经常用 Python 做实验，所以第一个版本是用简单脚本控制的：每次对话前先读 PROJECT.md，拼到系统提示词后面，再发给 LLM。这个做法不依赖任何复杂框架，半天就能跑通。用 DeepSeek 的 API 来做示例的话，核心逻辑大概是：

import os from openai import OpenAI client = OpenAI( api_key=os.getenv("API_KEY"), base_url="https://api.deepseek.com" ) def load_project_doc(path="PROJECT.md"): with open(path, "r", encoding="utf-8") as f: return f.read() def ask_agent(user_question, doc_path="PROJECT.md"): doc = load_project_doc(doc_path) system_prompt = ( "你是科研助手。以下是当前项目的完整背景文档：\n\n" f"{doc}\n\n" "回答问题时，必须严格依据文档中的术语和约束。" "如果文档没有提到，明确说不知道。" ) resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_question} ] ) return resp.choices[0].message.content print(ask_agent("帮我检查这段代码是否符合项目数据格式约束：..."))

提示：不要硬编码 API Key，用环境变量。这是个细节但很重要，尤其当你准备把脚本交给别人或者提交到版本库的时候。

如果你不想写代码，也可以直接用支持知识库的对话工具，把 PROJECT.md 上传进去，效果类似。但背后的原理是一样的：给模型一份稳定的事实文档。区别只在于工具帮你做了分块和检索，但核心仍然是“模型要有文档可依”。

3.4 为什么我建议从“小项目”开始练手

搭建 Agent 很容易上头，一上来就搞多智能体、工具链、记忆网络。我的建议是别急。先把一个小项目跑通：一个文档、一个模型接口、一个简单的加载函数。这样你能快速感受到 PROJECT.md 带来的变化——比如 AI 对术语的使用准确了，编造参数的次数少了，多轮对话的延续性好了。

等这些基础打牢，再考虑加工具，比如让它自动跑实验脚本、自动更新文档。社区里常说“从 0 到 1 搭建 Agent”，其实最难的不是框架，而是你对自己项目的结构化理解。PROJECT.md 恰好逼着你完成这一步。你要能把它写清楚，说明你对你自己的项目想明白了；你要是写不清楚，后面所有 Agent 的包装都是空中楼阁。

4. 跑科研项目时，PROJECT.md 常见的“翻车”与维护要点

4.1 文档越长 Agent 越糊涂：token 稀释

第一个坑：文档越写越长。我一开始恨不得把所有细节都塞进去，结果整个文档超过 5000 字，再喂给模型，它的回答开始变得又长又飘。原因很直观：上下文窗口和 token 总量不变时，无关细节会稀释关键信息。就像你把一根针丢进草堆，人找不着，模型也找不着。

解决的办法是控制文档长度。我的目标是单个 PROJECT.md 控制在 3000 token 以内，大约就是 2000 到 4000 汉字。如果某个通信协议、数据集结构细节太长，拆出来放到单独的 docs 子文件里，在 PROJECT.md 中只保留一行链接和摘要。分层，比一次性全塞更健康。

4.2 文档和代码不同步：过期信息会带偏 Agent

第二个坑更隐蔽：文档写完了，但实验代码改了，文档没同步。模型拿到旧的参数、旧的文件路径，自然给出错误建议。更麻烦的是，Agent 会非常自信地引用过期内容，因为它真的有“依据”。你甚至会觉得它说得头头是道，直到跑代码才发现参数早就改了。

我现在的做法是：把更新 PROJECT.md 纳入到实验流程中。每次提交代码前顺手改动文档；如果有脚本会自动生成数据文件，那么数据字典部分尽量从代码注释里同步出来。反正不要相信“我记得更新过”。这个坑我踩过不下三次，后来给自己定了一条规则：代码和文档不同步，就是没完成。

4.3 排查链路：一次“Agent 推荐了错误参数”的完整定位过程

有一次，Agent 给我推荐了一个学习率 0.1，我一看就知道不对，因为之前实验里 0.01 都偏高了。但我不能直接怪 Agent，因为它确实读了 PROJECT.md，而 PROJECT.md 里根本没写学习率范围。

这就是排查链路的起点：不是 Agent 抽风，是文档缺失。我接下来做的是：

1. 先把 Agent 的回答和它引用的 PROJECT.md 版本放在一起对比，确认它读到的是最新版。
2. 发现文档里完全没有“超参数范围”这一类约束信息。
3. 在 PROJECT.md 的关键约束里补上一条：学习率取值范围，参考历史实验记录，默认不超过 0.01。
4. 让 Agent 重读文档，再问同一个问题，得到的是“根据项目约束，学习率建议从 0.001 开始调”。

这个过程给了我一个很重要的经验：任何 Agent 的异常输出，先查文档，再查提示词，最后才怀疑模型本身。大部分问题出在前两个。

4.4 用版本化维护项目文档

我建议把 PROJECT.md 也放进版本控制。用 Git 的话，每次的修改都能回溯。这样如果 Agent 给出一个奇怪的结论，我可以看出它读到的是哪个版本的项目背景。尤其当你的实验结论发生变化时，旧版本文档很可能就是“幻觉来源”，可回溯会省很多排查时间。

我在实际使用中发现一个好习惯：在 PROJECT.md 顶部加一个“最后更新时间”字段，并在会话开始时让 Agent 报告读到的版本时间。这样可以第一时间发现文档过期的问题。让 Agent 自己报版本，比你自己去查文件修改时间省事得多。

4.5 什么时候该拆成多个文档

当项目大到一定程度——比如包含文献综述、多个子实验、数据管道——一个 PROJECT.md 就不够用了。我的策略是维护一个 docs 目录，下面按主题拆分：README 作为入口索引，PROJECT.md 作为核心背景，其他文档按需加载。Agent 可以根据用户问题判断要不要读取 docs/experiment-model.md 这类子文档。

拆分的判断标准很简单：如果一个文档已经超过 4000 字，或者里面出现多个平行的“项目目标”，就该拆。不要硬塞，也不要拆得太碎。维持一个“索引 + 按需加载”的结构，对 Agent 的稳定性和成本控制都有好处。

5. 一些值得尝试的扩展：从单 Agent 到多 Agent 共享记忆

5.1 让 Agent 先读文档再提问

一个不起眼但很有效的设置：在会话开始时，默认要求 Agent 先复述一遍它对 PROJECT.md 的理解，再来回答具体问题。这样相当于让模型做了“阅读理解”，它能更好地把文档内容转化到自己的注意力里。实测下来，这个简单步骤能显著减少后续的用词偏差。

我一般在系统 Prompt 里加一句：请先用三句话概括你对项目目标、关键约束和当前状态的理解，然后再开始回答我的问题。这个成本几乎为零，但效果立竿见影。很多看似复杂的 Agent 问题，其实只是模型根本没把上下文当回事。

5.2 PROJECT.md 作为多 Agent 的共享记忆

如果你在尝试多智能体协作，比如一个 Agent 负责写代码、一个负责查文献、一个负责写报告，那么 PROJECT.md 可以作为它们共享的事实源。每个 Agent 都在开始时加载同一份文档，大家至少在项目目标和术语上是一致的。这比让每个 Agent 用自己“训练时的常识”靠谱很多。

当然，通信、编排、结果校验这些后面还有很多工作要做，但 PROJECT.md 是一个很好的起点。至少多 Agent 之间不会再频繁出现“你理解的数据格式怎么和我理解的不一样”这种问题。共享记忆就是共享事实，没有事实的团队协作永远是鸡同鸭讲。

5.3 最后分享一个小技巧

在跑通之后，我还会在 PROJECT.md 里维护一个“模型输出校验”的清单，把模型容易出错的地方列出来，比如时间单位、坐标参考系、统计显著性阈值。然后让 Agent 在每次给出结论前，按清单自查一遍。这个技巧可以视作“提示词层面的约束”，非常管用。

我在这个清单里通常写三类内容：一是容易被误解的术语；二是经常出错的单位或格式；三是“如果文档没写，直接说不知道”的兜底规则。这份清单帮我消除了实验里大量“看着合理其实是瞎猜”的输出。现在我的 Agent 在回答不确定的问题时，会主动说“文档中未定义”，然后在问我原因。搞得像真同事一样。