AGENTS.md
项目根目录的 AGENTS.md 是项目规则:Agent 每次对话都会读,你在「记忆 → 当前项目」里直接改,改完自动保存。
更新于 2026年11月10日
AGENTS.md 是放在项目根目录的规则文件,写这个项目必须遵守的事:用什么包管理器、哪些目录不能动、提交前要执行什么。Agent 每轮都会读它,所以它是「不看就会做错」的那一类知识,不是资料库。
查看与编辑
左侧栏「记忆」→「当前项目」,文件列表第一行固定是「项目 AGENTS.md」,副标题显示「项目规则 · 项目根目录」,还没建过就显示「待建立 · 项目根目录」。
- 文件内容在右侧直接编辑,停止输入约一秒自动写盘。
Cmd/Ctrl + S立刻保存;切换文件或切走页面时也会先把未保存内容刷盘。- 文件状态显示「自动保存」「等待保存」「需要合并修改」。
- 想知道 Agent 读的是哪个文件,看编辑器上方的绝对路径,或点「打开文件所在位置」。
加载方式
- 从会话的工作目录开始,沿上级目录一路往上找
AGENTS.md,所以把规则放在仓库根,子目录里的会话也能读到。 - 会话工作目录是 Proma 的会话目录时,会额外从项目根再加载一次,项目规则不会因为工作目录换了就丢。
- 多个层级的规则同时存在时都生效,具体走哪一份以 Agent 实际工作目录为准。
自动建立与完善
第一次在项目里开展任务时,Proma 会先补全这份规则,不需要手动初始化。
- 还没有
AGENTS.md:项目页显示「待建立」,下一次对话自动建立并写入骨架,已有内容不动。 - 文件存在但内容太少:提示「项目协作能力待完善,下次对话将自动建立或关联项目规则与记忆,无需手动初始化。」
- 发现旧的外层规则文件:提示「发现旧项目规则,下次对话将自动合并并完善协作能力;原文会保留备份。」旧文件在被合并归档之前仍然生效。
- 规则文件被清空后,下一次对话会重新触发完善。
这些提示都带一个「定位旧规则」按钮,用来打开旧文件所在的文件夹。旧规则只能在自己的项目主目录里合并,从别的项目或 worktree 打开的会话会提示「旧规则待合并,请在原项目主目录的会话中处理」。
内容范围
- 命令与版本约定:用哪个包管理器、启动和测试命令、Node 或 Bun 的版本要求。
- 目录边界:哪些目录是生成的不要改,哪些是共享的不要删。
- 红线禁令:不能提交的东西、不能覆盖的文件、必须询问你的操作。
- 项目结构和常用入口,控制在看一遍就能记住的篇幅。
不要写:一次性的排查经过、某天的状态快照、某个模块的详细实现说明。这些内容留在会话里或写进项目记忆的专题文件。
注意
AGENTS.md是规则,改错了下一轮就会照着做错;改完在同一项目里发一轮对话,能验证 Agent 的解读是否符合预期。- 内容太短会被当成「待完善」,下一次对话自动补写;写到能覆盖主要约束的程度,才不会再被改动。
- 在 worktree 里工作时,界面编辑的是项目根的那一份,worktree 自己的规则文件需要直接打开文件改。
- 会话里临时说的要求不会写进
AGENTS.md,要长期生效必须落到文件。