这篇文章用一个可运行的 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-fsSLhttps://chatgpt.com/codex/install.sh|sh# 2. 登录codex login# 3. 进入本地项目cdyour_project# 4. 启动交互式 Codex或直接给出任务codex codexExplain 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函数如下defparse_amount(raw:str)-float:textstr(raw).strip().replace($,)iftext.startswith(()andtext.endswith()):texttext[1:-1]returnfloat(text)这段代码看似处理了美元符号和括号实际留下了两个输入格式问题$1,200.50去掉$后仍是1,200.50float()不能直接解析带逗号的字符串。(12.30)去掉括号后变成12.30负数语义丢失。测试文件把这两个问题直接写成断言deftest_currency_and_comma(self)-None:self.assertEqual(parse_amount($1,200.50),1200.50)deftest_parentheses_negative(self)-None:self.assertEqual(parse_amount((12.30)),-12.30)这也是选择这个项目做教程的原因问题不是玩具式打印错误而是输入格式归一化不足修复不需要大规模重构但必须顺着测试和业务含义做判断。第一步准备可复现工作区先在项目根目录安装依赖并运行演示脚本pipinstall-rrequirements.txt python run_demo.py脚本会完成这些动作复制 demo_project 到 workspace/demo_project 生成 Codex CLI 任务提示词 运行修复前单元测试并保存失败日志 应用 solutions 中的参考修复 再次运行单元测试 执行账单统计命令行程序 生成 Markdown 报告和结果图这里的参考修复不是为了绕过 Codex CLI而是让教程在离线状态下也能复现完整效果。真实使用时可以先只准备带 Bug 的干净工作区python run_demo.py --prepare-onlycdworkspace/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合理修复就应该优先集中在这个函数附近。第五步做最小修复而不是顺手重构参考修复方案如下defparse_amount(raw:str)-float:textstr(raw).strip()ifnottext:raiseValueError(Amount cannot be empty.)is_parentheses_negativetext.startswith(()andtext.endswith())ifis_parentheses_negative:texttext[1:-1].strip()texttext.replace($,).replace(,,).strip()valuefloat(text)ifis_parentheses_negative:value-abs(value)returnvalue这个补丁的处理顺序是有讲究的先strip()去掉首尾空白避免输入格式影响判断。再判断是否为括号负数并把括号内部的金额取出来。清理货币符号和千分位逗号。交给float()做最终数值转换。如果原始格式是括号负数则统一转为负值。这里没有用一个宽泛的try/except把错误吞掉也没有引入第三方金额库。原因很简单当前任务只要求处理项目测试覆盖的几类金额格式最合适的补丁应该小、直观、可测试。如果未来要支持多币种、不同地区格式或精确财务计算再考虑Decimal、本地化解析或更完整的数据校验也不迟。这也是审查 Codex 输出时需要关注的点。一个看似“更高级”的大改动未必更好如果它改变了公开接口、删除了测试、引入新依赖反而增加了风险。对这类测试驱动的小 Bug最佳结果通常是最小补丁加明确验证。第六步重新测试并生成报表修复完成后必须重新运行同一条测试命令python-munittest discover-stests-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-mexpense_tool.cli data/expenses.csv--month2026-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-onlycdworkspace/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 DevelopersCodexhttps://developers.openai.com/codexOpenAI DevelopersCodex CLIhttps://developers.openai.com/codex/cliOpenAI DevelopersCodex Quickstarthttps://developers.openai.com/codex/quickstartOpenAI DevelopersPrompting Codexhttps://developers.openai.com/codex/promptingOpenAI DevelopersAGENTS.md 指南https://developers.openai.com/codex/guides/agents-mdOpenAI DevelopersCodex CLI Command Line Optionshttps://developers.openai.com/codex/cli/reference
OpenAI Codex CLI 本地开发提效实战：从测试失败到确认修好
发布时间：2026/6/3 23:48:25
这篇文章用一个可运行的 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-fsSLhttps://chatgpt.com/codex/install.sh|sh# 2. 登录codex login# 3. 进入本地项目cdyour_project# 4. 启动交互式 Codex或直接给出任务codex codexExplain 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函数如下defparse_amount(raw:str)-float:textstr(raw).strip().replace($,)iftext.startswith(()andtext.endswith()):texttext[1:-1]returnfloat(text)这段代码看似处理了美元符号和括号实际留下了两个输入格式问题$1,200.50去掉$后仍是1,200.50float()不能直接解析带逗号的字符串。(12.30)去掉括号后变成12.30负数语义丢失。测试文件把这两个问题直接写成断言deftest_currency_and_comma(self)-None:self.assertEqual(parse_amount($1,200.50),1200.50)deftest_parentheses_negative(self)-None:self.assertEqual(parse_amount((12.30)),-12.30)这也是选择这个项目做教程的原因问题不是玩具式打印错误而是输入格式归一化不足修复不需要大规模重构但必须顺着测试和业务含义做判断。第一步准备可复现工作区先在项目根目录安装依赖并运行演示脚本pipinstall-rrequirements.txt python run_demo.py脚本会完成这些动作复制 demo_project 到 workspace/demo_project 生成 Codex CLI 任务提示词 运行修复前单元测试并保存失败日志 应用 solutions 中的参考修复 再次运行单元测试 执行账单统计命令行程序 生成 Markdown 报告和结果图这里的参考修复不是为了绕过 Codex CLI而是让教程在离线状态下也能复现完整效果。真实使用时可以先只准备带 Bug 的干净工作区python run_demo.py --prepare-onlycdworkspace/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合理修复就应该优先集中在这个函数附近。第五步做最小修复而不是顺手重构参考修复方案如下defparse_amount(raw:str)-float:textstr(raw).strip()ifnottext:raiseValueError(Amount cannot be empty.)is_parentheses_negativetext.startswith(()andtext.endswith())ifis_parentheses_negative:texttext[1:-1].strip()texttext.replace($,).replace(,,).strip()valuefloat(text)ifis_parentheses_negative:value-abs(value)returnvalue这个补丁的处理顺序是有讲究的先strip()去掉首尾空白避免输入格式影响判断。再判断是否为括号负数并把括号内部的金额取出来。清理货币符号和千分位逗号。交给float()做最终数值转换。如果原始格式是括号负数则统一转为负值。这里没有用一个宽泛的try/except把错误吞掉也没有引入第三方金额库。原因很简单当前任务只要求处理项目测试覆盖的几类金额格式最合适的补丁应该小、直观、可测试。如果未来要支持多币种、不同地区格式或精确财务计算再考虑Decimal、本地化解析或更完整的数据校验也不迟。这也是审查 Codex 输出时需要关注的点。一个看似“更高级”的大改动未必更好如果它改变了公开接口、删除了测试、引入新依赖反而增加了风险。对这类测试驱动的小 Bug最佳结果通常是最小补丁加明确验证。第六步重新测试并生成报表修复完成后必须重新运行同一条测试命令python-munittest discover-stests-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-mexpense_tool.cli data/expenses.csv--month2026-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-onlycdworkspace/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 DevelopersCodexhttps://developers.openai.com/codexOpenAI DevelopersCodex CLIhttps://developers.openai.com/codex/cliOpenAI DevelopersCodex Quickstarthttps://developers.openai.com/codex/quickstartOpenAI DevelopersPrompting Codexhttps://developers.openai.com/codex/promptingOpenAI DevelopersAGENTS.md 指南https://developers.openai.com/codex/guides/agents-mdOpenAI DevelopersCodex CLI Command Line Optionshttps://developers.openai.com/codex/cli/reference
