Mystpet's Blog

Appearance

DAILY QUOTE

“ ”

重点：

  • 读代码
  • 改代码
  • 跑命令
  • 解释报错
  • 做code review

1.简介 ​

  • 第1个阶段是分清 Codex 的产品形态

第 2 阶段要聚焦 CLI 和 IDE 中的本地协作： 官方对CLI的定位是：Codex CLI是可以在终端本地运行的coding agent，能在选定目录中读取、修改、运行代码。

IDE Extension使用同一个agent，并且与CLI共享配置。IDE的优势是打开文件、选区、@file等上下文，适合写代码时边看边问。

最重要的本地工作模型是：

text
当前目录/IDE工作区
        +
打开文件/选区/@file
        +
AGENTS.md项目说明
        +
config.toml权限与默认行为
        +
Codex执行读、改、跑、review

本地协作不是让Codex凭空回答，而是让它围绕当前项目、当前文件、当前规则和当前权限行动。

2.CLI和IDE分别适合什么 ​

2.1.CLI ​

CLI适合工程型任务。

常见任务：

  • 让Codex读整个仓库
  • 搜索代码
  • 修改多个文件
  • 运行测试、lint、build
  • 根据报错继续修复
  • 做本地code review
  • 使用 codex exec 做一次性自动化任务

CLI的优势是更接近真实工程环境：目录、shell、git、测试命令都在同一个地方。

一句话理解：

CLI是最适合处理repo级工程任务的入口。

2.2.IDE Extension ​

IDE适合写代码时的即时协作。 常见任务：

  • 解释当前打开的文件
  • 修改选中代码
  • 引用 @file
  • 使用当前IDE上下文生成更准确的回答
  • 在本地模式和云端模式之间切换
  • 直接在编辑器里review改动

典型prompt：

text
解释当前选中的函数，它依赖哪些模块

参考 @api.ts，把 @user-service.ts 里的错误处理改成同样风格。

一句话理解：

IDE Extension是写代码时贴在旁边的本地协作者。

3.读代码：先建立项目地图 ​

读代码时，不要一开始就让Codex改。先让他建立结构认知。

推荐prompt：

text
先不要修改文件。请阅读这个项目，回答：
1. 项目入口在哪里？
2. 主要模块如何划分？
3. 本地启动、测试、构建命令分别是什么？
4. 如果我要修改登录流程，应该先看哪些文件？

更聚焦一点：

text
先只读代码，不要改文件。请梳理 `src/api` 目录的职责、关键文件和调用关系。

在IDE里可以加上下文：

text
结合@router.ts和@auth.ts，解释一次登录请求从入口到返回结果的完整流程。

读代码时的关键点：

  • 先要求“不要修改文件”
  • 明确让Codex输出文件路径
  • 让它区分“确定事实”和“推测”
  • 让它说明下一步应该看哪些文件
  • 让它基于代码而不是凭经验猜

4.改代码：小步执行，保证可验证 ​

改代码时，最稳的方式不是一句话让Codex全自动大概，而是先让他明确影响范围。

适合中等复杂度任务的prompt：

text
先分析影响范围，再给出修改计划。确认后再改。

对于小改动，可以直接让它执行：

text
修复这个函数的空值处理问题，并补一个最小测试。修改后运行相关测试。

对于中等改动，推荐格式：

text
请完成这个改动：  
目标：把用户列表页的搜索参数同步到 `URL query`。  
要求：  
1. 保持现有UI不变  
2. 不引入新依赖  
3. 优先复用现有`hooks`  
4. 修改后运行相关测试  
5. 最后总结改了哪些文件

改代码时的关键点：

  • 给目标，不只给方案
  • 写清约束
  • 要求运行验证
  • 让它最后总结文件和测试结果
  • 不要让它顺手重构无关代码
  • 修改范围越大，越应该要求先计划再执行

5.跑代码：理解approval、sandbox、rules ​

Codex本地能运行命令，但不是无限制运行。

CLI Features文档把approval mode分为几种常见模式：

