这篇文章用一个可运行的 Python 账单统计 CLI 项目，讲清楚 OpenAI Codex CLI 在本地开发中的实际用法：为什么要用它、适合交给它什么任务、怎样用 AGENTS.md 写清楚项目规则、如何让它先读代码再复现失败、怎样根据失败日志做小范围修复，最后再通过单元测试、命令行输出和报告图确认结果。文章的目标不是演示“让 AI 写一段代码”，而是走一遍更接近真实开发的完整过程：测试失败 -> 定位问题 -> 小范围修复 -> 再次测试 -> 提交前检查。

为什么要用 Codex CLI：让它帮你跑测试、改代码、查结果

如果只是让模型补一个函数，普通聊天窗口已经足够。真实开发里更难处理的是另一类问题：代码已经在仓库里，测试已经写好，失败日志也在终端里，开发者需要有人沿着项目规则去读文件、跑命令、看错误、改代码，并把验证结果留下来。

Codex CLI 的价值就在这个位置。它运行在终端里，面向当前项目目录工作，可以读取仓库文件、执行测试命令、修改代码、解释代码改动，并把过程保留在会话里。对开发者来说，它不是替代测试和人工检查，而是把 AI 工具接到平时写代码、跑测试、看结果的流程里：

• 用测试约束结果，避免只凭“看起来正确”判断代码。
• 用 AGENTS.md 和提示词说明修改范围，减少无关改动。
• 用失败日志找原因，而不是让 Codex 凭经验猜问题。
• 用重新运行测试、查看代码改动、提交前检查决定结果是否可接受。

本文要完成的任务很具体：修复一个 Python 账单统计命令行项目中的金额解析 Bug。原始项目无法正确处理 "$1,200.50" 这种带货币符号和千分位逗号的金额，也会把 "(12.30)" 这种括号负数解析成正数。这个问题小，但足够真实：它有输入数据、有单元测试、有失败日志，能看出该改哪里、不该改哪里，也有最终的 JSON 报表输出。

Codex CLI 适合做什么

Codex CLI 是 OpenAI Codex 面向终端的本地开发形态。按照官方手册的说明，运行 codex 可以启动终端交互界面；也可以直接在命令后追加一个提示词，让 Codex 围绕当前目录完成一次任务。它适合处理解释代码、修复测试失败、补充小功能、检查代码改动、整理文档这类有明确上下文和检查标准的工作。

下图是 OpenAI Developers 上的 Codex CLI 页面截图。安装入口、登录方式和命令选项可能随版本更新，实际使用时建议以官方页面为准。

一个最小使用流程大致是：

# 1. 安装 Codex CLI，具体方式以官方文档为准
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 2. 登录
codex login

# 3. 进入本地项目
cd your_project

# 4. 启动交互式 Codex，或直接给出任务
codex
codex "Explain this codebase to me"

这里要注意一件事：Codex CLI 更适合处理“知道要看哪里、知道怎么检查结果”的任务，不适合一开始就接收“重构整个系统”“优化所有代码”“顺便补齐所有测试”这种范围很大的指令。任务越模糊，它越容易改到无关文件；检查标准越清楚，结果越容易判断。

可以把适合交给 Codex CLI 的任务概括为四个条件：

条件	说明	本文示例
有明确目标	不是“改好一点”，而是修复一个可描述的问题	修复金额解析和月度汇总相关失败
有上下文入口	知道先读哪些文件、哪个目录是核心	README.md、AGENTS.md、tests/、expense_tool/
有检查命令	修改后能运行命令判断结果	python -m unittest discover -s tests -v
有修改范围	知道哪些地方不要动	不新增重依赖、不删除测试、不改公开函数名

具备这四点，Codex CLI 更像一个能帮你跑命令、改代码、查结果的本地开发助手；缺少这些条件，它就容易变成“边猜边改”的代码生成器。

实战项目：一个带 Bug 的账单统计 CLI

