用途
Iterative Coder 是一个通过结构化迭代循环来精炼代码的技能。它不追求一次写出“完美”代码，而是依靠快速反馈循环：计划 → 编码 → 评估 → 改进。评估步骤会暴露仅靠思考无法预测的问题，例如 lint 错误、导入失败、测试回归和缺失的边界情况。
何时使用
- 主智能体委派以“MODE: MORE_EFFORT”为前缀的代码任务
- 用户为代码生成选择了“More Effort”模式
- 任务要求高代码质量并需要验证正确性
- 任务涉及复杂实现（5 个以上文件、多个模块）
- 希望对代码质量进行迭代，而不是提交第一版代码
- 提到“iterative refinement”“code quality loop”“plan-code-evaluate”
开始前：加载上下文
- 读取 /memory/experiment-memory.md 获取过往循环中验证过的策略（若不存在则跳过）
- 识别工作区中已有的测试、lint 配置（pyproject.toml、ruff.toml）或 CI 设置
- 检查可用工具：
ruff --version 2>&1; echo "---"; python -m pytest --version 2>&1
若任一工具缺失，则在评估时跳过该项检查（不要让迭代失败）。
阶段分解
迭代前先分析任务并拆分为顺序阶段：
| 任务复杂度 | 建议阶段数 |
|---|---|
| 单文件、定义明确的函数 | 1 个阶段 |
| 2-4 个文件、接口清晰 | 2 个阶段 |
| 5 个以上文件、多个交互模块 | 3-5 个阶段 |
每个阶段需定义：
- 名称：简洁标签（如“Data loading pipeline”）
- 目标：该阶段“完成”的标准
- 验证信号：如何确认阶段完成（特定测试、lint 通过、输出匹配）
按依赖关系排序阶段，后续阶段可建立在前面阶段之上。
迭代循环
每个阶段最多迭代 3 次。全局上限：所有阶段合计最多 10 次迭代。
步骤 1：计划
读取当前代码和上一次评估反馈（如有），写出简洁的改进计划。
- 阶段首次迭代：基于阶段目标写出初始实现计划。
- 后续迭代：先分析上次评估反馈并诊断失败根因，再规划变更。不要重复已经失败的做法。
根据上次评估的失败模式调整计划：
| 上次失败 | 计划响应 |
|---|---|
| 超时 | 添加 --quick/--smoke 模式、减少数据量、添加提前停止 |
| 语法错误 | 简化逻辑，运行 python -c "import ast; ast.parse(open('file.py').read())" 在运行前验证 |
| 导入错误 | 检查 pip list，只使用已安装的包，将缺失依赖加入 requirements |
| 测试失败 | 聚焦具体失败的测试，做最小针对性修改 |
| Lint 失败 | 在任何逻辑修改前运行 ruff check --fix . && ruff format . |
| 自评偏低 | 重读原始任务要求，检查缺失功能 |
步骤 2：编码
实现计划。保持变更聚焦于计划指定的内容。
- 除非计划明确要求，不要重写可正常工作的文件
- 写完代码后，快速通读变更文件做合理性检查
步骤 3：评估
关键：每次迭代都必须运行以下命令，不得跳过评估。
# 1. Lint check
ruff check . 2>&1 | tail -20
echo "LINT_EXIT: $?"
# 2. Format check
ruff format --check . 2>&1 | tail -10
echo "FORMAT_EXIT: $?"
# 3. Run tests (only if test files exist in workspace)
python -m pytest -x -q --tb=short 2>&1 | tail -30
echo "TEST_EXIT: $?"
若未安装 ruff，跳过检查 1-2。若未安装 pytest 或工作区无测试文件，跳过检查 3。记录哪些检查被跳过。
步骤 4：评分
由客观信号与自评计算综合得分。
客观信号（来自步骤 3 的退出码）：
- LINT_EXIT=0 → lint_score = 1.0，否则 lint_score = 0.0
- FORMAT_EXIT=0 → format_score = 1.0，否则 format_score = 0.0
- TEST_EXIT=0 → test_score = 1.0，否则从 pytest 输出解析通过比例（如“3 passed, 1 failed” → 0.75）
自评（0.0 – 1.0）：评估正确性（代码是否完成要求？）、完整性（所有需求是否覆盖？）、错误处理（是否覆盖合理边界情况？）、可读性（命名与结构是否清晰）。
综合得分——基于可用信号的动态权重：
- Lint + 测试均可用：0.2 × lint + 0.1 × format + 0.3 × test + 0.4 × self
- 仅 Lint（无测试）：0.3 × lint + 0.1 × format + 0.6 × self
- 仅测试（无 ruff）：0.4 × test + 0.6 × self
- 两者均不可用：1.0 × self
自评硬性上限——防止自评导致分数虚高：
- 若 lint 检查失败 → 综合得分上限 0.4，无论自评如何
- 若任一测试失败 → 综合得分上限 0.6
- 仅当 lint 与测试均通过且实现完整时，才可声称综合得分 ≥ 0.85
扣分项：明显情况缺少错误处理（−0.1）、硬编码绝对路径（−0.05）
评分边界情况详见 references/evaluation-protocol.md。
步骤 5：决策
- 综合得分 ≥ 0.85 → 进入下一阶段（若为最后阶段则完成）
- 综合得分 < 0.85 → 带评估反馈返回步骤 1
- 达到阶段迭代上限（每阶段 3 次）→ 仍进入下一阶段，记录遗留问题
- 达到全局迭代上限（共 10 次）→ 停止，输出当前最佳结果
步骤 6：记录
关键：每次迭代后追加到 /artifacts/iteration_log.md。
使用 assets/iteration-log-template.md 中的模板：
## Iteration {N} (Phase {M}/{T})
- **Score**: {composite} (lint={X} format={X} test={X} self={X})
- **Lint**: passed/failed ({N} issues)
- **Tests**: passed/failed ({passed}/{total})
- **Changes**: [{files changed}]
- **Feedback**: [{key evaluation findings}]
- **Next**: continue / next_phase / done
完成
所有阶段完成或达到全局迭代上限后，向调用方报告：
- 使用的总迭代次数
- 最终综合得分
- 各阶段关键改进（每阶段 1-2 句）
- 列出所有输出文件路径（代码、配置、测试）
- 记录遗留问题：lint 警告、缺失测试、已知限制、TODO
反直觉的迭代规则
- 先修 lint 再修逻辑：lint 错误会累积——一个导入错误会掩盖下游所有测试失败。在调查逻辑缺陷前始终先运行 ruff check --fix .。
- 每阶段 3 次迭代足够：若 3 次针对性迭代仍无法修复，问题在于架构（分解错误），而非增量问题。应进入下一阶段或重新规划，而不是继续迭代。
- 测试比阅读揭示更多：运行测试 10 秒比阅读代码 5 分钟更能了解正确性。即使确信代码正确，也要运行测试。
- 分数下降是信息：若某次变更后综合得分下降，这是关于什么重要的信号。在撤销变更前先分析下降原因。
- 不要镀金：目标是 0.85，不是 1.0。超过 0.9 后收益递减明显。先交付，必要时在下次对话中迭代。
技能集成
- 开始前（加载记忆）：参考 evo-memory → 读取 /memory/experiment-memory.md 获取先前策略
- 失败时（达到最大迭代仍卡住）：参考 experiment-craft → 5 步诊断流程，在重试前理解根因
- 成功时（所有阶段完成，得分 ≥ 0.85）：向主智能体报告 → 主智能体继续流水线（data-analysis、writing 等）
交接产物
| 产物 | 位置 | 使用者 |
|---|---|---|
| 迭代日志 | /artifacts/iteration_log.md | 主智能体摘要、evo-memory ESE |
| 最终代码 | 工作区根目录 | 下一流水线步骤 |
| 测试结果 | 迭代日志条目 | data-analysis-agent |
参考导航
| 主题 | 参考文件 | 何时使用 |
|---|---|---|
| 评分规则与边界情况 | evaluation-protocol.md | 出现评分边界情况时（部分测试、工具缺失） |
| 迭代日志模板 | iteration-log-template.md | 每次迭代（步骤 6） |