Codex 每次都要重新教？Prompt、AGENTS.md、Skills、MCP 到底怎么选

lrt369805210

425人浏览 · 2026-08-04 15:03:14

lrt369805210 · 2026-08-04 15:03:14 发布

摘要：同一句要求，应该写进当前 Prompt、仓库里的 AGENTS.md，做成 Skill，还是接入 MCP？本文用一张对比图、一个完整案例和一份 30 秒判断流程，讲清四种机制各自解决什么问题，并附可直接复制的 Prompt、AGENTS.md 与 SKILL.md 模板。

关键词：Codex、Prompt、AGENTS.md、Agent Skills、SKILL.md、MCP、AI 编程工作流

使用 Codex 一段时间后，很容易遇到一种反复消耗：

每次都要提醒它使用 pnpm，不要改用 npm；
每次都要说明哪些目录不能动、改完要跑什么检查；
每次发布都要重新描述“看 diff、核对测试、生成 CHANGELOG”的步骤；
需要查 GitHub Issue、设计稿或内部文档时，又得重新想怎么把资料交给它。

这些事情都能写进一段很长的提示词，但问题也会随之出现：提示词越来越臃肿，新开任务还要重新复制；真正只对当前需求有效的限制，反而被埋在一堆长期规则里。

Codex 现在提供了多种定制方式。它们看上去都在“告诉 Agent 怎么工作”，实际承担的职责并不相同。

先记住一句话：Prompt 交代这一次，AGENTS.md 约束这个仓库，Skill 固化一套流程，MCP 连接外部系统。

下面不堆概念，直接从“什么内容该放在哪里”讲起。

一张图看懂：四种机制分别解决什么问题

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

机制	主要解决的问题	适合放什么	有效范围	不适合承担什么
Prompt	把当前任务说清楚	本次目标、上下文、输出格式、临时边界、验收方式	当前任务或当前会话	长期项目规范、复杂重复流程
AGENTS.md	让 Codex 每次进入仓库都遵守同一套规则	项目命令、目录边界、代码约定、检查要求、风险操作	仓库或指定子目录	一次性需求、长篇操作教程
Skill	把反复执行的工作变成可复用流程	多步操作、判断分支、参考资料、脚本、模板和验收步骤	多任务、多项目或团队复用	实时外部数据、单次临时要求
MCP	让 Codex 访问仓库之外的数据与工具	GitHub、Figma、浏览器、Issue 系统、知识库等能力	取决于已连接的服务与权限	代替项目规范、代替完整工作流

OpenAI 的官方定制文档也把它们放在不同层次：AGENTS.md 提供持久的项目指导，Skills 封装可重复流程，MCP 连接本地工作区之外的系统。它们是组合关系，不是四选一。Codex Customization

Prompt：把“这一次要做什么”说清楚

Prompt 最适合承载当前任务才会变化的信息。

比如这次要修哪个问题、允许改哪些文件、输出一份报告还是直接修改、什么情况必须停下来确认。这些要求下一次很可能不一样，没有必要写进项目规则。

一段实用的 Codex Prompt，通常包含五类信息：

目标：修复设置页保存后刷新失效的问题。

上下文：复现步骤在 issue #128，优先检查 settings store 和保存接口。

范围：允许修改 settings 相关代码和测试；不要调整 API 数据结构。

验证：先复现问题，再完成最小修复，运行相关测试和类型检查。

交付：说明根因、修改文件、执行过的检查，以及仍未验证的内容。

这里最重要的不是套模板，而是把真正会改变结果的内容交代清楚。OpenAI 的提示指南给出的关键项也是目标、上下文、输出和边界；对 Codex 任务，还应说明相关代码或复现步骤以及如何验证。Prompting Codex

适合写进 Prompt 的判断标准：这条要求只服务当前任务，或者下一次很可能改变。

AGENTS.md：把仓库长期有效的规则固定下来

如果一条提醒已经说过三次，而且以后大概率还要继续说，就值得考虑放进 AGENTS.md。

例如：

依赖必须使用 pnpm 安装；
generated/ 下的文件不能手工修改；
修改 API 后要运行契约测试；
新增生产依赖前必须确认；
不覆盖工作区里与本次任务无关的改动。

一份精简的项目级 AGENTS.md 可以这样写：

# AGENTS.md

## Project

- This is a TypeScript monorepo managed with pnpm workspaces.
- Frontend code lives in `apps/web`; API code lives in `services/api`.

## Commands

- Install dependencies with `pnpm install` from the repository root.
- Run targeted tests for the package you changed.
- Run `pnpm lint` and `pnpm typecheck` before finalizing code changes.

## Boundaries