本项目名为 codex_cli_dev_booster_tutorial，里面放了一个故意带 Bug 的账单统计工具。它读取 CSV 账单数据，按月份输出 JSON 报表。项目不大，但包含真实开发中常见的要素：命令行入口、解析模块、汇总模块、测试文件、输入数据、运行脚本和结果报告。

项目结构如下：

codex_cli_dev_booster_tutorial/
├── run_demo.py              一键运行验证脚本
├── demo_project/            带 Bug 的账单统计项目
├── solutions/               参考修复方案
├── prompts/                 可复制给 Codex CLI 的任务提示词
├── src/                     提示词、报告和结果图生成代码
├── outputs/                 测试日志与运行报告
├── images/figures/          项目结构与流程说明图
├── images/results/          真实运行结果图
└── docs/                    教程、排错和素材来源说明

这张图展示了项目内部关系：demo_project 提供待修复代码，tests/ 暴露失败用例，AGENTS.md 写明项目规则，prompts/ 保存分阶段提示词，run_demo.py 负责生成可复现的运行证据。

核心业务链路很短：cli.py 接收 CSV 路径和月份参数，parser.py 读取并解析账单行，report.py 过滤目标月份并计算总额和分类汇总。Bug 出在解析阶段，后续汇总只是消费解析后的数值。

原始 parse_amount 函数如下：

def parse_amount(raw: str) -> float:
    text = str(raw).strip().replace("$", "")

    if text.startswith("(") and text.endswith(")"):
        text = text[1:-1]

    return float(text)

这段代码看似处理了美元符号和括号，实际留下了两个输入格式问题：

• "$1,200.50" 去掉 $ 后仍是 "1,200.50"，float() 不能直接解析带逗号的字符串。
• "(12.30)" 去掉括号后变成 "12.30"，负数语义丢失。

测试文件把这两个问题直接写成断言：

def test_currency_and_comma(self) -> None:
    self.assertEqual(parse_amount("$1,200.50"), 1200.50)

def test_parentheses_negative(self) -> None:
    self.assertEqual(parse_amount("(12.30)"), -12.30)

这也是选择这个项目做教程的原因：问题不是玩具式打印错误，而是输入格式归一化不足；修复不需要大规模重构，但必须顺着测试和业务含义做判断。

第一步：准备可复现工作区

先在项目根目录安装依赖并运行演示脚本：

pip install -r requirements.txt
python run_demo.py

脚本会完成这些动作：

复制 demo_project 到 workspace/demo_project
生成 Codex CLI 任务提示词
运行修复前单元测试并保存失败日志
应用 solutions 中的参考修复
再次运行单元测试
执行账单统计命令行程序
生成 Markdown 报告和结果图

这里的参考修复不是为了绕过 Codex CLI，而是让教程在离线状态下也能复现完整效果。真实使用时，可以先只准备带 Bug 的干净工作区：

python run_demo.py --prepare-only
cd workspace/demo_project

这样做有两个好处。第一，Codex 面对的是一个可修改的临时项目，不会直接污染原始示例目录。第二，每次实验前都能恢复到同一个失败状态，便于比较不同提示词的效果。

第二步：用 AGENTS.md 写清楚项目规则

使用 Codex CLI 前，建议先写 AGENTS.md。它不是给读者看的 README，而是给 Codex 看的项目工作说明。对于多人协作项目，这类规则如果每次都写进提示词，很容易遗漏；放到 AGENTS.md 后，Codex 每次进入项目都能先读到同一套要求。

本文项目里的规则很短：

Prefer small, reviewable patches.
After changing Python code, run:
python -m unittest discover -s tests -v
Do not add heavy dependencies unless the user explicitly asks.
Keep generated artifacts under outputs/ or images/results/.
Write explanations in Chinese for blog/tutorial files.

这几个规则足够覆盖本次任务的关键风险：

规则	解决的问题
小范围补丁	防止 Codex 顺手重构无关模块
修改后运行测试	防止只改代码不验证
不新增重依赖	防止简单解析问题被复杂化
生成物放到固定目录	防止日志、图片、报告散落在项目根目录
教程说明用中文	保持文章、报告和提示词风格一致

