Codex 应用教程

从能力体系到 SDD 实战：让 AI 编码进入可审查的团队流程

本文以 Codex 的深度应用能力为主线，SDD 作为贯穿方法论，而不是唯一主题。你可以把 SDD 理解为给 Codex 准备“规格、边界、任务和证据”的工程输入；真正要落地，还必须配合 AGENTS.md、Cloud Environment、Sandbox/Rules、Subagents、Skills/MCP/Hooks 和自动化。

Codex 应用教程

图 1：Codex 深度应用框架。SDD 是其中“上下文 + 验证闭环”的方法化表达。

1. 先把 Codex 看成工程协作者，而不是代码补全器

Codex 的价值不止是写代码。高阶用法是让它读项目上下文、理解约束、拆解任务、修改文件、运行验证，并给出可审查的证据。真正的难点不在“让它多写”，而在“让它按团队规则写”。

低阶用法	深度用法
问一个问题，得到一段代码	让 Codex 在项目边界内完成一项可验证任务
每次重新解释背景	用 AGENTS.md、Skills、MCP 沉淀长期上下文
最后人工补测试	任务开始前定义验证命令和 evidence
一个线程硬做复杂任务	用 subagents 并行探索、审查和验证

2. 上下文工程：AGENTS.md、Skills、MCP 的分工

上下文不是越多越好，而是要放在正确的层级。AGENTS.md 放稳定规则，Skills 放可复用流程，MCP 放外部工具和资料入口。SDD 产生的 spec、design、tasks、evidence 则是单个需求的短期上下文。

组件	放什么	不要放什么
AGENTS.md	包管理器、测试命令、架构边界、PR 标准	每次任务里的临时想法
Skills	发布说明、PR 审查、迁移检查等重复工作流	只用一次的提示词
MCP	浏览器、Figma、内部文档、API schema	与任务无关的高权限工具
SDD 文件	当前需求的规格、计划、任务和证据	长期团队规则

3. 执行边界：Sandbox、Rules、Cloud Environment

Codex 能跑命令，所以必须先讲边界。Sandbox 决定能读写什么，Rules 决定哪些命令需要批准或禁止，Cloud Environment 决定云端任务能不能复现。SDD 中的 tasks.md 应该显式写出允许修改的文件范围和验证命令。

实用规则

低风险检查命令可以写进 AGENTS.md 或 rules；跨目录写入、网络下载、高风险命令必须要求批准；Cloud setup script 只负责准备环境，不应该替代任务本身。

边界项	团队应该明确
文件范围	哪些目录允许 Codex 修改，哪些目录只能读
命令范围	哪些测试/lint/build 可自动运行，哪些需要人工确认
网络范围	Cloud agent phase 默认谨慎开放，按域名和方法最小授权
证据范围	每个任务完成后必须留下哪些验证结果

4. SDD：适度引入，而不是把文章变成 SDD 宣讲

SDD 指 Spec-Driven Development / Specification-Driven Development，中文可称“规格驱动开发”。在 Codex 场景里，它不是独立替代所有工程实践，而是把模糊需求变成 Codex 可执行、团队可审查的工程输入。

Codex 应用教程

图 2：SDD 的价值是把模糊提示词变成规格与证据。

推荐的权重是：小任务用任务合同，中等任务用轻量 spec + tasks，大任务再完整使用 spec / design / tasks / evidence。这样不会为了流程而流程。

任务类型	推荐 SDD 强度
一行 bug、typo、简单测试	不用完整 SDD；写清目标、约束、验证即可
中等功能或局部重构	轻量 spec.md + tasks.md，结束补 evidence.md
跨模块功能、架构调整、合规需求	完整 spec.md / design.md / tasks.md / evidence.md

5. SDD × Codex 主流程：从需求到证据

当任务开始变复杂，最稳的链路是：需求意图 → spec.md → design.md → tasks.md → Codex 执行 → evidence.md → PR 审查。注意：Codex 不是只负责最后“写代码”，它也可以参与生成和审查前面的规格、设计与任务。

Codex 应用教程

图 3：SDD × Codex 主流程。

Codex 应用教程

图 4：最小 SDD 文件组。

文件	价值	Codex 使用方式
spec.md	明确目标、非目标、验收标准	先问清歧义，再生成规格草案
design.md	约束方案和架构边界	给出最小实现方案，不随意扩架构
tasks.md	拆成可验证任务	按任务执行，标记可并行项给 subagents
evidence.md	留下验证证据	记录命令、结果、截图、日志和剩余风险

6. 任务合同：轻量 SDD 的最佳入口

如果完整 SDD 太重，就用任务合同。它是最小可用的规格：目标、复现、约束、交付物、验证、汇报。这个结构足以显著降低 Codex 误解需求和扩大范围的概率。

Codex 应用教程

图 5：任务合同，适合小任务和中等任务的起步。

可直接复制的任务合同

目标：要解决什么问题。复现：如何看到问题。约束：不能改什么、不能引入什么。交付物：代码、测试、文档或截图。验证：必须跑什么命令。汇报：最终说明根因、变更、风险和未覆盖项。

7. 并行协作：Subagents 适合审查，不适合抢同一片代码

Subagents 最适合并行探索、审查和验证。例如一个 agent 审安全，一个 agent 查测试缺口，一个 agent 看可维护性。不要让多个 agent 同时大范围修改同一批文件。SDD 的 tasks.md 可以天然标记哪些任务可并行。

适合并行：安全审查、测试缺口、日志分析、性能风险、文档梳理。
谨慎并行：多个 agent 同时改同一模块。
最佳实践：主线程整合决策，子代理给出证据和提议。

8. 复用与自动化：Skills、Hooks、codex exec、Automations

当一个流程重复出现三次，就应该思考沉淀。Skills 适合沉淀工作流，Hooks 适合生命周期控制，codex exec 适合脚本化，Automations 适合周期巡检。SDD 的 evidence.md 可以成为这些自动化的检查目标。

能力	最适合做什么
Skills	PR 审查、发布说明、迁移检查、SDD checklist
Hooks	提交前扫描 secret，停止前检查是否包含验证结果
codex exec	CI 中生成摘要、只读巡检、批量文档更新
Automations	每日巡检、定时关注 PR、生成周报

9. 团队落地路线

团队不应该直接从“大规模自动写代码”开始，而应从上下文、边界、复用、自动化逐步推进。SDD 文件模板可以在第 1 周就引入，但完整 SDD 应该只用于值得的任务。

Codex 应用教程

图 6：团队落地路线。

阶段	目标	交付物
第 1 周	统一上下文	AGENTS.md、检查命令、任务合同模板
第 2 周	收紧边界	Rules、Sandbox 策略、Cloud setup script
第 3 周	沉淀复用	PR review skill、release notes skill、轻量 SDD 模板
第 4 周	自动化	Subagents 模板、codex exec、周期 Automations

10. 资料来源

OpenAI Codex 文档：https://developers.openai.com/codex
OpenAI Codex Prompting：https://developers.openai.com/codex/prompting
OpenAI Codex Workflows：https://developers.openai.com/codex/workflows
OpenAI Codex AGENTS.md：https://developers.openai.com/codex/guides/agents-md
OpenAI Codex Cloud environments：https://developers.openai.com/codex/cloud/environments
OpenAI Codex Subagents：https://developers.openai.com/codex/subagents
GitHub Spec Kit：https://github.com/github/spec-kit