Codex 把调查结果整理成项目理解报告

测试环境（核验信息） Windows 11 24H2（Build 26100）；Codex Desktop 26.820.7780.0；Codex CLI 0.147.0；Git 2.47.0.windows.2；2026-08-27 核验。

只读调查结束后，终端里通常已经积了一屏命令，聊天里也有不少结论。问题是，换一个人接手，他还是不知道从哪里改、判断依据是什么、还缺哪条证据。

项目理解报告接在调查记录之后，负责把能影响决定的内容整理出来。读者拿到它，应该能复核现状，知道下一步怎么做。

图一　把文件发现、命令记录和风险提示收束成一份可交接报告。

先区分两种产物

调查记录回答“我看到了什么”，项目理解报告回答“目前可以据此做什么”。前者允许保留搜索过程，后者只留下影响判断的证据。

如果一条信息不能帮助读者复核现状、评估风险或安排下一步，它通常不需要进入报告正文。

报告先写结论，再补证据

我通常把报告分成下面六块。这个顺序能让结论先落地，再补证据和行动边界。

1. 范围与结论。写清调查对象、分支、时间和当前判断。
2. 项目地图。列出入口文件、核心模块、测试目录、运行命令及其关系。
3. 已确认事实。每条事实附上文件路径、符号、命令或输出。
4. 基于证据的推断。说明推断链，别把推断写成代码已经证明的事实。
5. 未知项与风险。列出缺少的运行证据、未覆盖的分支和可能影响。
6. 建议步骤。把下一轮任务写到文件、符号、改动边界和验收方式。

图二　终端案例展示项目地图与代码证据，并将它们整理成报告条目。

一条结论至少要有一个证据锚点

证据锚点通常来自四个地方。

• 文件路径和行号，例如 src/discounts.py:4 的 apply_discount。
• 代码符号之间的调用或导入关系。
• 命令及其关键输出，例如 python -m unittest discover -s tests -v 的失败用例。
• Git 状态、提交记录或差异，用来说明调查前后是否发生了改动。

不要把“看起来像入口”“应该是缓存问题”直接放进事实栏。看起来像入口是推断，缓存问题是待验证假设。

用一个小项目演示

本文使用 temp/workflow-demo/，这是一个不含真实业务数据的 Python 练习项目。README 说明它有四类练习，探索、修复折扣计算、重构重复逻辑和补测试。运行命令如下。

cd .\temp\workflow-demo
python -m unittest discover -s tests -v

只读调查时先看目录和入口，再看实现与测试。

rg --files
rg -n "apply_discount|order_total|shipping_total|unittest" README.md src tests
git status --short --branch
git log --oneline --max-count=5

这几条命令能回答“项目怎么跑、核心函数在哪里、测试覆盖什么、调查期间有没有动过仓库”，但不会自动证明业务行为正确。

把发现压缩成项目地图

针对这个项目，报告里的地图可以只保留五行。

README.md                       任务说明、运行命令和当前已知问题
src/discounts.py                折扣、订单总价和运费总价的实现
tests/test_discounts.py         unittest 行为测试，包含成功、异常和边界
python -m unittest ...          唯一记录在 README 中的测试入口
风险                           README 声称保留一个 Bug，需以实际测试输出确认

注意最后一行仍然是风险提示。README 的描述是项目文档事实，Bug 是否仍能复现，要靠运行结果确认。

事实、推断和未知项怎么写

可以用同一条发现演示三种写法。

这张表里的“未知项”不能被省略。读者知道哪里没有证据，才不会把一段合理猜测当成已经验证的结论。

图三　从文件、符号、命令到 Git 记录，证据越具体，结论越容易复核。

把证据写成可复核引用

正文不需要复制整段源码，引用到能定位的最小单位就够了。

结论：折扣计算入口是 apply_discount。
证据：src/discounts.py:4；函数在 :7 检查 price < 0，在 :9 检查 percent 范围，:10 返回 round(...)。
验证：python -m unittest discover -s tests -v；需记录实际通过/失败数量。

命令输出也要保留原貌，至少包括命令、关键行和执行时间。不要只写“测试通过”，更不要在没有运行时把 README 里的预期结果写成实际结果。

Git 证据建议成对记录。

