Codex 分层提示词设计：项目级 AGENTS.md 之上的任务级模板实践

上一篇谈过 AGENTS.md 作为项目级规范入口的价值，但只有项目级规范是不够的。实际使用中我们发现：一个项目里有几十种高频任务——写接口、写测试、修 bug、做重构——每种任务对提示词的要求完全不同。把所有要求塞进 AGENTS.md，既臃肿又低效。这篇分享我们的解法：项目级规范之上的任务级提示词模板层，以及这个两分法落地三个月后的数据。

一、为什么需要分层：一次失败的实践

先说反例。最早我们把所有经验都堆进 AGENTS.md：技术栈约定、目录结构、加上"写测试的注意事项"“修 bug 的流程要求”“重构的边界规则”，一共 90 多行。

结果怎么样？写 CRUD 接口时，它带着 90 行规范里没用的 40 行；修一个线上 bug 时，测试规范是噪音，但 bug 复现要求被淹在里面。更糟的是会话变长后，它对中后段规范的遵循明显变差——文档越长，单条规范的执行力越差。

这次失败让我们想明白一件事：AGENTS.md 应该放"所有任务都适用的规范"，任务特定的要求应该在任务开始时注入。这就是分层的由来。

二、两层架构的职责划分

第一层：项目级（AGENTS.md），放不变量。

• 技术栈与版本约束：语言、框架、包管理器、禁止引入的依赖类型
• 目录职责：src/、tests/、migrations/ 各放什么，哪些目录禁改
• 代码风格底线：函数长度、命名规范、错误处理方式
• 安全红线：禁止读取的文件、禁止输出到日志的内容

我们的 AGENTS.md 控制在 30 行以内。判断一条规范该不该进来的标准：删掉它，任何任务都会出问题，才配进来。

第二层：任务级模板，放可变量。

按任务类型建一组模板文件，存在项目的 prompts/ 目录下，每个模板针对一类任务。开工时选择对应模板，作为任务描述的开头注入。

三、五个高频任务模板的核心内容

以下是五个月迭代后沉淀的模板骨架（已脱敏简化）：

new-api.md（新接口）

# 任务：新增接口
– 先只读分析：列出相似接口的现有实现，对齐参数校验和返回结构
– 参照 src/routes/ 下最近的接口风格，不发明新结构
– 完成标准：接口可用 + 单元测试覆盖正常/边界/异常三种路径
– 禁止：修改公共模块；如确需修改，先停下来说明理由

fix-bug.md（修 bug）

# 任务：修复缺陷
– 第一轮只做诊断：列出 3 个以内的根因假设，按验证成本排序
– 每个假设给出验证方法，等人工确认后再动手
– 修复完成后：写一个能复现原 bug 的回归测试，必须先失败后通过
– 禁止：顺手重构周边代码

write-test.md（补测试）、refactor.md（重构）、code-review.md（评审） 的骨架类似，核心都是：先约束动作顺序，再定验收标准，最后划禁区。

三个月用下来，模板里最值钱的从来不是"怎么做对"，而是那句"禁止顺手做什么"。

四、模板生效的关键机制：注入方式

模板写得再好，注入方式不对等于白写。三个要点：

**要点一：注入位置在会话开头，紧跟 AGENTS.md 之后。**Codex 加载 AGENTS.md 后读到的第一段用户输入，权重最高。我们的习惯是开场第一句永远是"读取 prompts/fix-bug.md 并严格按其流程执行"。

**要点二：任务描述与模板分离。**模板是稳定的流程约束，具体这个 bug 是什么、涉及哪个文件，放在模板之后单独一段。混在一起写，下次复用就要重新整理。

**要点三：模板本身也要迭代。**每次某个任务翻车，复盘后把教训写回对应模板。我们的 fix-bug.md 从初版的 6 行迭代到现在的 14 行，每一行背后都有一次真实事故。

五、两个月的数据对比

分层改造前后，同一批任务的对比：

最有意思的是最后一行：模板化的本质是把提示词工程从"每次现场发挥"变成"一次性投资、反复复用"。写模板的两小时，一个月内摊薄到接近零。

六、落地建议

如果你现在只有一个臃肿的 AGENTS.md，迁移路径很简单：

小结

提示词工程的成熟标志，不是每次写出精妙的 prompt，而是不再需要每次现写。项目级 AGENTS.md 管住边界，任务级模板管住流程，两层各司其职——这是我们在 Codex 上沉淀下来的最有效的工程化实践。

模板文件整理后放在了 gptupcn.com，需要的话可以直接拿去按自己项目改。