模式含义适合场景
Auto默认模式。Codex可以在工作目录内读文件、改文件、运行命令；访问工作目录外或网络时仍会询问日常开发
Read-only偏咨询模式。可以读文件，但不会直接修改或运行命令只想分析、解释、规划
Full Access权限最高，能跨机器访问文件和网络，不会频繁询问只在非常信任repo和任务时使用
在CLI里可以用：
text
/permissions

查看当前状态：

text
/status

查看当前diff：

text
/diff

在IDE中也有类似的Chat、Agent、Agent Full Access等模式。默认Agent模式下，Codex可以在工作目录内读、改、跑命令，但访问工作区外或网络仍需要审批。

跑命令时推荐这样要求：

text
请先说明你要运行哪些命令以及目的，然后执行。失败后解释原因并继续定位。

6.解释报错：给他命令、输出和上下文 ​

解释代码时，最好不要只贴一段错误。更稳的方式是同时给出：

  • 运行了什么命令
  • 完整或关键报错输出
  • 相关文件
  • 期望的行为
  • 最近做过什么改动

推荐prompt：

text
下面是`npm test`的失败输出。请先解释失败原因，再定位最可能的文件，最后给出修复方案。先不要改文件。
<粘贴错误输出>

如果希望它直接修：

text
运行测试，定位失败原因并修复。只改与失败相关的最小范围。修复后重新运行失败测试。

如果报错来自截图，CLI支持图片输入，例如：

bash
codex -i screenshot.png "解释这个错误"

解释报错的核心流程：

text
先复现->再定位->再修改->再验证

不要让Codex只“解释错误文本”，要让他回到代码和命令环境里定位根因。

7.做Codexreview：本地常用/review ​

CLI Features文档说明，/review会启动一个专门reviewer，读取你选择的diff，并输出优先级明确、可执行的问题，不会修改工作区。

它可以review：

  • 相对base branch的改动(Review against a base branch)
  • 未提交改动(Review uncommitted changes)
  • 某个commit(Review a commit)
  • 带自定义重点的review，例如“重点看可访问性回归”(Custom review instructions) 配合：
text
/diff

用来查看具体改动。

也可以直接要求：

text
请以`code review`方式检查当前未提交改动。优先指出bug、行为回归、缺失测试和安全风险。

Code review的输出重点应该是：

text
先列bug/风险/回归/缺测试  
再给文件和位置  
最后才是总结

这和普通“帮我看看代码”不一样。Code review不是夸代码，而是找可能出问题的地方。

8.Slash commands：本地协作快捷控制 ​

CLI中输入/可以打开slash command菜单

最常用的CLIslash commands：

命令用途
/status查看模型、权限、workspace、token使用情况
/permissions切换Codex能否自动读、改、跑命令
/model切换模型和reasoning
/plan进入计划模式，先规划再实现
/diff查看当前Gitdiff
/review对本地改动做code review
/mention把指定文件加入上下文
/compact长对话后压缩上下文
/clear清空终端并开始新对话
/new在同一CLIsession中开新conversation
/resume恢复历史会话
/init生成AGENTS.md脚手架
/mcp查看可用MCP工具

IDE中常用的slash commands：

命令用途
/auto-context开关自动加入最近文件和IDE上下文
/local切到本地模式
/cloud切到云端模式
/review启动代码审查
/status查看 thread、上下文、rate limit

9.Config Basics：配置决定默认行为 ​

本地CLI和IDE共享配置层 用户级配置：

text
~/.codex/config.toml

项目级配置：

text
.codex/config.toml

配置优先级从高到低：

  1. CLIflags和--config
  2. profile
  3. 项目.codex/config.toml
  4. 用户~/.codex/config.toml
  5. 系统 /etc/codex/config.toml
  6. 内置默认值

常见配置示例：

toml
model = "gpt-5.5"  
approval_policy = "on-request"  
sandbox_mode = "workspace-write"  
model_reasoning_effort = "high"  
web_search = "cached"  
personality = "pragmatic"

理解这些配置项：

