Tip · Last checked
This workflow was checked on 2026-09-03. Follow the Codex CLI documentation, AGENTS.md configuration, and agent approvals and security for current behavior.
Run your first Codex CLI task
Choose a typo fix, a small unit test, a README command update, or a bug with an existing failing test. Avoid a broad refactor, production credentials, billing, permission changes, or deletion on the first run.
1. Map the repository without editing
Ask Codex to identify the purpose, key directories, install command, test command, and a low-risk first task. Read the answer and correct its assumptions before proceeding.
2. Give one small task
State the allowed files, required verification, and delivery summary. Ask Codex to read the relevant code, make the smallest patch, run the focused check, and report residual risks.
3. Observe the run
Watch whether Codex reads context first, keeps scope, explains commands, asks for approval when needed, and reports failures instead of hiding them.
4. Review the diff
Use the CLI or your editor to check changed files, links, tests, and generated artifacts. Do not accept a patch you have not read.
git diff
5. Record the result
Capture the goal, files changed, verification command, result, remaining risk, and a proposed commit message. Commit only after the checks and review are complete.
If the first attempt fails
Keep the error output, classify it as a code, dependency, environment, or scope problem, and ask for the smallest relevant fix. Re-run the same verification after the fix.
Completion checklist
- The task is small enough to understand.
- The diff is limited and reviewed.
- The focused test or command passed.
- No secret, destructive command, or unverified claim was introduced.
Next step
Continue with Codex in VS Code.
Code examples
请只读分析当前仓库,不要修改文件。
请输出:
1. 项目用途
2. 关键目录
3. 安装、测试、构建命令
4. 当前任务适合从哪里开始
5. 你建议我第一次交给你的低风险任务
请修复当前仓库中最小范围的一个测试失败。
要求:
1. 先运行测试,确认失败信息。
2. 阅读相关代码和测试,不做无关重构。
3. 修改最少必要文件。
4. 修复后重新运行相关测试。
5. 最后总结:失败原因、改了哪些文件、验证命令和剩余风险。
请更新 [文档文件] 中关于 [主题] 的说明。
要求:
1. 先读取相关官方资料和现有文档结构。
2. 保持中文教程风格,避免整段翻译官方原文。
3. 涉及操作步骤时添加截图占位。
4. 修改后运行文档站构建。
5. 最后列出来源链接和需要人工补图的位置。
请 review 你刚才的改动,不要继续修改文件。
请重点检查:
1. 是否有无关改动
2. 是否遗漏测试
3. 是否引入安全或兼容风险
4. 是否还有未验证的地方
请用提交前摘要格式输出:
- 改动目标
- 修改文件
- 验证命令
- 验证结果
- 剩余风险
- 建议 commit message
git add .
git commit -m "fix: resolve failing test"
Reference screenshots



Reference tables
| 观察点 | 说明 |
|---|---|
| 是否先读上下文 | 好结果通常来自充分阅读相关文件 |
| 是否控制范围 | 第一次任务不追求顺手重构 |
| 是否解释命令 | 命令执行前应说明目的 |
| 是否运行验证 | 修改完成后要跑相关测试或构建 |
| 是否说明风险 | 没能验证的部分要如实记录 |
| 失败现象 | 处理方式 |
|---|---|
| 改动太大 | 让 Codex 停下,只保留最小修复思路 |
| 测试跑不起来 | 先让它解释环境缺口和命令来源 |
| 方向不对 | 回到只读分析,让它列出文件依据 |
| 输出太泛 | 要求按文件、命令、风险分段输出 |
| 误改无关文件 | 用 git diff 确认,再手动决定保留或丢弃 |
