第20课:架构模板复用、常见踩坑与学习路径闭环

系列走到最后一课。这课不教新功能，而是帮你把前面 19 课的积累"收口"：学会复用、避开踩坑、看清边界，并给自己一条可持续的学习路径。

TL;DR（太长不看）：本课是系列完结篇，帮你把前 19 课积累"收口"。核心四件事：① 学会复用成熟项目架构模板，别每次都从零开始；② 避开需求太模糊、上下文失控、权限一刀切、忽略验证、环境没配好五大常见踩坑点；③ 看清 Codex 的能力边界——擅长可拆解、可验证的任务，关键判断永远留给人；④ 按"基础 → 扩展 → 实战 → 协同"四阶段形成学习路径闭环。文末附有术语速查表，可随时对照回顾。

一、架构模板复用：别每次都从零开始

成熟项目的价值不仅在它能跑，更在它的结构可以被复用。用 Codex 时尤其如此：

• 把验证过的项目结构固化成模板；
• 新项目基于模板起步，让 Codex 在既定框架内填充；
• 结合 AGENTS.md、PLAN.md，形成"模板 + 规范 + 计划"的复利组合。

复用的本质，是把一次性经验沉淀为可重复的生产力。

下面用 Codex CLI 演示，一条命令即可基于既有模板初始化新项目：

# 基于 project-template 模板初始化 my-new-project# 触发流程：# 1. 复制模板目录结构到新项目# 2. 自动加载模板中的 AGENTS.md，作为本次会话的项目规范# 3. 自动加载 PLAN.md，作为可执行计划上下文# 4. 在既定框架内开始填充新项目代码codex exec --template project-template --output my-new-project

二、常见踩坑点

结合真实使用，这些坑最常出现：

1. 需求太模糊
   ：指望 Codex 猜出你想要什么，结果返工；
2. 上下文失控
   ：会话越拉越长，token 花钱、结果还跑偏；
3. 权限一刀切
   ：要么全程只读憋得难受，要么全自动改了不该改的；
4. 忽略验证
   ：盲目相信输出，没跑测试就交付；
5. 环境没配好
   ：Node、Git、认证没弄对，第一步就卡住。

好在这些坑，前面每一课其实都给了对应的解法——回到对应课程复习即可。

实战对照：把模糊需求拆到可执行

先看一个反面案例。

反面指令：需求太模糊

codex exec "帮我把登录做好"

这类指令下，Codex 只能靠猜，典型结果是：

• 自己选框架、自己定数据库；
• 生成一套未经确认的账号密码规则；
• 返回一堆代码，却没有明确验收标准。

最终方向不对、范围失控，只能返工。

正面指令：目标、范围、验收标准都写清楚

# 1. 指定模板与输出目录：基于 project-template 初始化 my-new-project# 2. 会话开始自动加载模板内 AGENTS.md，锁定技术栈与协作规范# 3. 自动加载 PLAN.md，把目标、步骤、验收标准注入任务上下文# 4. 使用多行指令，按“目标 → 范围 → 步骤 → 验收”逐项写清，避免模糊需求codex exec --template project-template --output my-new-project \  "基于现有 Express + SQLite 模板，新增邮箱密码登录：1. 数据表 users，包含 email、password_hash 字段；2. 注册：校验邮箱格式，密码使用 bcrypt 加密；3. 登录：校验成功后签发 JWT；4. 验收：跑通 npm test，全部通过后再提交。"

这样写之后，Codex 的输出会明显更可控：

• 先停在计划阶段，给出待修改文件清单；
• 再按步骤生成代码；
• 最后执行测试并给出结果。

用 AGENTS.md + PLAN.md 避免返工

# AGENTS.md（项目规范，固定到仓库）- 技术栈固定：Express + SQLite + bcrypt + jsonwebtoken；- 接口必须带错误码与测试用例；- 未跑通 npm test 不允许结束任务。# PLAN.md（每次任务开始前先写）- 目标：新增邮箱密码登录；- 步骤：建表 → 注册接口 → 登录接口 → JWT；- 验收：npm test 全绿，且能用 curl 完成一次注册/登录。

先写好规范和计划，Codex 就有了上下文与验收标准，返工自然会少很多。相关做法可回看第 9–15 课。

执行后的预期输出

基于上面的命令、AGENTS.md 与 PLAN.md，Codex 会先产出计划，再逐项执行。一个典型的结果如下：

