写一份真正有用的 AGENTS.md

如果每次打开项目都要解释测试命令、生成文件的位置和接口兼容要求，可以把这些长期有效的约定放进 AGENTS.md。它的价值在于减少重复沟通，让后续任务获得相同的项目背景。

先分清长期约定与当次任务

“接口字段使用 snake_case”属于项目约定；“本次修复导出按钮”属于当次任务。两者混在一起，几周后就很难判断哪些规则仍然有效。AGENTS.md 适合保留稳定信息，具体需求和短期进度留在任务说明中。

OpenAI 文档说明，Codex 会组合全局与项目目录中的指引。同一目录优先读取 AGENTS.override.md，再考虑 AGENTS.md；从项目根目录到当前目录，越靠近当前目录的指引位置越靠后。排查规则未生效时，应同时检查启动目录和覆盖文件。[1]

从四类信息开始

项目入口：业务代码、测试和生成产物分别在哪里。只保留容易误判的目录，不要抄写整个文件树。

验证方法：真正可运行的测试或构建命令，以及必要的前置条件。命令变更后应同步更新。

兼容要求：哪些接口、文件格式或旧链接需要保持稳定。说明原因，会比单独写一句“不要修改”更清楚。

变更边界：哪些文件由工具生成，哪些操作需要单独确认，怎样处理任务开始前已经存在的改动。

一份适合小型前端仓库的起点

# 项目协作约定

## 目录
- src/ 是业务代码，tests/ 是测试。
- dist/ 是构建结果，修改源文件后重新生成。

## 验证
- 使用 package.json 中现有的构建和测试脚本。
- 修复行为缺陷时，覆盖触发该缺陷的输入。
- 无法运行的检查要写明原因。

## 兼容
- 保留已发布文章的 URL。
- 复用现有样式变量和组件，不重复引入同类依赖。

## 协作
- 保留任务开始前已有的无关改动。
- 提交结果时说明实际验证过的行为。

上面的路径需要按真实项目调整。维护规则时，最好直接运行一次列出的命令，确认它们没有因为脚本改名、依赖升级或目录迁移而过期。

大仓库按目录拆分

前端与数据库迁移的约束通常不同。根目录只放共同约定，专项规则放在相应目录，并从该目录启动任务或确认当前加载范围。拆分的目的，是减少无关规则，同时让局部约束容易找到。

避免在多层文件中重复写同一件事。重复规则一旦不一致，维护成本会迅速增加。对局部例外，写清适用范围和原因，方便之后重新评估。

把规则当成需要维护的代码

新增规则前，可以问三个问题：它是否解决了真实发生的问题？是否能明确判断遵守与否？是否仍适用于当前工具链？如果答案不明确，先把它留在任务讨论里。

更新后开启新会话，请 Codex 列出已加载的指引并概括关键约定。再用一个小任务检查实际行为。规则文件写得很长，不等于规则真的有效；能被理解、执行和验证，才有长期价值。