← Back to learning path
Chapter · Published

Run your first Codex CLI task

Start with a small reversible task, inspect the repository, review the diff, and verify the result before committing.

Source: start/11-cli-first-run.md快速上手 (original language)
Chapter progress 0%Learning path progress 0% · 0/46 chapters completedContinue learning path →

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 screenshot

Reference screenshot

Reference screenshot

Reference tables

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

Further reading

KnowledgeAI Agents: From Core Concepts to ProductionKnowledgeDesigning Reliable AI Automation Workflows
Product Hub Demo · V0.3