配置项作用
model默认模型
approval_policy什么时候需要你批准
sandbox_modeCodex能访问和写入哪里
web_search是否允许搜索网页，以及用 cached还是live
model_reasoning_effort思考深度
shell_environment_policy命令运行时能继承哪些环境变量

项目级 .codex/config.toml 只会在 trusted project 中加载。这个限制很重要，因为项目配置可能改变Codex的权限、hooks、rules和工具行为。

10.AGENTS.md：让Codex稳定理解项目规则 ​

AGENTS.md 是给Codex的长期项目说明。

官方说明：Codex在开始工作前会读取AGENTS.md文件。通过全局说明和项目说明分层，可以让每次任务都有稳定的默认规则。

适合写入：

  • 项目结构说明
  • 本地启动命令
  • 测试命令
  • lint/typecheck 命令
  • 代码风格
  • 常用开发约定
  • review重点
  • 安全注意事项
  • 不希望Codex做的事情

发现顺序：

  1. 全局：~/.codex/AGENTS.md或~/.codex/AGENTS.override.md
  2. 项目：从Gitroot一路向当前目录查找
  3. 越靠近当前目录的规则越具体，优先级越高

实用写法：

  • ~/.codex/AGENTS.md写个人偏好
  • 项目根目录AGENTS.md写项目通用规则
  • 子目录AGENTS.md或AGENTS.override.md写模块特殊规则

一句话理解：

AGENTS.md管Codex应该如何理解和处理这个项目。

11.Rules：控制哪些命令能越过sandbox ​

Rules控制Codex哪些命令可以在sandbox外运行。官方标注Rules仍是experimental。

规则文件放在：

text
~/.codex/rules/default.rules

或项目：

text
.codex/rules/default.rules

项目级rules只在trusted project中加载

规则核心是prefix_rule()：

python
prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Viewing PRs is allowed with approval",
)

decision 有三种：

decision含义
allow允许匹配命令直接运行
prompt每次运行前询问
forbidden禁止运行

Rules适合处理这些情况：

  • 常用安全命令减少重复确认
  • 高风险命令强制禁止
  • 团队统一限制某些操作
  • 对gh、git、包管理器、部署命令做精细控制

需要区分：

text
`AGENTS.md`管“应该怎么做”
`Rules`管“哪些命令能不能做”
`config.toml`管“默认运行边界”

12.五类任务推荐工作流 ​

12.1.读代码 ​

text
先不要修改文件。请梳理这个项目的入口、模块结构、关键命令和主要数据流。

输出期望：

  • 关键目录
  • 入口文件
  • 调用链
  • 配置文件
  • 启动和测试命令
  • 后续应该阅读的文件

12.2.改代码 ​

text
请实现X。要求保持现有风格，不引入新依赖，修改后运行相关测试，并总结改动文件。

输出期望：

  • 修改了哪些文件
  • 为什么这样改
  • 运行了哪些验证
  • 是否还有未验证风险

12.3.跑命令 ​

text
请先说明你要运行哪些命令以及目的，然后执行。失败后解释原因并继续定位。

输出期望：

  • 命令
  • 目的
  • 结果
  • 如果失败，下一步定位路径

12.4.解释报错 ​

text
请解释这个报错的根因，定位相关文件，给出最小修复方案。先不要改文件。

输出期望：

  • 报错含义
  • 最可能根因
  • 相关文件
  • 验证方式
  • 修复方案

12.5.Code review ​

text
/review

或：

text
请以`code review`方式检查当前未提交改动。优先指出bug、行为回归、缺失测试和安全风险。

输出期望：

  • 严重问题优先
  • 文件路径明确
  • 风险具体
  • 不把总结放在问题前面

13. 总结 ​

text
CLI/IDE是入口  
AGENTS.md是长期规则  
config.toml是运行边界  
`slash commands`是现场控制  
approval+sandbox+rules是安全阀  
`diff`+`test`+`review`是验证闭环

一句话总结：

本地协作的关键不是让Codex“随便帮我改”，而是给它明确上下文、明确边界、明确验证方式，让它在当前项目中小步读、小步改、小步跑、小步review。