下图是官方 AGENTS.md 指南页面截图。迁移到自己的仓库时，AGENTS.md 不需要写得很长，优先写清楚“怎么跑项目、怎么测试、哪些事情不能做、什么结果算完成”。

一个实用的写法是把规则分成四类：

项目入口：主要目录、启动命令、测试命令
修改范围：哪些模块可以动，哪些模块不要碰
依赖策略：是否允许新增依赖，新增前是否需要确认
完成标准：必须通过哪些测试，最后需要说明哪些内容

这比写一堆抽象口号更有效。比如“保持高质量代码”不如“修改 Python 代码后运行 python -m unittest discover -s tests -v”；“不要乱改”不如“不要删除已有测试，不要改变公开函数名”。

第三步：让 Codex 先读项目，不急着改代码

很多失败的 Codex 使用方式都从一句话开始：“帮我修一下这个项目。”问题在于，这句话没有目标范围，也没有检查标准。更稳的做法是先让 Codex 只读理解项目，不允许它修改文件。

第一段提示词可以这样写：

你现在在一个 Python 命令行小项目中。请先不要修改文件，只做代码库理解。
请阅读 README.md、AGENTS.md 和 tests/ 目录，用中文总结项目功能、主要模块、测试入口和潜在失败点。
给出下一步修复计划，但不要直接改代码。

这一阶段要检查的不是代码，而是 Codex 的理解是否可靠。它至少应该说清楚：

• 项目是读取 CSV 并生成月度账单 JSON 的命令行工具。
• 测试入口是 python -m unittest discover -s tests -v。
• 失败风险集中在金额字符串解析和汇总结果。
• 修复前应该先运行测试，不能直接凭经验改代码。

如果 Codex 在这个阶段把重点放到无关模块，比如想重写 CLI 参数解析、改报表输出格式、引入新库处理金额，那么应该先纠正任务范围，再进入修复。只读理解这一步看似慢，实际是在降低后续返工成本。

第四步：复现失败，让日志决定修改点

确认上下文正确后，再让 Codex 进入修复阶段。提示词可以写得更明确：

请读取 AGENTS.md，并严格按仓库约定执行。

任务目标：
1. 运行 python -m unittest discover -s tests -v；
2. 根据失败日志定位问题；
3. 修复金额解析、负数金额、带千分位金额、月度汇总等相关逻辑；
4. 不要引入新的第三方依赖；
5. 修改后再次运行测试；
6. 最后用中文总结改动文件、Bug 原因和验证结果。

约束：
- 优先小步修改；
- 保持函数名和公开接口不变；
- 不要删除已有测试；
- 如需补充测试，只补充与本次 Bug 直接相关的测试。

修复前失败日志里有两条关键证据：

ValueError: could not convert string to float: '1,200.50'
AssertionError: 12.3 != -12.3

第一条错误从测试直接指向 parse_amount("$1,200.50")，说明解析函数没有处理千分位逗号。第二条失败说明括号负数被转成了正数。它们共同指向一个结论：根因在金额字符串归一化，而不是 CLI 参数、CSV 读取或月度汇总算法。

这一步体现了使用 Codex CLI 的一个关键原则：不要把失败日志当成最后的报错截图，而要把它当成修改范围的证据。日志已经把问题定位到 parser.py，合理修复就应该优先集中在这个函数附近。

第五步：做最小修复，而不是顺手重构

参考修复方案如下：

def parse_amount(raw: str) -> float:
    text = str(raw).strip()
    if not text:
        raise ValueError("Amount cannot be empty.")

    is_parentheses_negative = text.startswith("(") and text.endswith(")")
    if is_parentheses_negative:
        text = text[1:-1].strip()

    text = text.replace("$", "").replace(",", "").strip()
    value = float(text)

    if is_parentheses_negative:
        value = -abs(value)

    return value

这个补丁的处理顺序是有讲究的：

