AI Agent / 系统课时
编写 AGENTS.md
编写 AGENTS.md
AGENTS.md 用于保存每次任务都应遵守的仓库规则。本课将编写一份短小但可执行的项目指令,覆盖目录定位、常用命令、编码约定和完成标准,并通过 Codex 自检确认文件确实被加载。
学习目标
- 区分适合写入
AGENTS.md的持久规则与临时需求 - 编写包含项目结构、命令和验证要求的最小文件
- 验证 Codex 已读取并理解仓库指令
只记录可复用规则
AGENTS.md 会自动进入 Codex 的项目上下文,适合保存仓库布局、构建测试命令、代码约定和评审要求。一次性的需求、具体缺陷描述和临时实验结论应留在当前对话,否则文件会不断膨胀,旧规则也更容易与现实冲突。
好的指令应能直接影响行动。例如“保持高质量”无法验证,而“修改 TypeScript 后运行 npm run lint 和相关测试”可以执行。命令必须以仓库当前实际脚本为准,不能从其他项目复制。
编写最小可用文件
在仓库根目录创建 AGENTS.md。下面是一个适合 Node.js 服务的片段示例,使用前应替换为本项目真实目录与命令。
markdown
# Repository Guide
## Project layout
- `src/` contains application code.
- `tests/` contains automated tests.
- `docs/` contains public behavior documentation.
## Working rules
- Keep changes within the requested module.
- Do not add production dependencies without approval.
- Follow the existing TypeScript style.
## Validation
- Run `npm run lint` after changing TypeScript files.
- Run `npm test -- --runInBand` before reporting completion.
- Summarize changed files and any remaining risks.生效行为:Codex 进入该仓库或其适用子目录时,会把这些内容作为持久项目指导。规则不等于强制安全边界,因此关键约束仍应由测试、格式化工具、权限策略和代码审查共同保证。
验证是否加载
从仓库根目录启动一次只读检查,让 Codex 复述指令来源,不要求它修改代码。
bash
codex --ask-for-approval never "列出你为当前仓库加载的项目指令,并概括必须执行的验证命令。不要修改文件。"预期结果的措辞可能不同,但应明确提到根目录 AGENTS.md,并列出 npm run lint 与测试命令:
text
已加载当前仓库的 AGENTS.md。
完成 TypeScript 修改后需要运行 npm run lint,并在交付前运行相关测试。
未修改任何文件。若输出没有提到该文件,先确认 Codex 的当前目录位于仓库内,再检查文件名大小写、文件是否为空,以及项目是否被标记为可信。不要通过重复粘贴同一份规则掩盖加载问题。
按自己的节奏,确认真正理解。