- Do not edit files under `generated/`; use `pnpm generate`.
- Preserve unrelated user changes in the working tree.
- Ask before adding production dependencies or changing public APIs.

## Handoff

- Summarize what changed and why.
- List the checks actually run and their results.
- Call out anything that remains unverified.

Codex 会在开始工作前读取这些说明。规则可以放在全局、仓库根目录和更靠近代码的子目录；从项目根目录到当前工作目录逐层组合，越靠近当前目录的规则优先级越高。Custom instructions with AGENTS.md

AGENTS.md 不宜变成另一本 README。业务背景、完整 API 文档和很长的操作教程仍应放在原来的文档中，只在 AGENTS.md 里告诉 Codex 去哪里读、什么时候必须读。

适合写进 AGENTS.md 的判断标准：每次在这个仓库或目录工作时都要遵守，而且它会影响修改方式或验收结果。

Skill：把重复工作变成一套可执行流程

AGENTS.md 擅长写“始终遵守什么”，但不适合塞进一大段分步骤教程。

假设你每次发布都要做这些事：

确认 Git 变更范围；
从代码和测试中提取用户可见变化；
更新 CHANGELOG 与相关文档；
生成发布说明；
核对链接、示例和发布边界。

这已经不是一句项目规则，而是一套会重复执行、带输入输出和验收步骤的工作流，更适合做成 Skill。

一个 Skill 至少包含 SKILL.md，还可以按需加入脚本、参考资料和模板：

release-docs/
├── SKILL.md
├── references/
│   └── release-style.md
├── scripts/
│   └── collect-diff.sh
└── assets/
    └── release-template.md

最小可用的 SKILL.md 不需要写得很复杂：

---
name: release-docs
description: 根据已确认的代码变更生成 CHANGELOG、技术文档和发布说明。用于准备版本发布材料；不要在尚未确认变更范围时触发。
---

1. 只读检查 Git 状态、目标 diff、相关测试和已有文档。
2. 建立事实清单，区分用户可见变化、内部重构和无法证实内容。
3. 输出文档影响范围，等待确认后再修改文件。
4. 分别起草 CHANGELOG、技术文档和发布说明，不混用三者的读者视角。
5. 运行仓库已有的文档检查，并列出未验证项。
6. 未经确认，不提交、不推送、不发布。

OpenAI 当前的 Skills 文档要求 SKILL.md 至少提供 name 和 description。Codex 会先查看技能元数据，任务匹配时再读取完整说明，需要时才继续读取引用或运行脚本，这种渐进加载能避免一开始就把所有细节塞进上下文。Build skills

适合做成 Skill 的判断标准：这是一项会重复发生的工作，步骤相对稳定，而且包含多步判断、参考资料、模板或可复用脚本。

MCP：给 Codex 接上外部数据和操作能力

Prompt、AGENTS.md 和 Skill 都能告诉 Codex“应该怎么做”，但它们不会凭空提供外部系统的访问能力。

如果任务需要读取 GitHub PR、查询 Issue、获取 Figma 设计、控制浏览器，或者访问团队知识库，就要用到工具或 MCP。

可以把 MCP 理解成一条能力通道：

Codex 是使用这些能力的宿主；
MCP 连接负责把工具与上下文提供给 Codex；
MCP Server 可以暴露可执行工具、可读取资源和可复用提示模板；
实际能读什么、能改什么，仍然取决于服务权限和审批策略。

OpenAI 的说明把 MCP 定义为连接模型与工具、上下文的协议，适合让 Codex 使用浏览器、Figma、GitHub 或第三方文档等外部能力。Model Context Protocol

需要特别注意：MCP 提供“能做什么”，Skill 规定“按什么流程做”。

例如，GitHub MCP 能让 Codex 读取 PR 和 Issue；一个“准备发布材料”的 Skill，则可以规定先读取哪些信息、如何筛选事实、输出什么格式、发布前如何验收。两者组合后，工作流才既有步骤，也有数据入口。

适合接入 MCP 的判断标准：任务需要本地仓库之外的实时数据，或者需要在外部系统中执行受控操作。

用同一个任务，看清四者怎样配合

以“为 v1.4.0 准备发布材料”为例：

层次	在这个任务里负责什么	具体内容
Prompt	定义本次发布	目标版本是 v1.4.0；比较 v1.3.2 到当前分支；先生成草稿，不要发布
AGENTS.md	提供仓库固定规则	使用项目原有术语；用户行为变化必须同步 docs；完成后运行文档检查
Skill	执行稳定工作流	收集差异 → 建立事实清单 → 更新文档 → 生成发布说明 → 反向验收
MCP	补齐外部上下文	读取 GitHub PR、Issue、里程碑或团队文档中的已确认信息