【Code Buddy Agent 实践】国际化最佳实践
文章目录
- 一、为什么这类任务必须用 Agent 模式
- 二、Agent 在大规模代码改造中的边界
- 2.1 任务有多大
- 2.3 我们怎么把任务重新设计
- 三、Agent 指令设计：把任务写成可执行协议
- 3.1 先别写模板，先写指令结构
- 3.2 再给一个“任务卡”样板
- 3.3 再写“单文件 / 大文件 / 批量文件”的差异
- 3.4 最后写“为什么这样写更适合 Agent”
- 四、Agent 协作 SOP：从样板到批量收口
- 4.1 角色分工与前置标准
- 4.2 任务推进流水线
- 4.3 验收与收口
- 4.4 返工机制
- 五、失败模式、修复机制与模型选型结论
- 5.1 典型失败模式
- 5.2 修复机制
- 5.3 模型对比与使用感受
- 5.4 最终结论
本文基于 3000+ Java 文件的国际化改造实践，沉淀一套可复用的 Agent 执行方法：如何把大任务拆成可控的小任务，如何在多轮修改中保持上下文一致，如何通过自检和验收把遗漏率压到可接受范围。
一、为什么这类任务必须用 Agent 模式
本次任务不是简单的中文替换，而是一次大规模、跨文件、强约束的代码治理任务。
它同时满足三个特征：文件量大、模式多、验收严。如果只靠人工逐文件处理，成本高且容易遗漏；如果只给一句模糊指令，Agent 也很难稳定收敛。
因此，这类任务最适合用 Agent 模式来完成：先识别模式，再拆分任务，最后通过自检和验收闭环收口。
二、Agent 在大规模代码改造中的边界
2.1 任务有多大
这次任务的难点不在于“改什么”，而在于“规模太大、模式太杂、验收太严”。
2.2 Agent 容易卡在哪里
实践证明，Agent 不是不会改，而是超长文件和多模式写法会让它更容易只完成局部修改并且认为达到标准。
2.3 我们怎么把任务重新设计
所以后面我们不再要求 Agent 一口气做完，而是把任务拆成可验证、可收口的执行窗口。
三、Agent 指令设计：把任务写成可执行协议
3.1 先别写模板，先写指令结构
好的 Agent 指令，不是“说得更像人话”，而是把任务写成能执行、能检查、能收口的协议。
3.2 再给一个“任务卡”样板
3.3 再写“单文件 / 大文件 / 批量文件”的差异
不同任务类型不是换一个说法而已，而是要换一套指令颗粒度。
3.4 最后写“为什么这样写更适合 Agent”
我们最终把任务从“口头描述”改成“任务协议”，核心变化不是表达方式，而是让 Agent 每一步都有明确目标和可验证结果。
四、Agent 协作 SOP：从样板到批量收口
前面我们已经明确了任务边界，也把任务写成了可执行协议。接下来真正重要的是，如何把这些规则落到执行过程中。我们的做法不是一开始就批量推进，而是先用样板文件验证规则，再按文件大小和模块复杂度逐步扩展，最后通过统一验收收口。
4.1 角色分工与前置标准
Agent 不是独立交付者，而是执行者。真正决定结果的，是前置标准是否清楚，职责边界是否明确。
4.2 任务推进流水线
我们的执行顺序不是一上来就批量改，而是先用一个样板文件校准规则，再把同一套规则复制到大文件和批量文件中。这样可以先验证方向，再扩大范围，避免一开始就进入不可收口的状态。
4.3 验收与收口
是否达到完成标准，要以“验收是否清零”为标准。只要搜索结果还有残留，就说明任务还没有真正收口。
4.4 返工机制
如果验收未通过，不要整体重来，而是回到对应片段重新处理。
对于超长文件，优先补漏局部；
对于批量任务，优先修正同类模式；
对于参数化问题，优先回看原始表达式。
五、失败模式、修复机制与模型选型结论
5.1 典型失败模式
本次国际化改造里，Agent 最常见的失败不是“完全不会改”，而是“改到一半开始失焦”。尤其在大文件、多轮修改、多种写法混杂的场景下，局部修改看起来完成了，但全局仍可能残留旧写法、漏改分支或参数丢失。
5.2 修复机制
针对这些失败模式，我们后来把任务治理方式固定成一套可复用的修复机制，而不是每次临时补救。
- 先做样板文件。
先选一个中等复杂度文件，把规则跑通，形成“金标准”。 - 大文件强制分段。
超过一定行数的文件，不再要求一次性处理完，而是按区间拆开。 - 每轮都做自检。
每次修改后都必须搜索 ResultStatus、中文硬编码和参数占位符，不能只看 Agent 自述完成。 - 错误码先统一再新增。
先检查是否已有可复用错误码，避免同义重复。 - 最后人工收口。
对关键文件、参数化消息和边缘情况进行人工复核，确保结果可交付。
如果把这套机制画成流程，就是：
这也是这次实践最重要的经验之一：
Agent 不是“一次性替人干完”，而是要放在一个可控的执行链路里，才能真正稳定交付。
5.3 模型对比与使用感受
这次实践里，我实际使用了 Code Buddy 、Cursor 和 Codex 三类工具链，整体感受很明显。
| 工具/模型 | 实际感受 | 优势 | 存在问题 | 适用场景 |
|---|---|---|---|---|
| Code Buddy（Kimi2.5 / GLM5 / DeepSeekV3.2） | 其中 kimi2.5 的综合能力最好，但整体工具稳定性一般 | 上手快，适合初步改动和局部处理 | 多轮对话后容易明显变慢，偶发卡顿甚至卡崩，写出来的 bug 也相对更多，常需要重启 IDE 恢复，影响进度 | 前期试探、简单任务、局部修改 |
| Cursor（Auto 模式 / Kimi2.5） | 响应快，考虑更全面，连续编辑体验更好 | 响应快，考虑更全面，连续编辑体验更好 | 也会崩，但频率低很多 | 中期主力推进、连续修改 |
| Codex（gpt-5.3-codex / gpt-5.4mini） | 整体体验最强，尤其是 gpt-5.3-codex | 处理 bug、修复漏改、长上下文补漏能力很强；支持 258k 上下文，并且会主动压缩上下文信息；稳定性最好，使用过程中没有出现卡崩 | 更适合明确任务边界的工程化场景 | 后期补漏、复杂修复、最终收口 |
如果只看 Code Buddy 体系内部的模型表现，Kimi2.5 的综合能力最好。如果看整条任务链路的稳定性和复杂修复能力，Codex 的整体表现最强。Cursor 则更像是一个“稳定性和效率都更均衡”的中间层，适合作为中期主力工具。
更直接地说，这次实践里我形成的分工感受是：
- Code Buddy 更适合前期试探和简单修改
- Cursor 更适合中期连续推进
- Codex 更适合后期补漏和最终收口
5.4 最终结论
这次实践说明，Agent 最适合处理的不是“随便改一改”的任务，而是“规则明确、模式可识别、结果可验收”的大规模代码治理任务。真正决定效果的，不只是模型本身强不强，而是任务边界是否清楚、执行流程是否稳定、验收机制是否足够硬。
如果把这套经验浓缩成一句话，就是：
Agent 的价值不在于一次性写完，而在于把大任务拆成可验证、可收口的执行链路。