experiment-iterative-coder

迭代式编码

通过结构化的“规划 → 编码 → 评估 → 改进”循环，迭代完善代码。每轮都会运行客观检查（lint、测试）并进行自我评估，随后诊断问题并规划有针对性的改进。经过 3-8 轮迭代，达到可用于生产环境的质量。

何时使用此技能

• 主 Agent 委派了一项代码任务，且前缀为 “MODE: MORE_EFFORT”
• 用户为代码生成选择了 “More Effort” 模式
• 任务需要高质量代码和经过验证的正确性
• 任务涉及复杂实现（5 个以上文件、多个模块）
• 你希望通过迭代提升代码质量，而不是提交第一版代码
• 你提到了“迭代改进”“代码质量循环”或“规划-编码-评估”

迭代思维

代码质量来自快速反馈循环，而不是谨慎地尝试一次就写好。 快速进行“规划 → 编码 → 评估 → 修复”循环，胜过花 30 分钟试图实现“完美”的初版。评估步骤会揭示单靠思考无法预见的问题——lint 错误、导入失败、测试回归和遗漏的边界情况，都会在实际运行代码时立即显现。

开始之前：加载上下文

1. 阅读 /memory/experiment-memory.md，了解以往循环中验证有效的策略（如果文件不存在，则跳过）
2. 在工作区中查找现有测试、lint 配置（pyproject.toml、ruff.toml）或 CI 设置
3. 检查可用工具：

   ruff --version 2>&1; echo "---"; python -m pytest --version 2>&1
   

   如果其中任一工具不可用，则在评估时跳过相应检查（不要因此判定本轮失败）。

阶段分解

开始迭代前，分析任务并将其拆分为按顺序执行的阶段：

任务复杂度	建议阶段数
单个文件、定义明确的函数	1 个阶段
2-4 个文件、接口清晰	2 个阶段
5 个以上文件、多个相互作用的模块	3-5 个阶段

为每个阶段定义：

• 名称：简洁的标签（例如“数据加载管道”）
• 目标：该阶段完成后的预期状态
• 验证信号：如何确认阶段已完成（具体测试、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. 向调用方报告：
   • 使用的迭代总次数
   • 最终综合得分
   • 各阶段的主要改进（每个阶段 1–2 句话）
2. 列出所有输出文件路径（代码、配置、测试）
3. 注明剩余问题：Lint 警告、缺少的测试、已知限制、TODO

反直觉的迭代规则

1. 先修复 Lint，再处理逻辑：Lint 错误会层层叠加——一个导入错误就可能掩盖后续所有测试失败。调查逻辑错误前，务必先运行 ruff check --fix .。

2. 每个阶段迭代 3 次就够了：如果经过 3 次有针对性的迭代仍无法修复，问题就是架构性的（分解方式错误），而非渐进式的。应进入下一阶段或重新规划，而不是继续迭代。

3. 测试比阅读更能揭示问题：运行测试 10 秒，比读代码 5 分钟更能帮助了解正确性。即使确信代码正确，也务必运行测试。

4. 得分下降也是一种信息：如果修改后综合得分下降，这说明了哪些方面更重要。撤销修改前，先分析得分下降的原因。

5. 不要过度打磨：目标是 0.85，而不是 1.0。超过 0.9 后，收益会急剧递减。完成并交付；如有需要，可在下一次对话中继续迭代。

技能集成

开始之前（加载记忆）

参阅 evo-memory → 阅读 /memory/experiment-memory.md，了解以往策略

失败时（达到最大迭代次数后仍受阻）

参阅 experiment-craft → 按照 5 步诊断流程，在重试前找出根本原因

成功时（所有阶段完成，得分 ≥ 0.85）

向主 Agent 报告 → 主 Agent 继续执行工作流（数据分析、写作等）

交接产物

产物	位置	使用方
迭代日志	/artifacts/iteration_log.md	主 Agent 摘要、evo-memory ESE
最终代码	工作区根目录	下一流水线步骤
测试结果	迭代日志条目	data-analysis-agent

参考导航

主题	参考文件	使用时机
评分规则和边缘情况	evaluation-protocol.md	出现评分边缘情况时（部分测试、缺少工具）
迭代日志模板	iteration-log-template.md	每次迭代（步骤 6）