1. 先 strip()，去掉首尾空白，避免输入格式影响判断。
2. 再判断是否为括号负数，并把括号内部的金额取出来。
3. 清理货币符号和千分位逗号。
4. 交给 float() 做最终数值转换。
5. 如果原始格式是括号负数，则统一转为负值。

这里没有用一个宽泛的 try/except 把错误吞掉，也没有引入第三方金额库。原因很简单：当前任务只要求处理项目测试覆盖的几类金额格式，最合适的补丁应该小、直观、可测试。如果未来要支持多币种、不同地区格式或精确财务计算，再考虑 Decimal、本地化解析或更完整的数据校验也不迟。

这也是审查 Codex 输出时需要关注的点。一个看似“更高级”的大改动未必更好；如果它改变了公开接口、删除了测试、引入新依赖，反而增加了风险。对这类测试驱动的小 Bug，最佳结果通常是最小补丁加明确验证。

第六步：重新测试并生成报表

修复完成后，必须重新运行同一条测试命令：

python -m unittest discover -s tests -v

本项目修复后 5 个单元测试全部通过：

test_currency_and_comma ... ok
test_leading_negative ... ok
test_parentheses_negative ... ok
test_plain_number ... ok
test_build_monthly_report ... ok

Ran 5 tests
OK

单元测试通过后，还要运行一次真实 CLI 命令，因为项目的最终使用方式不是直接调用 parse_amount，而是读取 CSV 并输出月度报表：

python -m expense_tool.cli data/expenses.csv --month 2026-05 --output ../monthly_report.json

最终输出如下：

{
  "month": "2026-05",
  "record_count": 4,
  "monthly_total": 1227.15,
  "category_totals": {
    "Food": 35.75,
    "Refund": -12.3,
    "Salary": 1200.5,
    "Transport": 3.2
  }
}

这里可以分三层理解验证结果：

验证层级	证明了什么	仍不证明什么
单元测试通过	金额解析和月度汇总覆盖了当前几个特殊输入	不代表所有地区金额格式都支持
CLI 输出正常	从 CSV 读取到 JSON 输出的主链路可运行	不代表异常输入都有友好提示
报表图生成	教程结果可以被读者直观看到	不代表这是生产级财务系统

下图由真实运行日志和 CLI 输出生成，可以看到修复前失败、修复后通过以及报表输出。

修复前后的测试状态图如下：

月度账单汇总图如下：

第七步：让 Codex 做提交前审查

测试通过后，不建议马上提交。最后可以让 Codex 帮你做一次提交前检查，只看当前代码改动，不继续主动改代码：

请像一名严谨的代码审查助手一样检查当前修改。

请重点关注：
1. 金额解析是否覆盖常见格式；
2. 日期和月份过滤是否稳定；
3. CLI 输出是否便于用户理解；
4. 测试是否能覆盖本次修复；
5. 是否存在过度设计或不必要依赖。

输出：
- 风险清单；
- 建议修改；
- 可以直接提交的结论；
- 后续优化建议。

这一步的重点不是让 Codex 继续写代码，而是让它帮助开发者发现风险。比如：

• 是否只改了 parser.py，没有动无关模块。
• 是否保留了已有测试，并让失败用例变成通过用例。
• 是否改变了 CLI 输出字段。
• 是否对空字符串、缺失字段等异常输入有基本处理。
• 是否新增了不必要依赖。

最终是否提交仍然由开发者决定。Codex 的检查意见是辅助，不应该替代人工看代码改动、跑测试和判断业务影响。

提示词可以按这几项写

本文的提示词可以拆成几项，迁移到其他项目时直接替换内容即可：

要写的内容	要回答的问题	示例
目标	这次到底要完成什么	修复金额解析导致的测试失败
要看的文件	Codex 应该先看哪里	README.md、AGENTS.md、tests/
复现方式	如何复现问题	运行 python -m unittest discover -s tests -v
限制	哪些事情不能做	不新增依赖、不删除测试、不改公开函数名
完成标准	什么结果算完成	测试通过，CLI 报表能输出 JSON，并总结改动

对应到本文项目，完整命令可以写成：

