端到端开发案例

以下案例不是特定框架教程，而是一套可迁移到多数仓库的协作节奏。任务：给已有 Web 项目增加“导出 CSV”功能，同时保持现有 API 不变。

第 0 步：建立基线#

先由人确认仓库当前是健康的：

git status --short
npm test
npm run lint

如果基线已经失败，要把失败写进任务背景。否则 Codex 无法判断错误是新引入的还是原本就存在。

第 1 步：只读侦察#

先不授权修改：

请只读分析这个仓库，定位列表数据的获取、展示和测试位置。
不要改文件。输出：
- 相关文件及各自职责；
- 最小实现路径；
- 可能破坏现有行为的风险；
- 建议的验证命令。

评审它的理解：是否找到了数据边界、是否注意编码和大数据量、是否识别已有工具函数。若方向不对，此时纠正成本最低。

第 2 步：锁定任务边界#

实现列表页“导出 CSV”功能。

范围：
- 只导出当前筛选结果；
- 字段顺序为 name、email、created_at；
- UTF-8 with BOM，确保 Excel 打开中文正常；
- 保持现有查询 API 不变。

验证：
- 为转义逗号、引号、换行和中文补单元测试；
- 运行相关测试与 lint；
- 不修改无关格式。

交付：
- 总结改动；
- 列出验证命令和结果；
- 说明仍存在的边界情况。

这份任务单同时提供目标、约束、失败边界和验收方式。比“帮我加个导出”更容易一次得到可审查结果。

第 3 步：小步实现#

要求 Codex先改纯函数与测试，再接 UI。拆分顺序：

1. CSV 序列化函数；
2. 边界测试；
3. 下载触发逻辑；
4. 按钮和状态；
5. 回归检查。

每一步都应保持差异小且目的单一。若代理开始大范围重命名，及时要求停止并解释必要性。

第 4 步：看差异，不只看总结#

至少检查：

git diff --stat
git diff --check
git diff

重点问五件事：

• 输入为空时会怎样？
• 字段中有双引号、换行时是否正确转义？
• 导出是否复用了当前筛选条件？
• 浏览器对象 URL 是否被释放？
• 是否改动了任务范围之外的接口？

总结是导航，差异才是证据。

第 5 步：分层验证#

如果某项无法运行，交付说明必须写清“未运行”及原因，不能用“应该没问题”代替。

第 6 步：形成可合并交付#

理想收尾包含：

完成：
- 新增 src/utils/csv.ts，集中处理序列化与 BOM；
- 列表工具栏增加导出入口；
- 新增 8 个边界测试。

验证：
- npm test -- csv：通过；
- npm run lint：通过；
- 人工下载：已检查中文与引号字段。

未做：
- 未增加服务端批量导出；当前功能只覆盖已加载筛选结果。

失败模式与纠偏#

一次交给它整个“大功能”#

结果通常是上下文过多、差异过大。纠偏：先侦察，再按可独立验证的切片执行。

测试只验证正常输入#

纠偏：在任务中显式列出失败样例、边界字符和空状态。

代理顺手清理无关代码#

纠偏：要求“不要修改无关格式”，并以 git diff --stat 监控扩散。

命令通过就直接合并#

自动测试不能替代产品验收。对用户可见行为仍需一次人工检查。

可复用检查单#

• 基线状态已记录
• 先完成只读侦察
• 范围与禁区明确
• 实现被拆成小步
• 人看过完整差异
• 关键边界有测试
• 未验证项被明确披露