用 AGENTS.md 留下真正有用的项目上下文

# 用 AGENTS\.md 留下真正有用的项目上下文

长期规则放进仓库，当前任务留在对话，减少重复解释。

资料核实：2026-10-20

## 学习目标

写出一份简短、能核对、适合长期维护的仓库指引。

## 图示：AGENTS\.md 的三层稳定信息

1. **项目用途**：产品解决什么问题、面向谁，以及核心目录各自负责什么。
2. **运行与检查**：从项目脚本核对过的启动、构建与测试入口，而不是记忆中的命令。
3. **修改边界**：前后端职责、数据归属和必须保留的业务规则。

判断标准是换一次会话、换一个任务，这条信息是否仍然成立。

## 适用场景

每次新会话都要重复告诉 Codex 如何启动项目、哪里不能随便改，或者它总在不相关目录中扩散修改。

## 准备条件

- 已经知道项目使用的开发与测试入口。
- 能查看现有 AGENTS\.md、README 与项目脚本。

## 操作步骤

### 1. 先检查已有指引

先读现有文件，再补缺失内容。Codex 认可 AGENTS\.md 作为持久仓库指引；不要为了套模板覆盖项目已经确认的规则。

**检查提示词**

```text
请查看本仓库的 AGENTS.md、README 和项目脚本。
指出本任务适用的规则，以及仍缺少的上下文；先不要编辑文件。
```

### 2. 只留下稳定信息

记录项目用途、关键目录、真实测试命令和业务边界。临时进度、一次性故障日志和某次任务的待办不适合长期堆在这里。

**AGENTS\.md 内容结构示意**

```markdown
## 项目用途
说明产品解决什么问题。

## 运行与检查
填写从项目配置核对过的启动和测试命令。

## 修改边界
说明前后端职责、数据归属和必须保留的业务规则。
```

### 3. 需要起点时使用 /init

在 Codex 交互会话中可用 /init 生成起始指引。生成结果仍需和真实目录、命令逐项核对；它不能替你决定尚未明确的业务规则。

**Codex 交互命令**

```text
/init
```

### 4. 用真实任务验证是否够用

开启下一项任务时，让 Codex 指出读取了哪些规则和实际路径。只补足反复缺失的上下文，避免把指引越写越长。

## 常见误区

### 复制别人的指引，保留不适用命令

以当前仓库的脚本和架构为依据逐项替换。

### 把临时任务和永久规则混在一起

将本次目标写在任务说明，稳定约定保留在 AGENTS\.md。

## 验收清单

- 指引中的目录和命令确实存在。
- 没有密钥、账号口令或只属于某次任务的长日志。
- 新任务能据此找到入口，并解释需要遵循的主要边界。

## 资料与版本

本文为原创整理，示例需按项目调整；工具界面与功能以当前版本为准。

- [OpenAI：Codex 工作流示例](https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex)