Codex 实战笔记（后端开发工程师版）

一句话：Codex 是终端里的编码 Agent——读得懂整个仓库，跑得了命令，改完自己验证。脉络：为什么学 → 怎么装 → 怎么读项目 → 怎么跑闭环 → 怎么管上下文 → 怎么搭积木 → 怎么做团队复用官方手册：https://learn.chatgpt.com/docs/codex/cli

1. 为什么学：先建心智模型

核心思想

Codex 不是聊天窗口，而是"能看懂你仓库的结对工程师"。后端日常高频场景全覆盖：理解老代码、写单测、重构接口、排障、code review。它看得见 git 状态和报错，改完能自己跑测试确认。

Agent 由四部分构成，也是后面所有小节的线索：

部件	对应能力	后文位置
大脑	推理与规划（模型）	全程
手脚	连接与执行（Tools / MCP）	§3、§6
记忆	上下文与规范（Context / AGENTS.md / Skills）	§5、§6
流程	验证与汇报（Skills / Hooks）	§4、§6

2. 怎么装

核心思想：装一个 CLI，登录后即可在项目根目录使用。

执行命令

1
2
3
4
npm install --global @openai/codex   # 安装 Codex CLI
codex login                          # ChatGPT 账号或 API key 登录
codex --version                      # 验证安装
codex doctor                         # 环境出问题时的诊断命令

安装后在项目根目录运行 codex 进入交互界面。

3. 怎么读项目

核心思想：先让 Codex 建立全局理解并复述给你，确认后再深入细节；大仓库用代码图谱按符号查源码和调用链，代替肉眼翻代码。

怎么做

树状结构：让 Codex 列出项目结构并说明模块职责（可落盘到 project_tree.md）
全局理解：让 Codex 复述它理解的项目情况，先不要改
符号级探索：装 CodeGraph 建索引后，按符号名直接查源码和调用路径
原则：先理解、再计划、最后才动手

示例 Prompt

“以树状结构列出项目结构，说明每个模块的职责，保存到 project_tree.md” “先读项目结构和现有代码，复述你理解的项目情况，先不要改”

执行命令（CodeGraph：仓库级代码图谱，npm 包 @colbymchenry/codegraph）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# 安装并接入 Codex CLI（自动配置 MCP server）
npm install --global @colbymchenry/codegraph
codegraph install -y

# 在项目根初始化索引（生成 .codegraph/，代码变化后增量同步）
codegraph init
codegraph status        # 索引状态
codegraph sync          # 代码有变化时同步索引

# 日常查询
codegraph files                              # 项目文件结构
codegraph explore "orderService"             # 相关符号源码 + 调用路径（最常用）
codegraph node <symbol>                      # 单个符号 + 调用者/被调用者
codegraph callers <symbol>                   # 谁调用了它
codegraph impact <symbol>                    # 改动它会影响哪些代码
codegraph affected <files>                   # 哪些测试会受影响

4. 怎么跑闭环（核心工作流）

核心思想：让 Codex 按「目标 → 计划 → 最小改动 → 验证 → 总结」闭环工作，而不是让它一把梭。Prompt 只需四要素：Goal（改什么）、Context（相关文件/报错）、Constraints（规范、最小改动）、Done when（验收标准）。

怎么做

先要计划，确认后再开发
按计划做最小改动，不做无关开发
跑验证命令，确认未破坏现有功能
让它总结：修改了什么、修改原因、怎么验证、验证结果
出问题时先让它分析原因，不要急着改

示例 Prompt

“给我一个开发计划，先不要直接开发” “按计划修改，保持代码简洁，不做无关开发” “运行测试命令，确认本次修改未破坏现有功能” “总结：修改了什么、修改原因、怎么验证、验证结果” “页面白屏了，控制台报错，先分析原因，不要急着改”

执行命令

1
2
3
npm test
npm run build
npx eslint ./src

复杂任务先 /plan 进入计划模式，改完用 /review 自审 diff。

5. 怎么管上下文

核心思想：上下文是"好钢用在刀刃上"——主会话只放目标、约束和决策，探索日志、报错堆栈别堆进来，否则信息会被淹没。

怎么做

继续任务时沿用之前的分析和计划，不重新解释
每个阶段完成，让它主动总结「目标 / 已完成 / 关键决策 / 剩余问题」
会话状态不对时，用斜杠命令快速切换

