# Codex 可执行任务说明书

核验日期：2026-07-16

## 可复制结构

```text
背景：
说明用户、当前行为和为什么现在要改。

目标：
用可观察结果描述本轮唯一目标。

先读：
列出入口、相邻实现、类型、测试和 AGENTS.md；未知时要求 Codex先调查。

允许修改：
列出文件、目录或模块边界。

禁止修改：
列出必须保持不变的接口、数据、权限、依赖和无关功能。

实施要求：
说明最小改动原则、错误处理、兼容性和需要保留的现有模式。

验收标准：
逐项写成可以测试或人工观察的行为。

验证命令：
只列仓库真实存在的命令，并说明最小与完整检查。

报告格式：
改动、文件、实际命令与结果、手工 QA、未验证项、风险。

停止条件：
遇到接口变化、生产操作、秘密、删除数据、范围扩大或不可逆决定时停止确认。
```

## 完整示例

```text
背景：
资源下载接口在 slug 不存在时返回 500，日志显示读取文件前没有区分未注册资源。

目标：
让未知 slug 返回现有 API 约定中的 404 JSON，合法资源下载行为保持不变。

先读：
读取根 AGENTS.md、下载 route、资源 registry、错误响应 helper 和相关测试。
第一阶段只调查并列出计划，不编辑文件。

允许修改：
- 下载 route。
- 与未知 slug 行为直接相关的测试。

禁止修改：
- 不改资源数据格式。
- 不改认证和下载审计逻辑。
- 不新增依赖。
- 不删除或覆盖工作树中已有的无关改动。

实施要求：
沿用仓库现有错误 helper；在读取文件前处理未知 slug；不要捕获并吞掉所有异常。

验收标准：
- 未知 slug 返回 404 和稳定错误码。
- 已知 slug 仍返回原有内容类型和文件名。
- 未授权行为保持现有状态码。
- 新测试在旧实现失败、修复后通过。

验证命令：
- pnpm lint
- pnpm typecheck
- pnpm test -- download

报告格式：
列出改动文件、每条命令的退出结果、没有运行的完整构建和任何残余风险。

停止条件：
如果错误契约在多个 route 中不一致，先报告证据，不扩展为全站重构。
```

## 迭代提示

调查后：

```text
先不要实施。用文件路径说明当前错误路径、最小修改点、会受影响的测试和你仍不确定的事实。
```

实施后：

```text
阅读完整 diff。逐项映射验收标准到测试或手工证据；没有实际运行的检查明确标为未验证。
```

## 自检

- [ ] 目标只有一个主要行为变化。
- [ ] 范围和禁止事项都可判断。
- [ ] 验收不是“看起来更好”等主观描述。
- [ ] 命令来自当前仓库。
- [ ] 高风险事项有停止条件。
- [ ] 没有把长期仓库规则重复塞进每个提示；它们应进入 AGENTS.md。

官方来源：

- https://learn.chatgpt.com/docs/prompting
- https://learn.chatgpt.com/docs/agent-configuration/agents-md