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 的当前目录位于仓库内,再检查文件名大小写、文件是否为空,以及项目是否被标记为可信。不要通过重复粘贴同一份规则掩盖加载问题。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编写 AGENTS.md

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通