调查开始：git status --short --branch -> [原始输出]
调查结束：git status --short --branch -> [原始输出]
判断：两次输出一致，调查期间未发现新增改动；若不一致，逐项解释来源，不自行清理。

报告模板

下面的模板可以直接复制到项目文档、任务评论或交接记录中。

# 项目理解报告：<主题>

调查范围：<仓库 / 分支 / 时间>
一句话结论：<当前最重要的判断>

## 项目地图
- 入口：<文件:行号 / 符号>
- 核心路径：<入口 -> service -> 数据或适配层>
- 运行命令：`<命令>`
- 测试入口：`<命令>`

## 已确认事实
- [事实] <结论>；证据：<文件:行号、命令或 Git 输出>

## 基于证据的推断
- [推断] <判断>；依据：<两条以内的证据>

## 未知项与风险
- [未确认] <还缺什么证据>；影响：<可能阻塞的决定>

## 下一步计划（尚未执行）
1. <文件:符号>：<最小改动>；原因：<对应证据>
2. 验证：<测试命令 / 手工检查 / 预期结果>
3. 停止条件：<出现什么情况就暂停并回报>

模板里的“尚未执行”很重要。它把调查和修改分成两个授权阶段，下一位执行者可以直接接着做，也能清楚知道哪些动作还没有发生。

从报告转成开发任务

一份报告合格的标志，是它能在不重新调查的情况下生成下一轮任务。转换时只保留四个要素。

1. 目标文件和符号。不要只写“修复折扣逻辑”，写成 src/discounts.py:4 apply_discount。
2. 允许的范围。例如只改公式，保留参数校验和返回值格式。
3. 证据和验证。先复现失败测试，再展示差异，最后运行完整测试集。
4. 停止条件。实际结果与报告不一致，或发现共用逻辑会影响订单总价时，先停下来确认。

以本例为例，下一轮任务可以这样写。

图四　完整报告将推断、未知项、风险和下一步任务分开记录，并保留停止条件。

只处理 src/discounts.py 的 apply_discount。先运行
python -m unittest discover -s tests -v，记录失败用例和实际值。
确认百分比公式后做最小修复，不改函数签名、参数校验和其他公开函数。
展示 git diff，再运行完整测试。若 order_total 或 shipping_total 也受影响，暂停并报告。

这段任务保留了报告里的证据、边界和暂停点，执行者可以据此继续。

图五　报告把项目地图、证据和停止条件交给下一轮开发任务。

常见的四个误区

把搜索过程当报告。 rg 查了几十个文件，读者仍可能不知道哪个入口重要。报告应删掉不影响判断的路径。

把推断写成事实。 函数名相似、目录名熟悉，都不能代替调用关系或运行输出。

把预期结果当验证结果。 README 写“第一次会失败”，只能说明项目作者的意图；当前工作树是否如此，要重新运行。

为了完整而复制源码。 引用路径、符号和关键行就够了。大段源码会掩盖风险，也让报告很快过期。

交付前检查

• 报告开头写了调查范围、分支和核验时间。
• 每条事实都有路径、符号、命令或 Git 证据。
• 推断注明依据，未知项明确写“未确认”。
• 运行命令和实际输出没有互相冒充。
• 下一步任务包含改动边界、验证方式和停止条件。
• 调查前后的 Git 状态已对照；发现变化时没有擅自清理。
• 报告长度能让接手者在几分钟内定位入口，而不是重新读完整个仓库。

项目理解报告要把三件事写清楚，当前知道什么，哪些地方仍缺证据，下一步能安全做什么。这样下一次任务才能接着往下走。

参考资料

• OpenAI Codex 文档。Codex 产品与工作流入口，页面于 2026-08-27 通过 Jina Reader 核验。
• Codex CLI 文档。CLI 使用入口，页面于 2026-08-27 通过 Jina Reader 核验。
• git-log 官方文档。用来记录提交历史和调查依据。
• git-diff 官方文档。用来检查改动范围和差异。

图六　Git 官方 git-status 文档中对工作树、暂存区和未跟踪文件的说明。页面内容可能随 Git 版本更新。

项目理解报告写完后，下一轮任务可以直接引用其中的文件路径、证据、风险和验证命令。