Codex 项目开发实战指南
一套以真实项目生命周期为主线的方法论手册：从接手项目到长期维护，每个阶段都告诉你「为什么这样做、做什么、Codex 怎么参与、给它喂什么任务、产出什么文档、怎么进入下一步」。
适用对象：用 Codex（或同类 coding agent）做真实项目的开发者、独立开发者、技术负责人。不限定技术栈与框架。
阅读方式：第一次通读「第一/二部分」建立心法与底座；之后每接一个新项目，把「第三部分」当 SOP 照着走；卡住时回查对应章节末尾的 Checklist 和文末附录。
目录
- 前言：这份指南解决什么问题
- 第一部分 · 心法
- 第二部分 · 底座（开工前先懂两件事）
- 第三部分 · 项目生命周期实战（主线）
- 第四部分 · 沉淀
- 附录
前言：这份指南解决什么问题
很多人用 Codex 的方式是「一句话丢过去」：
帮我做个网站 / 帮我改这个功能 / 帮我优化一下项目。
这样不是不能用，但会反复踩同一个坑：AI 改得很快，你却不知道它改了什么，更不敢确认能不能放心交付。 在小 demo 上无所谓，一旦放到有真实用户、需要长期迭代的项目里，最典型的事故就是——改了问题 A，引发了问题 B 和 C。
根因只有一句话：AI 不懂你项目过去的逻辑，每开一个新对话它都从零猜你的意图。 猜错就改错，改一处动一片。
这份指南要解决的，就是把「靠运气」变成「靠流程」。它的核心主张是：
需求不会直接变成交付物。中间必须经过理解 → 文档 → 规划 → 拆分 → 实现 → Review → 测试 → 上线 → 维护这条链路，每一步都有边界、有产出、有验收。
把这条链路固化下来，Codex 的输出就会从「不可控」变成「可预期、可审查、可回滚」。
第一部分 · 心法
第 1 章 核心理念与十条根本原则
1.1 先纠正一个认知：Codex 是工程执行者，不是代码生成按钮
AI 编程工具这些年大致走过四个阶段：补全（Copilot）→ 对话（ChatGPT）→ 项目协作（Cursor 类编辑器）→ 工程 Agent（Codex 类）。
一句话区分：Copilot 帮你补代码，ChatGPT 帮你想代码，Cursor 陪你改项目，而 Codex 帮你执行工程任务。
Codex 真正的价值不在于「生成一段代码」，而在于它能进入一个真实项目：读文件、理解上下文、制定计划、修改代码、运行命令、检查结果、整理成可 review 的 diff/PR。所以本指南所有方法，都是围绕「如何把任务安全地交给一个执行者」来设计的——而不是「如何写出一句好 prompt 让它吐代码」。
1.2 十条根本原则（贯穿全书）
| # | 原则 | 一句话解释 |
|---|---|---|
| 1 | 执行者定位 | 把 Codex 当工程执行者，交付任务，而不是当代码按钮要片段 |
| 2 | 人拍板，AI 执行 | 方向、边界、验收由人决定；读、写、跑、查由 AI 干 |
| 3 | 先理解，后动手 | 没读懂项目之前，不让它写任何业务代码 |
| 4 | 计划先行 | 先出方案（Plan Mode）确认，再改代码，绝不直接动手 |
| 5 | 边界优先 | 动手前先讲清"哪些文件/功能不能碰"，给 AI 画牢笼 |
| 6 | 小步快跑 | 一次只改一小块，每步可独立测试、可回滚 |
| 7 | 文档即上下文 | AI 没有你的历史记忆，文档是它唯一的"项目记忆" |
| 8 | 一切留痕 | 需求、设计、变更、Review 都落成文档，不留口头约定 |
| 9 | 统一约束 | 组件、色值、模板、工具库强制统一，杜绝风格漂移 |
| 10 | 主流程优先 | 先把"AI coding 流程"跑通，自动化/Agent 等辅助后置 |
这十条不是装饰。后面每个阶段的做法，本质都是这十条在某个环节的具体落地。如果某个做法你想不通为什么，回头对照这张表，基本都能找到出处。
1.3 全局视角：一张图看懂整条链路
接手 → 理解 → 建文档 → 规划需求 → 拆任务 → AI协作开发 → Review → 测试 → 上线 → 维护
│ │ │ │ │ │ │ │ │ │
环境就绪 认知报告 文档体系 需求文档 任务清单 可审查diff 通过PR 测试通过 发布成功 回到"规划"
(地基) +责任田边界 +责任划分 (Plan Mode) (画边界) 记录 形成闭环
维护不是终点，而是回到「规划需求」，形成闭环。每一轮迭代都复用同一条链路。
第 1 章 Checklist
- 我已经不再把 Codex 当"代码生成按钮"，而是当"可被交代任务的执行者"
- 我能背出"人拍板 / AI 执行"这条分工线
- 我接受"先理解后动手、先计划后改代码"是默认纪律，而不是可选项
- 我理解"文档即上下文"——不写文档，AI 就只能靠猜
- 我认同"先跑通主流程，再上自动化"，不会一开始就堆一堆 Agent 和工具
第二部分 · 底座（开工前先懂两件事）
在进入生命周期之前，必须先建立两个"地基"：文档体系（第 2 章）和 能力底座（第 3 章）。后面每个阶段都会反复用到它们，所以先讲清楚，避免后文重复。
第 2 章 文档体系：项目的"上下文地基"
2.1 为什么文档是 Codex 的命脉
人协作靠记忆和默契，AI 协作靠文档。你脑子里的"这个页面之前为什么这么写、哪些地方不能动"，AI 一概不知。你不写下来，它就只能：
- 全项目乱找文件 → 改错地方
- 凭训练数据猜风格 → 风格不统一
- 为了完成当前任务顺手改别处 → 级联 bug
所以：文档不是给人留档用的附属品，而是 Codex 的工作输入。 文档质量直接决定 AI 输出质量。
2.2 四类核心文档及其关系
把两份材料里散落的文档概念统一成四类，各司其职：
| 文档 | 主要读者 | 作用 | 何时建/更新 |
|---|---|---|---|
| AGENTS.md（全局规则） | Codex / AI | 告诉 AI 在本项目里"该怎么工作"：技术栈、命令、规范、禁止事项、完成标准 | 建文档阶段建立，规范变化时更新 |
| 责任田文档（模块边界） | Codex / 人 | 描述每个页面/模块"是什么、管什么、影响谁、不能动什么" | 建文档阶段建立，每次该模块迭代时更新 |
| 需求与变更文档（Spec） | 人 / Codex | 记录"这次要做什么、解决什么问题、边界、完成标准"，以及改了什么（变更记录） | 规划需求阶段产出，每次迭代新增 |
| Review 与测试记录 | 人 | 记录 diff 审查结论、测试结果、风险说明 | Review/测试/提交阶段产出 |
命名约定（解决两份材料的冲突）：本指南是 Codex 视角，全局规则文件统一用
AGENTS.md。如果团队同时用 Claude Code，再放一份CLAUDE.md，内容可与 AGENTS.md 共用——两者只是不同 Agent 读取的同一套项目规则。其余文档（责任田、需求、Review）命名随项目约定，能让 AI 在动手前读到即可。
它们的关系，可以理解成一个金字塔 + 时间线：
AGENTS.md（全局：整个项目怎么干）
/ \
责任田文档A 责任田文档B …（模块级：每块的边界与影响）
│
需求/变更文档（每次迭代：这轮做什么、改了什么）
│
Review/测试记录（每次交付：审查与验证结论）
- 向上：责任田受 AGENTS.md 约束；需求受责任田边界约束。
- 沿时间：需求 → 变更 → Review/测试，构成一次迭代的完整留痕。
2.3 AGENTS.md 详解（全局规则）
定位：写给 AI 看的"项目规则说明书"，对应给人看的 README。
三级作用域（叠加生效）：
| 位置 | 作用范围 | 用途 |
|---|---|---|
项目根目录 AGENTS.md |
整个项目 | 本项目的总规则 |
子目录 AGENTS.md |
该子目录/模块 | 某个模块的专属规则（与"责任田"天然契合） |
用户级 ~/.codex/AGENTS.md |
你的所有项目 | 个人通用偏好（如全局防误删指令） |
一份好的 AGENTS.md 的特征：具体（写清技术栈/命令/目录）、简洁（不写废话）、可执行（看了就知道怎么做）、有限制（明确哪些文件不能碰）、有验证（写清用什么命令检查）、有完成标准（知道交付什么）、可维护（项目变了及时更新）。
怎么写：直接让 Codex 读完项目后帮你总结初稿，你再审校。完整模板见 附录 A。
强烈建议加进用户级 AGENTS.md 的防误删指令（AI 编程最大事故之一就是乱删）：
禁止批量删除文件或目录。不要使用 rm -rf、del /s、rd /s、rmdir /s、Remove-Item -Recurse。
需要删除时，只能一次删除一个明确路径的文件。
如需批量删除，应停止操作并请求用户手动删除。
2.4 责任田文档详解（模块边界）
「责任田」是本指南的核心实践，也是防级联 bug 的关键。它把"橙皮书里需求拆解时临时画的边界"沉淀成长期文档。
粒度原则：以页面 / 功能模块为单位划分。太碎（按函数）维护成本高，太粗（整个系统一份）失去意义——页面级刚好。
每块责任田至少写清八个字段：
- 功能描述（这块负责什么）
- 入口（路由/组件/调用入口在哪）
- API 明细（依赖哪些接口、字段）
- 依赖关系（依赖谁、被谁依赖）
- 影响范围（改这里会牵动哪些地方）
- 修改边界（什么能改、什么绝对不能动）
- 注意事项（历史坑、特殊逻辑）
- 约束（必须复用的组件/token/工具库）
它的价值：每次迭代前，让 AI 先读对应责任田文档，它就知道边界在哪、改这里会动到谁。这一步做到位，"改 A 崩 B、C"基本就被堵住了。模板见 附录 A。
2.5 需求/变更文档 与 Review/测试记录
这两类是"按迭代产生"的，分别在第 7 章和第 10/11 章详述，模板见附录 A。这里只需建立认知：它们让每一次改动都可追溯——谁、为什么、改了什么、验证了没有。
第 2 章 Checklist
- 我能说清四类文档（AGENTS.md / 责任田 / 需求变更 / Review测试）各自的作用
- 我理解它们的金字塔+时间线关系，不会把它们混成一坨
- 全局规则文件统一为
AGENTS.md（如用 Claude 再共用一份CLAUDE.md） - 责任田以"页面/模块"为粒度，含全部八个字段
- 用户级 AGENTS.md 已加入"防批量删除"指令
第 3 章 能力底座：Skill、MCP、插件、记忆与工具链
3.1 三者怎么分：一句话定位
| 能力 | 解决什么 | 一句话 |
|---|---|---|
| Skill | "怎么做"的问题 | 把一套固定工作方法沉淀下来复用 |
| MCP | "连接什么"的问题 | 让 Codex连上外部工具/数据源 |
| 插件 | 增强 Codex 本身 | 给 Agent 装上额外的流程/编排能力 |
记忆口诀：「怎么做」用 Skill，「连接什么工具」用 MCP。
3.2 Skill：把重复流程标准化
什么时候用：同一类任务经常重复做（写 README、做 Code/UI Review、生成落地页、标准化修 bug 流程），且你希望输出稳定、团队统一。一次性小任务、临时改一句文案、只问个概念——不用做 Skill，直接写 prompt 即可。
Skill vs 普通提示词：
| 维度 | 普通提示词 | Skill |
|---|---|---|
| 使用 | 每次手输 | 存成固定能力 |
| 稳定性 | 容易漏要求 | 更稳定 |
| 复用性 | 低 | 高 |
| 适合 | 临时任务 | 重复任务 |
与本指南的"统一约束"结合：把"必须用封装组件、必须引颜色库 token、生成代码按模板、必须用封装工具库不准引第三方"这类风格约束写成 Skill（或写进 AGENTS.md 的代码规范），就能根治"AI 生成代码不统一"。
Skill 基本结构（模板见附录 A）：适用场景 / 工作目标 / 工作流程 / 输出格式 / 注意事项。
3.3 MCP：让 Codex 连上外部世界
什么时候用 Skill vs MCP（最常见的纠结）：
| 需求 | 用 |
|---|---|
| 写 README、固定文档输出格式 | Skill |
| 做代码 / UI Review | Skill |
| 把"修 bug / 生成页面"流程标准化 | Skill |
| 查最新开发文档、新版本 API | MCP |
| 连接数据库 | MCP |
| 读取 Figma 设计稿 | MCP |
| 读取 GitHub issue / PR | MCP |
| 连 Notion / 内部知识库 / 公司内部工具 | MCP |
重点推荐：Figma 设计稿 MCP。 AI 靠"截图识别样式"非常不稳，经常谜之操作。用 Figma Dev Mode MCP，把设计的结构化数据（组件、变量、token、布局）直接喂给 Codex，比喂截图准得多。注意前提：不接 Code Connect 时，样式仍可能大幅不准——把 Figma 组件和代码库真实组件用 Code Connect 连起来，效果才真正拉满。所以这属于"有余力再上"的进阶项，不是开箱即用。
3.4 记忆系统
让 Codex 记住长期有用的信息（项目规则、个人偏好），主要载体就是 AGENTS.md 三级作用域（见 2.3）。把稳定不变的约定写进 AGENTS.md，等于给 AI 建立持久记忆，避免每次重新解释。
3.5 推荐工具链（按需引入，别一上来全装）
原则 10：先跑通主流程，再加辅助。下面工具按"先后该上"的顺序列，不要一次性全装。
| 工具 | 作用 | 何时引入 |
|---|---|---|
| Plan Mode（计划模式） | 改代码前先出方案、确认再执行 | 第一优先，必须用 |
| AGENTS.md + Skill | 全局规则 + 风格约束 | 建文档阶段就补齐 |
| OpenSpec（spec-driven） | propose→apply→archive 三段式，用 delta 只记增量改动，明确标 ADDED/MODIFIED/REMOVED；brownfield 友好 | 想把"先 spec 后实现"流程固化时 |
| Superpowers | 把 brainstorm→plan→TDD→review 流程做成自动触发的技能；Codex 有官方插件市场 | 想要更强的流程纪律时 |
| oh-my-codex | Codex 的多 Agent 编排，适合并行跑多任务 | 任务并行需求出现后 |
| Figma Dev Mode MCP | 设计稿结构化喂给 AI（配 Code Connect 更准） | 有 Figma 设计稿且样式还原成问题时 |
| CC Switch（非官方） | 可视化统一管理多 Agent 的 Provider/MCP/Skill，一键切换；可接 DeepSeek 等第三方模型 | 需要在多模型/多工具间切换时；重要项目先用测试仓库验证 |
第 3 章 Checklist
- 我能用"怎么做 vs 连接什么"瞬间判断该用 Skill 还是 MCP
- 我把"统一组件/色值/模板/工具库"写进了 Skill 或 AGENTS.md
- 我知道喂样式优先用 Figma MCP 而非截图，且了解 Code Connect 的前提
- 我按"先后顺序"引入工具，没有一上来堆一堆 Agent
- Plan Mode 已成为我改代码前的默认动作
第三部分 · 项目生命周期实战（主线）
从这里开始，每一章对应一个真实阶段，统一按六个小节展开：为什么 → 做什么 → Codex 如何参与 → 给 Codex 喂什么任务 → 产出什么 → 如何进入下一阶段，章末附 Checklist 与常见误区。照着做即可。
第 4 章 接手项目：启动与环境准备
为什么要这样做
环境没就绪、入口没找对，后面 AI 跑命令、装依赖、起服务全会卡壳。接手阶段的目标是：让项目能在本地/云端正常跑起来，并选定 Codex 的使用入口。
应该做什么
- 选定 Codex 入口：App（新手最推荐、功能最全）/ CLI / IDE 扩展 / Web·Cloud，按你的工作场景定。
- 确认运行环境：语言/运行时版本、包管理器、依赖安装、启动与构建命令。
- 准备代码托管：初始化或克隆 Git 仓库，确认分支策略。
- 配置必要的全局规则：把用户级
~/.codex/AGENTS.md（含防误删指令）准备好。
Codex 在这个阶段如何参与
让它帮你梳理"怎么把项目跑起来"：识别技术栈、推断安装/启动命令、检查缺失依赖。注意：此阶段只做环境就绪，不让它改业务代码。
应该输入什么类型的任务给 Codex
这是一个 [类型] 项目。请只做环境梳理，不要修改任何业务代码：
1. 判断技术栈和运行时版本要求
2. 给出安装依赖、启动、构建的命令
3. 指出当前缺失的环境依赖或配置
4. 如果有 .env 等需要我手动准备的文件，列出来但不要填写真实密钥
应该产出哪些文档或成果
- 一份"环境就绪说明"（安装/启动/构建命令、依赖清单）——可作为 AGENTS.md 的"常用命令"草稿。
- 可正常运行的本地/云端环境。
- 初始化好的 Git 仓库。
如何进入下一阶段
当项目能成功启动/构建、入口已选定，即可进入"理解项目"。
常见误区
- ❌ 环境还没跑通就急着让 AI 改代码。
- ❌ 把真实密钥写进让 AI 可见的文件。
第 4 章 Checklist
- Codex 使用入口已选定
- 安装/启动/构建命令已验证可用
- Git 仓库已就绪，分支策略已确认
- 用户级 AGENTS.md（含防误删）已配置
- 敏感信息未暴露给 AI
第 5 章 理解项目：项目认知
为什么要这样做
很多 Codex 任务失败，不是因为它不会写代码，而是因为它还没理解项目就被要求动手。 理解阶段的目标是：在写任何业务代码之前，让人和 AI 对项目结构达成共识。
应该做什么
让 Codex 先读项目、输出一份"项目理解报告"，你来核对它是否真看懂了。
Codex 在这个阶段如何参与
它负责通读代码并回答：技术栈是什么、入口文件在哪、核心模块在哪、测试/构建命令是什么、哪些文件不能随便动。
应该输入什么类型的任务给 Codex
（“读项目模板”，详见附录 B）
请先通读本项目，不要修改任何代码，输出一份项目理解报告，包含：
1. 技术栈与关键依赖
2. 目录结构与各目录职责
3. 程序入口与核心模块
4. 启动、测试、构建命令
5. 你认为"不应随意改动"的关键文件，并说明原因
6. 你对项目当前阶段和主要风险的判断
读完后等我确认，不要直接动手。
应该产出哪些文档或成果
- 项目理解报告（认知报告）。它是下一章生成 AGENTS.md 和责任田的原料。
如何进入下一阶段
校验四点后进入"建立文档"：① AI 是否看懂项目；② 技术栈判断是否正确；③ 启动方式是否清楚；④ 核心模块是否找对。任一不对，让它补读纠正。
常见误区
- ❌ 跳过理解，直接"帮我加个功能"。
- ❌ 看报告只扫一眼不核对——错误的认知会一路传导到后面所有改动。
第 5 章 Checklist
- 已拿到项目理解报告
- 技术栈、入口、核心模块判断均已人工核对正确
- 启动/测试/构建命令清楚
- "不能动的关键文件"已被识别
- AI 的认知与你的认知一致
第 6 章 建立文档：把文档体系落到本项目
为什么要这样做
理解只在"这次对话"里有效，下次新对话又归零。把理解沉淀成文档，AI 才有持久记忆。 这一章是把第 2 章的文档体系，真正落到当前项目——尤其要在"加新功能之前"做好，因为级联 bug 正是在无文档基线时迭代必然踩的坑。
关键时机：如果项目正处于"收尾 / 即将扩展功能"的节点，这一步最紧迫。趁代码还在脑子里、边界还清晰，先把责任田补上。
应该做什么
- 基于理解报告，建立根目录 AGENTS.md（全局规则）。
- 给每个页面/模块建立责任田文档（八字段）。
- 把风格约束（组件/token/模板/工具库）写进 AGENTS.md 或做成 Skill。
Codex 在这个阶段如何参与
让它读现有代码自动生成文档初稿，你负责审校边界——你最懂业务边界，AI 只负责把现状记录下来。
应该输入什么类型的任务给 Codex
基于你刚才的理解，帮我生成项目文档初稿，不要修改代码：
1. 一份根目录 AGENTS.md，包含：项目说明、技术栈、常用命令、目录结构、代码规范、UI 规则、禁止事项、完成任务后的输出要求
2. 为以下页面/模块各生成一份"责任田"文档，每份含：功能描述、入口、API 明细、依赖关系、影响范围、修改边界、注意事项、必须复用的组件/token/工具库
模块清单：[列出页面/模块]
生成后我会逐份核对边界，你先按现状如实记录，不要臆测。
应该产出哪些文档或成果
- 根目录
AGENTS.md - 每个模块一份责任田文档
- （可选）一组风格约束 Skill
如何进入下一阶段
当全局规则 + 各模块责任田齐备并经人工审校，文档地基完成，进入"规划需求"。此后每次迭代都站在这块地基上。
常见误区
- ❌ 文档让 AI 一键生成后不审校——边界字段最需要人把关。
- ❌ 责任田划得太碎或太粗（坚持页面/模块粒度）。
- ❌ 写完就不再更新（文档过期比没文档更危险）。
第 6 章 Checklist
- 根目录 AGENTS.md 已建立并审校
- 每个页面/模块都有责任田文档，八字段齐全
- "修改边界 / 不能动"字段经人工确认
- 风格约束已写入 AGENTS.md 或 Skill
- 文档已纳入版本管理，约定"迭代即更新"
第 7 章 规划需求：需求管理
为什么要这样做
用 Codex 翻车，多数不是它不会写，而是需求没说清。 你说"优化首页"，它可能去改 UI、改文案、改布局、改路由，甚至顺手删它觉得没用的代码。规划阶段的目标：把模糊愿望变成具体、可验收、有边界的需求。
应该做什么
把需求拆成五个关键问题（融合橙皮书"需求拆解"与群聊"留痕"）：
- 背景：现在什么阶段、遇到什么情况、为什么现在改、属于什么类型（UI/Bug/新功能/重构）。
- 要解决的具体问题：拒绝"优化""美化"这类词，写成可检验的描述。
- 相关文件：提前指明可能涉及的文件，减少 AI 全项目乱找。
- 不能动的部分：登录逻辑、接口地址、数据结构、路由、已有组件、依赖版本……给 AI 画边界。
- 完成标准：明确什么算做完。
留痕原则：如果有 Figma / 原型（RP），一并提供。AI 不懂你的前置逻辑，设计稿是它最可靠的意图来源（优先走 Figma MCP 而非截图）。
模糊 → 具体的对照：
| 模糊说法 | 更清楚的说法 |
|---|---|
| 优化首页 | 优化首屏标题、副标题和 CTA 按钮 |
| 页面不好看 | 调整卡片间距、字体层级、按钮样式 |
| 登录有问题 | 修复点击登录后没有跳转的问题 |
| 做一个后台 | 新增用户列表页，含搜索、筛选、分页 |
Codex 在这个阶段如何参与
让它基于责任田评估影响范围、补全你没想到的边界、产出需求文档。若用 OpenSpec，可在这一步生成 proposal/spec。
应该输入什么类型的任务给 Codex
我要做一个需求，先不要写代码，帮我把它整理成需求文档：
- 背景：[…]
- 要解决的具体问题：1)… 2)… 3)…
- 我认为相关的文件：[…]
- 绝对不能改动的部分：[…]
- 完成标准：[…]
请先读相关模块的责任田文档，然后：
1. 评估这次改动的影响范围（会牵动哪些模块）
2. 指出我可能遗漏的边界或风险
3. 输出一份结构化需求文档，等我确认
应该产出哪些文档或成果
- 需求文档（含背景/问题/相关文件/边界/完成标准/影响范围）。模板见附录 A。
如何进入下一阶段
需求文档经你确认、边界清晰、完成标准可验收后，进入"拆分任务"。
常见误区
- ❌ 用"优化/美化/改好点"这类无法验收的词。
- ❌ 不写"不能动什么"，等于默许 AI 顺手改别处。
- ❌ 喂截图让它猜样式（用 Figma MCP）。
第 7 章 Checklist
- 需求已具体到可验收，无"优化/美化"等模糊词
- 背景、相关文件、完成标准均已写清
- "不能动的部分"明确列出
- 有设计稿的已通过 Figma MCP 提供
- 已评估影响范围并形成需求文档
第 8 章 拆分任务：任务拆分与责任划分
为什么要这样做
Codex 适合连续完成小任务，而不是一次吞下大项目。 一次改太多 = 出错概率高 + 无法回滚 + diff 难审查。拆分阶段把需求切成"一次只动一块、可独立测试"的小任务。
应该做什么
- 按责任田边界，把需求拆成若干小步任务，每步只触及一个模块。
- 明确每个任务的责任边界：改哪、不改哪、依赖谁、完成标准。
- 排好顺序与依赖（先底层后上层、先核心后边缘）。
Codex 在这个阶段如何参与
让它基于需求文档和责任田产出任务清单（计划），这正是 Plan Mode 的用武之地：先列计划、你确认、再执行。
应该输入什么类型的任务给 Codex
基于需求文档和相关责任田，进入计划模式，先不要写代码：
1. 把这个需求拆成多个小任务，每个任务只改一个模块
2. 每个任务标注：涉及文件、修改边界、依赖关系、完成标准
3. 给出建议的执行顺序，并说明每步如何独立验证
输出任务清单，等我确认后再逐个执行。
应该产出哪些文档或成果
- 任务清单 / 执行计划（含每步边界与验证方式）——可并入需求文档或单独留档。
如何进入下一阶段
当任务清单粒度足够小、责任边界清晰、顺序合理且经确认，进入"AI 协作开发"，逐个执行。
常见误区
- ❌ 把一个大需求当一个任务整体丢给 AI。
- ❌ 任务之间边界重叠，导致改 A 时动到 B。
- ❌ 跳过 Plan Mode 直接让它开干。
第 8 章 Checklist
- 需求已拆成"一次只改一块"的小任务
- 每个任务有明确的涉及文件与修改边界
- 任务顺序与依赖已理清
- 每步都有独立验证方式
- 计划已经过 Plan Mode 产出并人工确认
第 9 章 AI 协作开发：与 Codex 一起写代码
为什么要这样做
这是真正动手的阶段，也是最容易失控的阶段。目标：让 AI 按既定计划、在边界内、小步实现，且全过程可见、可控、可回滚。
应该做什么（标准节奏）
对任务清单里的每一个小任务，重复这条循环：
- 让 AI 先读对应责任田，复述边界（确认它没跑偏）。
- Plan Mode 出本任务的具体方案，你确认。
- 小步实现：只改这一块。
- 立即自测（跑命令 + 必要的手动验证）。
- 看 diff（进入第 10 章 Review）。
- 没问题再做下一个任务。
Codex 在这个阶段如何参与
它是执行主体：读边界 → 出方案 → 改代码 → 跑命令 → 给 diff。人始终保留"方案确认"和"diff 审查"两道闸。
应该输入什么类型的任务给 Codex
现在执行任务 [N]：[任务描述]
约束：
- 先读 [模块] 的责任田，复述本次修改边界，确认后再动手
- 只改 [指定文件/模块]，不要触碰：[不能动的清单]
- 必须复用已封装的组件/token/工具库，不引入第三方库
- 改完运行 [测试/构建命令]
完成后请输出：改了哪些文件、每个文件改了什么、为什么这样改、是否需要构建、并提醒我看 diff。
应该产出哪些文档或成果
- 实现好的代码改动（一个任务一组小 diff）。
- 每个任务的"改动说明"（哪些文件/改了什么/为什么）——汇入变更记录。
如何进入下一阶段
当单个任务实现完成、自测通过，进入该任务的 Review；全部任务完成后进入整体测试。
常见误区
- ❌ 让它一口气把所有任务做完再看（应一步一审）。
- ❌ 允许它"顺手"重构无关代码或新增大依赖。
- ❌ 忽略它复述边界这一步——这是它有没有跑偏的早期信号。
第 9 章 Checklist
- 每个任务都先读责任田、复述边界
- 每个任务都经 Plan Mode 出方案并确认
- 始终一次只改一块，改完即自测
- 风格约束（组件/token/工具库）被遵守
- 每个任务都有清晰的改动说明
第 10 章 代码 Review 与 PR
为什么要这样做
AI 改得快，但它可能改到不该改的地方。 Review 是人保留的最后一道闸：确认改得对、范围没越界、没有顺手破坏别处。这也是把"原则 2：人拍板"落到实处的环节。
应该做什么
- 逐个 diff 审查：只看本任务该改的范围，警惕越界改动。
- 对照需求文档的"完成标准"和责任田的"修改边界"核验。
- 整理成 PR，写清改了什么、为什么、风险点。
Codex 在这个阶段如何参与
- 让它先自查 diff：解释每处改动、标出潜在风险、确认是否越界。
- 让它生成 PR 说明（本次修改 / 测试结果 / 风险说明）。
- 可把"Code Review / UI Review"做成 Skill，固定审查清单。
应该输入什么类型的任务给 Codex
对本次改动做一次自查 Review：
1. 逐文件解释改了什么、为什么
2. 是否有超出本任务边界的改动？若有，列出并说明
3. 是否触碰了"不能动"清单里的内容？
4. 潜在风险与回归影响范围
5. 生成 PR 说明：## 本次修改 / ## 测试结果 / ## 风险说明
应该产出哪些文档或成果
- Review 记录（审查结论 + 风险）。
- PR 说明（本次修改 / 测试结果 / 风险说明）。
如何进入下一阶段
当 diff 无越界、符合完成标准、风险已知，PR 说明就绪，进入"测试与验证"（或在测试通过后合并）。
常见误区
- ❌ 不看 diff 直接提交/合并。
- ❌ 只看"功能实现了"，不看"有没有顺手改坏别处"。
- ❌ PR 说明空洞，后人无法追溯。
第 10 章 Checklist
- 已逐 diff 审查，无越界改动
- 改动符合需求完成标准与责任田边界
- AI 自查 Review 已完成并人工复核
- PR 说明含"本次修改/测试结果/风险说明"
- Review 结论已留档
第 11 章 测试与验证
为什么要这样做
“改完了"不等于"能交付”。测试阶段确认：原报错消失、新功能走得通、没引入回归。
应该做什么
- 跑自动化检查（构建、lint、单测）。
- 按需求"完成标准"做手动验证（关键路径走一遍）。
- 必要时补测试覆盖（单测、边界、异常场景）。
Codex 在这个阶段如何参与
- 让它跑测试并报告结果。
- 让它补测试：但加边界——不改业务逻辑、不改公共 API、不引无关依赖，补完必须跑通。
- 失败时让它做"根因定位"，而不是盲目改。
应该输入什么类型的任务给 Codex
运行 [测试/构建命令] 并报告结果。若失败：
1. 定位根因（指出具体文件与原因），先别急着改
2. 给出修复方案，等我确认
另外，为本次改动补充测试：
- 覆盖正常路径、关键边界和异常场景
- 不改动业务逻辑和公共 API，不新增无关依赖
- 补完后运行测试，确认全部通过
应该产出哪些文档或成果
- 测试结果记录（通过/失败、覆盖了什么）。
- 新增/更新的测试代码。
如何进入下一阶段
当构建通过、关键路径手动验证通过、相关测试为绿，进入"上线与发布"。
常见误区
- ❌ 只信"AI 说通过了"，不亲自跑一遍关键路径。
- ❌ 补测试时顺带改了业务逻辑。
- ❌ 测试失败时让 AI 乱试，而不先定位根因。
第 11 章 Checklist
- 构建 / lint / 单测均通过
- 需求"完成标准"对应的关键路径已手动验证
- 新增测试覆盖正常/边界/异常
- 测试未顺带改动业务逻辑
- 测试结果已留档
第 12 章 上线与发布
为什么要这样做
发布是把成果交到用户手里的一步，环境与适用性判断错了会直接出事故。
应该做什么
- 选对发布方式与环境：静态站（HTML/CSS/JS）可用 GitHub Pages 等静态托管；带后端/数据库/敏感交易的业务不能用纯静态托管，需对应的服务端部署。
- 走标准 Git 流程：提交 → 推送 → （PR 合并）→ 部署。
- 发布后做线上冒烟验证。
Codex 在这个阶段如何参与
- 让它执行/校对 Git 与部署命令（提交、推送、打 tag）。
- 让它生成发布说明 / changelog。
- 仍受防误删、不暴露密钥等全局约束。
应该输入什么类型的任务给 Codex
准备发布本次改动：
1. 整理提交信息（简洁说明本次变更）
2. 给出推送与部署步骤（基于本项目的部署方式）
3. 生成本次发布说明 / changelog
注意：不要暴露任何密钥；涉及生产环境的破坏性命令先停下来让我确认。
应该产出哪些文档或成果
- 发布说明 / changelog。
- 成功发布的线上版本。
如何进入下一阶段
发布成功、线上冒烟通过后，进入"后期维护"——并在下一次需求到来时回到第 7 章，形成闭环。
常见误区
- ❌ 把带后端的业务部署到只能托管静态站的平台。
- ❌ 发布命令里夹带危险/破坏性操作未经确认。
- ❌ 发布后不做线上验证。
第 12 章 Checklist
- 发布方式与项目类型（静态/带后端）匹配
- Git 提交/推送/部署流程已走通
- 发布说明/changelog 已生成
- 线上冒烟验证通过
- 全程未暴露敏感信息
第 13 章 后期维护与迭代：防级联、控质量
为什么要这样做
项目真正的考验在长期迭代：改 A 引发 B、C 几乎都发生在维护期。这一章的核心是让每次迭代都"站在文档地基上"，并保持文档与代码同步。
应该做什么
- 迭代前先读旧逻辑：让 AI 先读对应责任田，了解历史与边界，再动手。
- 沿用同一条链路：维护期的每个改动，依然走"规划→拆分→开发→Review→测试→上线"。
- delta 思维：每次只改增量，明确标注 ADDED/MODIFIED/REMOVED（OpenSpec 的思路），不整体重写。
- 文档维护：改完同步更新对应责任田与变更记录。文档过期会让后续所有判断失真。
- 沉淀经验：把反复出现的坑写进 AGENTS.md / Skill。
Codex 在这个阶段如何参与
- 迭代起点让它"读历史 + 评估影响范围"。
- 改完让它"同步更新责任田/变更记录"。
- 让它定期"体检"：找出文档与代码不一致之处。
应该输入什么类型的任务给 Codex
我要在 [模块] 上做一次迭代：[需求]
请先读该模块的责任田和最近的变更记录，然后：
1. 复述当前逻辑和历史注意事项
2. 评估本次改动的影响范围（会牵动哪些模块）
3. 进入计划模式给出方案，等我确认
（执行完成后，记得同步更新该模块责任田与变更记录。）
定期维护任务：
对比 [模块] 的责任田文档与当前代码，列出不一致之处（接口、依赖、边界变化），给出更新建议，不要直接改代码。
应该产出哪些文档或成果
- 更新后的责任田文档。
- 持续累积的变更记录。
- 不断丰富的 AGENTS.md / Skill（经验沉淀）。
如何进入下一阶段
维护是循环：每完成一轮，回到第 7 章规划下一个需求。判断"健康"的标准是——文档始终与代码同步，且每次改动都能追溯。
常见误区
- ❌ 维护期图快，跳过读历史和 Plan Mode 直接改。
- ❌ 改了代码不更新文档，地基慢慢腐烂。
- ❌ 用"重写整块"代替"改增量"，引入大面积风险。
第 13 章 Checklist
- 每次迭代都先读责任田/变更记录再动手
- 维护改动仍走完整链路，未走捷径
- 改动以 delta 增量进行，标注清晰
- 责任田与变更记录已同步更新
- 反复出现的坑已沉淀进 AGENTS.md / Skill
第四部分 · 沉淀
第 14 章 《Codex 标准工作流（SOP）》
把全书浓缩成一张可贴在墙上的执行标准。以后所有项目统一照此执行。
14.1 一图流
【0 准备】环境就绪 + 用户级 AGENTS.md(防误删)
↓
【1 理解】读项目 → 项目理解报告 → 人工核对四点
↓
【2 建档】根目录 AGENTS.md + 各模块责任田(八字段) + 风格约束 ← 文档地基
↓
【3 规划】需求五问(背景/问题/相关文件/不能动/完成标准) → 需求文档
↓
【4 拆分】Plan Mode → 小任务清单(每步边界+顺序+验证)
↓
【5 开发】对每个任务循环：读责任田→出方案→小步改→自测→看diff
↓
【6 Review】逐diff审查 + AI自查 + PR说明(修改/测试/风险)
↓
【7 测试】构建/单测 + 关键路径手动验证 + 补测试 → 测试记录
↓
【8 上线】发布方式匹配项目类型 → 提交/推送/部署 → 线上冒烟
↓
【9 维护】先读历史→评估影响→delta改动→同步文档→沉淀经验
↓
└──────────── 下个需求回到【3 规划】，闭环 ────────────┘
14.2 九阶段速查表
| 阶段 | 核心动作 | 给 Codex 的任务类型 | 产出 | 进入下一步的条件 |
|---|---|---|---|---|
| 0 准备 | 环境就绪 | 环境梳理（不改代码） | 命令清单、Git 仓库 | 项目能启动/构建 |
| 1 理解 | 读项目 | 输出理解报告 | 项目理解报告 | 四点核对通过 |
| 2 建档 | 落文档地基 | 生成 AGENTS.md/责任田初稿 | AGENTS.md、责任田 | 文档审校完成 |
| 3 规划 | 需求具体化 | 整理需求+评估影响 | 需求文档 | 需求可验收、边界清晰 |
| 4 拆分 | Plan Mode 拆任务 | 出任务清单 | 任务清单 | 粒度小、顺序清、已确认 |
| 5 开发 | 小步实现 | 逐任务执行（带边界） | 小 diff + 改动说明 | 单任务自测通过 |
| 6 Review | 审 diff + 出 PR | 自查 + 生成 PR 说明 | Review 记录、PR | 无越界、符合标准 |
| 7 测试 | 验证 | 跑测试+补测试 | 测试记录 | 构建绿、关键路径通过 |
| 8 上线 | 发布 | 提交/部署/changelog | 发布说明、线上版本 | 冒烟通过 |
| 9 维护 | 闭环迭代 | 读历史+delta 改+更文档 | 更新的文档/变更记录 | 文档与代码同步 |
14.3 三条不可妥协的铁律（出问题先查这三条）
- 没读懂不动手，没计划不改码（理解 + Plan Mode）。
- 动手前先画边界（不能动什么 > 要做什么）。
- 一步一审，文档同步（小步 + 看 diff + 更新责任田）。
附录
附录 A 文档模板合集
A.1 AGENTS.md（项目根目录）
# AGENTS.md
## 项目说明
[一句话说明这个项目是什么]
## 技术栈
- [语言 / 框架 / 构建工具 / 关键依赖]
## 常用命令
- 安装依赖：[…]
- 启动：[…]
- 构建：[…]
- 测试：[…]
## 项目结构
- [目录]：[职责]
## 代码规范
- 优先复用已封装的组件，不重复造
- 样式必须使用 [color token / 设计系统]，不写死色值
- 生成代码遵循 [模板/约定]
- 工具能力使用已封装库，不随意引第三方
- 不大范围重构无关代码
## UI 规则
- 信息层级清晰；按钮/卡片/标题/留白统一
- 移动端基本可用
- 不要过度渐变/阴影/AI 模板感，优先真实产品感
## 禁止事项
- 不修改 .env / 密钥文件，不输出任何密钥
- 不删除已有核心功能
- 不随意新增大型依赖
- 不改动与当前任务无关的文件
## 完成任务后必须输出
1. 改了哪些文件 2. 每个文件改了什么 3. 为什么这样改
4. 是否需要构建/测试 5. 提醒我检查 diff
A.2 责任田文档（每个页面/模块一份）
# 责任田：[模块/页面名]
## 功能描述
[这块负责什么]
## 入口
[路由 / 组件 / 调用入口]
## API 明细
[依赖的接口、关键字段]
## 依赖关系
- 依赖：[…]
- 被依赖：[…]
## 影响范围
[改动这里可能牵动的模块/功能]
## 修改边界
- 可以改：[…]
- 绝对不能动：[…]
## 注意事项
[历史坑、特殊逻辑]
## 约束
- 必须复用：[组件 / token / 工具库]
A.3 需求文档
# 需求：[标题]
## 背景
- 当前阶段：[…] 当前情况：[…] 为什么现在做：[…] 类型：[UI/Bug/新功能/重构]
## 要解决的具体问题
1. … 2. … 3. …
## 相关文件
[…]
## 不能动的部分
[…]
## 完成标准
[可验收的描述]
## 影响范围（由 Codex 评估后补充）
[…]
A.4 变更记录 / PR 说明
## 本次修改
- [改了哪些文件，做了什么]
## 测试结果
- [跑了什么、结果如何、手动验证了哪些路径]
## 风险说明
- [潜在回归、需要关注的边界]
A.5 Skill 基本结构
# Skill 名称
## 适用场景
[这个 Skill 用来做什么]
## 工作目标
[最终要交付什么]
## 工作流程
1. 分析输入 2. 确认任务类型 3. 按固定步骤处理 4. 输出结果与检查清单
## 输出格式
[规定输出形态]
## 注意事项
[不能做的事、要提醒的风险]
A.6 用户级 AGENTS.md 防误删片段
禁止批量删除文件或目录。不要使用 rm -rf、del /s、rd /s、rmdir /s、Remove-Item -Recurse。
需要删除时只能一次删除一个明确路径的文件；如需批量删除，停止并请求用户手动处理。
附录 B 任务（Prompt）模板库
直接复制、填空使用。原则：先读、先计划、带边界、要 diff。
B.1 读项目
请先通读本项目，不要改代码，输出理解报告：技术栈、目录职责、入口与核心模块、启动/测试/构建命令、不应随意改动的关键文件及原因、当前阶段与主要风险。读完等我确认。
B.2 生成文档
基于你的理解，生成根目录 AGENTS.md 和各模块责任田初稿（八字段），按现状如实记录，不要臆测，不要改代码。
B.3 整理需求
把以下需求整理成需求文档并评估影响范围（先读相关责任田，不写代码）：背景[…]、要解决的问题[…]、相关文件[…]、不能动的部分[…]、完成标准[…]。指出我可能遗漏的边界与风险。
B.4 拆任务（Plan Mode）
进入计划模式，把需求拆成"一次只改一块"的小任务，每个标注涉及文件/边界/依赖/完成标准，并给出执行顺序与各步验证方式。先别写代码。
B.5 执行单任务
执行任务[N]：[描述]。先读[模块]责任田并复述边界。只改[文件]，不要碰[清单]。复用已封装组件/token/工具库，不引第三方。改完跑[命令]。输出改动说明并提醒我看 diff。
B.6 自查 Review + PR
对本次改动自查：逐文件解释改了什么/为什么；是否有越界改动；是否碰了"不能动"清单；潜在回归风险。最后生成 PR 说明（## 本次修改 / ## 测试结果 / ## 风险说明）。
B.7 测试与补测
运行[测试命令]并报告。失败先定位根因再等我确认。为本次改动补测试（正常/边界/异常），不改业务逻辑与公共 API，不引无关依赖，补完跑通。
B.8 维护迭代
在[模块]做迭代：[需求]。先读责任田与最近变更记录，复述当前逻辑与历史注意事项，评估影响范围，进入计划模式给方案等我确认。完成后同步更新责任田与变更记录。
附录 C 推荐工具链与第三方模型接入
| 工具 | 作用 | 何时引入 | 备注 |
|---|---|---|---|
| Plan Mode | 改码前出方案、确认再执行 | 第一优先，必用 | 整套方法的核心节奏 |
| AGENTS.md + Skill | 全局规则 + 风格约束 | 建档阶段 | 根治风格漂移 |
| OpenSpec | spec-driven，delta 增量改动 | 想固化"先 spec 后实现" | brownfield 友好，Codex 支持 |
| Superpowers | brainstorm→plan→TDD→review 自动技能 | 想要更强流程纪律 | Codex 有官方插件市场 |
| oh-my-codex | 多 Agent 编排 | 任务并行需求出现后 | — |
| Figma Dev Mode MCP | 设计稿结构化喂给 AI | 有设计稿且样式还原难 | 配 Code Connect 才真正准，否则样式仍可能大幅偏差 |
| CC Switch（非官方） | 统一管理多 Agent 的 Provider/MCP/Skill | 需多模型/工具切换 | 非官方，重要项目先用测试仓库验证；可接 DeepSeek 等 |
引入顺序就是上表从上到下。先把 Plan Mode + 文档 + 约束跑通（前三行），其余按需再加。
附录 D 常见误区速查表
| 误区 | 正确做法 | 出处阶段 |
|---|---|---|
| 一句话"帮我做个项目"丢过去 | 走完整链路，先理解再规划 | 全流程 |
| 没读懂项目就动手 | 先出理解报告并核对 | 理解 |
| 需求写"优化/美化/改好点" | 写成可验收的具体描述 | 规划 |
| 不写"不能动什么" | 动手前先画边界 | 规划/拆分 |
| 一次改一大片 | 小步快跑，每步可回滚 | 开发 |
| 截图喂样式让 AI 猜 | 用 Figma MCP（配 Code Connect） | 规划/开发 |
| 不看 diff 就提交 | 逐 diff 审查 + AI 自查 | Review |
| 只信"AI 说测过了" | 亲自跑关键路径 | 测试 |
| 带后端业务部署到静态托管 | 发布方式匹配项目类型 | 上线 |
| 改完不更新文档 | 责任田/变更记录即时同步 | 维护 |
| 维护期图快跳过流程 | 维护仍走完整链路 | 维护 |
| 一上来堆一堆 Agent/工具 | 先跑通主流程再加自动化 | 全流程 |
| 允许 AI 顺手重构/加大依赖 | 明确禁止，严控范围 | 开发 |
| 让 AI 随意批量删除 | 全局防误删指令 | 准备/全程 |
附录 E 全流程总检查清单
地基（开工前）
- 用户级 AGENTS.md（含防误删）已配置
- 项目能启动/构建，Git 就绪
- 项目理解报告已核对
- 根目录 AGENTS.md + 各模块责任田齐备且审校
每次迭代
- 需求已具体到可验收，边界清晰（含"不能动"）
- 有设计稿的走 Figma MCP
- Plan Mode 拆出小任务并确认
- 逐任务：读责任田→出方案→小步改→自测→看 diff
- 风格约束被遵守，无越界改动
- AI 自查 Review + 人工复核 + PR 说明齐全
- 构建绿、关键路径手动验证通过
- 发布方式匹配项目类型，线上冒烟通过
- 责任田与变更记录已同步更新
- 反复出现的坑已沉淀进 AGENTS.md / Skill
一句话总纲：让 Codex 当执行者，人来定方向、画边界、做验收；用文档喂上下文，用 Plan Mode 控节奏，用小步和 diff 控风险，用责任田防级联。把这套流程固定下来，AI 协作开发就从"靠运气"变成"靠标准"。
汇聚全球AI编程工具，助力开发者即刻编程。
更多推荐
0
0- 0
已为社区贡献1条内容
所有评论(0)