# 1. 模板初始化：复制 project-template 结构到 my-new-project# 2. 自动加载 AGENTS.md：技术栈与开发规范已生效# 3. 自动加载 PLAN.md：目标、步骤、验收标准已注入# 4. Codex 先给出待办清单，不直接写代码Todo- [ ] 新建数据表 users：email、password_hash- [ ] 实现注册接口 POST /register：邮箱校验 + bcrypt 加密- [ ] 实现登录接口 POST /login：校验密码 + 签发 JWT- [ ] 编写测试用例并运行 npm test# 5. 生成/修改文件清单已修改文件：- src/db.js           # 定义 users 表结构- src/routes/auth.js  # 注册、登录接口- src/middleware.js   # JWT 校验中间件- test/auth.test.js   # 注册/登录测试用例# 6. 执行验证：npm test 全部通过后才交付npm testPASS  test/auth.test.js  ✓ 注册成功并 bcrypt 加密存储  ✓ 邮箱格式错误返回 400  ✓ 登录成功签发 JWT  ✓ 错误密码返回 401Test Suites: 1 passed, 1 totalTests:       4 passed, 4 total

这里的核心是计划先行、清单可见、验证兜底：每一步都有明确注释和验收依据，Codex 没有随意发挥的空间，返工自然大幅减少。

三、看清能力边界

Codex 强，但不是万能。清楚它的边界，才能用得长久：

• 擅长
  ：有上下文、可拆解、可验证的任务；
• 不擅长
  ：完全开放、无验收标准、高度依赖主观判断的事；
• 最怕
  ：假性精确——它可能自信地给出错误结果。

所以，永远把关键判断留给人，把重复执行交给 AI。

四、你的学习路径闭环

最后，给你一条可执行的进阶路径，形成闭环：

第 1 阶段：掌握基础（第 1‒8 课）——安装、模式、命令、权限第 2 阶段：扩展能力（第 9‒15 课）——MCP、AGENTS.md、Skill 体系第 3 阶段：业务实战（第 16‒18 课）——商业、项目、多端开发第 4 阶段：进阶协同（第 19‒20 课）——并行、编排、复用

每个阶段都"学完就用、用了再沉淀"，再用附录的常用命令速查和术语解释辅助回顾。

下一步行动清单

• ① 用模板初始化一个新项目并跑通：基于已有模板执行 codex exec --template project-template --output my-new-project，把项目跑起来，验证模板复用的完整流程；
• ② 为现有项目补一份 AGENTS.md：把技术栈、协作规范、验收标准写进 AGENTS.md 并纳入版本管理，让后续会话自动加载、减少返工；
• ③ 用 Codex 完成一次带验收标准的任务并记录结果：挑一个真实小需求，写清目标、范围、步骤与验收标准，跑通后把过程与结果沉淀下来，形成自己的经验库。

五、写在最后 FAQ

Q1：模板需要持续更新吗？怎么维护？ 建议把验证过的目录结构、AGENTS.md 与 PLAN.md 一起纳入 Git 等版本管理。每次踩坑后把解法回填到模板，再让 Codex 基于新版模板初始化新项目，团队规范就能持续复用。可回到第 9–15 课的 AGENTS.md、PLAN.md 与第 20 课的模板复用复习。

Q2：Codex 权限怎么配置更安全？ 从最小权限开始：先用「只读 / 建议」模式让 Codex 输出方案，确认无误后再逐步放开执行；涉及删除、提交等关键操作保留人工确认，避免默认全自动。可参照第 1–8 课的权限配置。

Q3：怎么判断一个任务适不适合交给 Codex？ 看三个条件：有没有明确上下文、能不能拆成清晰步骤、有没有可验证的验收标准。满足就交给 Codex 重复执行；完全开放、只靠主观判断的任务，关键决策留给自己。可结合第 9–15 课与第 16–18 课的能力边界与项目实战理解。

六、写在最后

恭喜你走完整个系列。你学到的不是一个工具的按钮，而是一套**"与人协作"之外、全新的"与 AI 协作"的思维与方法**。

工具会迭代，但这套方法会一直有用。从今天起，把 Codex 用进你的真实工作里，然后，去造属于你自己的 Skill 吧。

如果阅读过程中对某些概念感到模糊，别急着翻回去——文末的**「七、术语速查表」**已把本系列高频术语整理成表，可随时对照回顾。例如对「模板」「上下文」等概念有疑问，可回看对应课程，快速定位到讲解位置。

七、术语速查表

本系列高频术语整理如下，方便回顾：

本文是《OpenAI Codex 从零基础到精通》第 20 课（完结篇）。感谢阅读，欢迎收藏、转发本系列。