python run_demo.py --prepare-only
cd workspace/demo_project
codex "读取 AGENTS.md，运行 python -m unittest discover -s tests -v，定位失败原因，修复金额解析和月度汇总相关问题。不要新增第三方依赖。修改后再次运行测试，并用中文总结改动。"

下面这张流程图概括了 Codex CLI 参与本地修复任务的方式：

如果任务更复杂，不要把所有目标塞进一条提示词。可以拆成几个连续阶段：

只读理解项目
复现失败并解释日志
提出最小修复计划
执行修复并运行测试
根据新失败日志继续小步修复
测试通过后检查代码改动

这种拆法看起来步骤更多，但每一步都有明确产物，失败后也知道该回到哪里修正。

常见误区和更稳的写法

使用 Codex CLI 时，最容易踩的坑不是工具不会写代码，而是任务描述太松。下面这些写法都容易让修改失控：

不推荐写法	问题	更稳的写法
帮我优化这个项目	目标过宽，不知道优化什么	先阅读项目并列出 3 个可验证的改进点，不要修改文件
修一下所有测试	范围过大，可能同时改测试和代码	先运行测试，只修复与当前失败日志直接相关的问题
顺便重构一下	容易让改动变大	本次只允许修改与 Bug 根因相关的函数
你自己看着办	没有完成标准	修改后必须运行指定测试，并说明改动文件和验证结果

还要避免把权限给得过大。面对陌生仓库或第三方代码时，先使用较保守的权限和小范围任务；需要访问网络、改外部目录或执行破坏性命令时，应该让 Codex 先说明原因，再由开发者判断是否允许。

迁移到真实项目时怎么改

这套方法不只适用于账单统计项目。迁移到自己的项目时，重点替换四类信息：

要替换的内容	本文示例	你的项目
测试命令	python -m unittest discover -s tests -v	例如 pytest、npm test、mvn test
失败目标	金额解析和月度汇总	某个接口、组件、脚本或数据处理流程
禁止事项	不新增依赖、不删除测试	不改数据库结构、不碰核心鉴权、不改公共 API
完成标准	5 个测试通过并生成报表	CI 通过、页面可用、指标正确、日志无异常

不同类型项目可以这样落地：

• 后端接口项目：让 Codex 先跑接口测试或最小复现脚本，只修失败接口相关代码。
• 前端项目：让 Codex 先定位组件和状态来源，再运行单元测试、类型检查或构建命令。
• 数据处理脚本：准备一份小样本输入和期望输出，让 Codex 修复转换逻辑后重新生成结果。
• 文档或教程项目：让 Codex 先核对代码、命令和截图是否一致，再改正文。

如果项目没有测试，至少要补一个可执行的验证入口。可以是一个脚本、一组样例输入输出，或者一份人工检查清单。没有验证入口时，Codex 也能改代码，但开发者很难判断它改得是否正确。

总结

本文用一个小型 Python 账单统计项目，演示了 Codex CLI 如何参与一次完整的本地开发任务：读取项目规则、理解测试入口、复现失败、定位金额解析问题、做小范围修复、重新测试、生成报表，并在提交前做风险检查。

真正值得复用的不是这段金额解析代码，而是这套做法：先让问题能复现，再用失败日志缩小修改范围，用 AGENTS.md 写清楚项目规则，用测试和 CLI 输出确认结果，最后让人工检查代码改动。Codex CLI 的价值不是绕过测试和审查，而是帮开发者把读代码、跑命令、修 Bug、查结果这些步骤做得更顺。

参考资料

• OpenAI Developers：Codex，https://developers.openai.com/codex
• OpenAI Developers：Codex CLI，https://developers.openai.com/codex/cli
• OpenAI Developers：Codex Quickstart，https://developers.openai.com/codex/quickstart
• OpenAI Developers：Prompting Codex，https://developers.openai.com/codex/prompting
• OpenAI Developers：AGENTS.md 指南，https://developers.openai.com/codex/guides/agents-md
• OpenAI Developers：Codex CLI Command Line Options，https://developers.openai.com/codex/cli/reference