示例 Prompt

“继续当前任务，沿用之前的分析和计划”

执行命令

1
2
3
4
codex resume          # 恢复上次会话；或会话内用 /resume
/clear                # 思路带偏、反复修改无效时清空重来（会开新会话）
/compact              # 长会话压缩摘要，释放 token
/status               # 查看模型、权限、剩余上下文

6. 怎么搭积木（经验固化）

核心思想：一次做对不算数，把规则、流程、连接、守门、并行五类积木固化下来，Codex 才会越用越顺手。

6.1 规则：AGENTS.md

项目根建 AGENTS.md（/init 可生成骨架），Codex 每次启动自动读取。只沉淀反复踩过的坑，保持简短（默认上限 32 KiB）。

1
2
3
4
5
6
7
8
9
## 项目命令
- 启动: npm run dev
- 测试: npm test
- 构建: npm run build

## 工作规则
1. 修改前先说明计划，最小改动
2. 修改后跑测试或构建
3. 总结修改 + 验证结果

6.2 流程：Skills

一个目录 + SKILL.md（name / description / 步骤）就是一个技能，放进 .agents/skills/ 会被自动发现。description 写清"什么时候该用"，Codex 按描述自动触发，或显式 $skill-name 调用。

6.3 连接：MCP

把 Codex 接上外部系统：GitHub、设计稿、文档、浏览器、数据库。

1
2
3
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN
codex mcp list        # 查看已配置的 MCP server
/mcp                  # 会话内查看当前可用工具

6.4 守门：Hooks

在 Codex 看不到的时刻自动出手：命令检查、日志记录、安全拦截、自动提醒。放在 ~/.codex/hooks.json 或 .codex/hooks.json，常用事件：PreToolUse / PostToolUse / SessionStart / Stop。

1
2
3
4
5
6
7
8
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "python3 .codex/hooks/check_command.py", "timeout": 30 }]
    }]
  }
}

6.5 并行：Subagents

读多、查多、分析多的任务拆给并行 Agent，最后收敛出高质量结论。例：派安全、测试、可维护性三个 Agent 并行审查 git diff。

“请使用 Subagent 并行审查当前 git diff，派出三个 Agent：1. 安全审查 Agent（权限、输入校验、敏感信息）2. 测试审查 Agent（缺少测试、覆盖关键路径）3. 可维护性审查 Agent（结构、重复逻辑、命名）。等三个都完成后按严重程度排序汇总，给出文件位置和修改建议，暂时不要修改文件。”

会话内用 /agent 查看和切换子代理线程。

7. 怎么做团队复用

核心思想：复用分两个层级——同一仓库内，文件随 git 走自动生效；跨仓库 / 多项目，打包成 Plugin 走团队 marketplace 安装。凡是"要装进别人环境"的复用，Plugin 是标准答案。

怎么做

仓库内复用（随 git 走）：AGENTS.md、.agents/skills/、.codex/config.toml + .codex/hooks.json 提交进仓库，同仓库同事开箱即用（密钥走环境变量，不提交）
团队级分发（跨仓库）：把 §6 的 Skills + MCP + Hooks 打包成 Plugin，发布到团队 marketplace，成员一键安装
CI 自动化：非交互跑评审、生成发布说明等

执行命令

1
2
3
4
codex exec "审查未提交改动并给出风险清单"   # 非交互模式，可进 CI
codex review --uncommitted                 # 审未提交改动
codex review --base main                   # PR 式评审
/plugins                                  # CLI 会话内打开插件浏览器

Codex 实战笔记（后端开发工程师版）

1. 为什么学：先建心智模型#

2. 怎么装#

3. 怎么读项目#

4. 怎么跑闭环（核心工作流）#

5. 怎么管上下文#

6. 怎么搭积木（经验固化）#

6.1 规则：AGENTS.md#

6.2 流程：Skills#

6.3 连接：MCP#

6.4 守门：Hooks#

6.5 并行：Subagents#

7. 怎么做团队复用#

1. 为什么学：先建心智模型

2. 怎么装

3. 怎么读项目

4. 怎么跑闭环（核心工作流）

5. 怎么管上下文

6. 怎么搭积木（经验固化）

6.1 规则：AGENTS.md

6.2 流程：Skills

6.3 连接：MCP

6.4 守门：Hooks

6.5 并行：Subagents

7. 怎么做团队复用