AGENTS.md 项目约定

AGENTS.md 是常见的项目约定文件格式。Captain Who 会自动读取项目文件夹根部的 AGENTS.md，并在对话中把内容作为工作区约定提供给 Agent——不需要每次手动粘贴。

放置与优先级

• 在每个项目文件夹的根目录放一个 AGENTS.md；当前不会读取子目录中的文件。
• 同一目录存在 AGENTS.override.md 时以它为准，适合临时覆盖团队默认约定。
• 多文件夹项目会合并各文件夹根部的约定，每个文件夹最多取一个文件。
• 空文件不提供任何内容。
• AGENTS.md 需要是真实文件；指向其他位置的符号链接会被忽略。

适合写进 AGENTS.md 的内容：代码风格与命名约定、目录结构说明、常用命令（例如构建与测试）、评审要求，以及希望 Agent 优先阅读的文档入口。

Agent 看到什么

• 约定的正文，以及它来自哪个文件夹（以 @workspace/<别名> 标注）和文件名。
• 所有文件夹合计最多约 32 KiB；超出后只保留前面的内容，并标注内容可能不完整。
• 最新的约定内容会作为项目约定用于当前任务，但只在对应文件夹（含子目录）内生效，并且不能改变权限、审批与安全规则，也不能覆盖你当前的明确要求；发生冲突时以后者为准。
• 和其他上下文一样，约定内容会随对话发送给你配置的模型服务商。

更新时机

修改 AGENTS.md 后不需要重启应用或新建对话：Agent 在下一次请求时就会看到最新内容。删除文件后约定不再提供；恢复文件后同样会在下一次请求中生效。上下文窗口预览显示的也是磁盘上的最新状态（新增、修改与删除都会体现）。

排查

• Agent 没有按约定工作时，先确认文件位于项目文件夹根目录、文件名拼写正确。
• 多文件夹项目中，确认文件放在了正确的源文件夹；界面会以别名区分不同来源。
• 约定很长时，考虑精简到最关键的规则，避免被截断。

相关：文件与 Git 介绍项目授权与文件工具；上下文与历史 说明 Agent 还能看到哪些信息；管理大型项目 给出组织约定的建议。