Coding Agents

三大 Coding Harness 的架构分野

背景与原理

把三者放进同一张坐标系，分野立刻清楚。横轴是自主度（谁决定下一步：你 or 模型），纵轴是 edit 落地方式（模型怎么改文件）：

• Aider：git-native CLI。你显式 /add 文件进 context，模型用 search/replace diff 块返回改动，每次改动自动 git commit。控制流基本在你手里——它是高度可控的「半自动结对」，不是放养 agent。优势：git 历史即审计、可随时 /undo、token 极省。
• Cursor：IDE-native。核心是两段式——前台用 frontier model 做 planning（chat / composer），后台用专训的 fast-apply 模型（~70B, ~1000 tok/s）把意图落成文件 diff。tab 补全是另一条轻量自主链。优势：编辑器内零上下文切换、apply 飞快。
• Claude Code：terminal-native agent。完整 agentic loop——自己 Grep/Read 探索、自己决定改哪些文件、用 Edit 工具做 string replace、跑 Bash 验证。控制流在模型手里，你通过 permission gate + plan mode 约束。优势：开放任务的自主度最高。

关键 insight：这三者不是「谁更强」，是三个自主度档位。Aider 适合你心里有明确改动的批量执行；Cursor 适合编辑器内的高频小迭代；Claude Code 适合「我不确定怎么改、你去探索」的开放任务。选错档比选错模型代价大。

Edit Format：Coding Agent 被低估的隐藏瓶颈

背景与原理

一个反直觉事实：很多 coding agent 的失败不是逻辑错，是改动应用失败——模型生成的 search 块和文件里的实际文本对不上（空格、引号、它脑补的旧代码），patch 静默丢失或报错。Aider 的 leaderboard 把这点量化成核心指标：模型不仅要写对代码，还要不靠人工干预把所有改动成功 apply。四种主流 edit format 各有权衡：

• whole file（整文件重写）：模型吐整个文件。最容易让模型「写对」，但 token 爆炸、大文件直接超限、且容易顺手改坏无关行。
• unified diff：标准 @@ diff 格式。token 省，但模型经常算错行号/上下文，apply 失败率高。
• search/replace block（Aider 主力）：给一段精确的旧文本 + 新文本。比 unified diff 鲁棒（不靠行号，靠文本匹配），是 token 与可靠性的较优平衡点。
• apply model（Cursor 路线）：frontier model 只产出「意图 + 粗略 diff」，再交给专训小模型把它精确落地。把「想清楚」和「写准确」解耦——这是 Cursor 1000 tok/s instant apply 的核心。

核心权衡：whole file 最易写对但最贵；diff 最省但最易 apply 失败；search/replace 取中；apply model 用第二个模型买可靠性。这就是为什么不同 harness 在同一个 base model 上表现差很多——edit contract 不同。

实战示例

search/replace 块的精确长相（Aider / Claude Code 同源思路）——SEARCH 段必须和文件逐字符匹配：

src/auth.py
<<<<<<< SEARCH
def verify_token(token):
    return jwt.decode(token, SECRET)
=======
def verify_token(token):
    try:
        return jwt.decode(token, SECRET, algorithms=["HS256"])
    except jwt.ExpiredSignatureError:
        raise AuthError("token expired")
>>>>>>> REPLACE

实战启发：（1）让 agent 改大文件前先让它 Read 精确片段——它脑补的旧代码是 apply 失败头号原因；（2）改动尽量小而局部，一次 replace 一个语义单元，比一次重写整函数 apply 成功率高得多；（3)模型反复 apply 失败时，换 whole-file 模式兜底比硬刚 diff 划算。

Plan Mode：研究-计划-实现的分离不是 UX，是工程必需

背景与原理

Anthropic 的 Claude Code 最佳实践里有一条被反复强调：把研究/计划和实现分开。让 agent 直接开写，最大风险不是写得烂，是解错了问题——它对着症状打补丁，绕过你真正想改的根因。Plan mode 的工程价值有三层：

• 问题锁定：先只读不写地探索（Grep / Read），产出一份计划，强制 agent 在动手前把「要改什么、为什么」讲清楚。错误的方向在这步就能被你截停——这是最便宜的 verification，比事后 review 几百行 diff 便宜得多。
• 物理隔离：Claude Code 的 plan mode 在 harness 层禁止 Write/Edit/Bash——不是 prompt 求它别动手，是物理拦截。模型再「手痒」也改不了文件（呼应 Day 3 harness 的 permission gate）。
• 可审计：计划是文本，失败时能复盘是「计划错」还是「执行错」，比对着一坨乱改的 diff 调试清晰得多。

反直觉点：plan mode 的收益不来自模型多思考（那是 reasoning 的事），来自给人一个低成本的纠偏检查点。对开放任务（调试、跨文件重构、新功能），先 plan 几乎总值得；对一行修改，plan 是纯开销。

实战示例

把「explore → plan → code → commit」固化成工作流，而不是上来就让 agent 写：

# Claude Code：开 plan mode（Shift+Tab 切档），只读探索 + 出计划
> 研究 payment 模块怎么处理 retry，先别改代码，
  给我一份修复 double-charge bug 的计划：要动哪些文件、风险点、测试怎么加

# 你 review 计划，截停错误方向，确认后再切回执行档
> 计划 OK，但别碰 webhook handler。按计划实现，每改完一个文件跑一次相关测试

# Aider 等价做法：先用 /ask 只问不改，再切回 code 模式
/ask 这个 retry 逻辑哪里会导致重复扣款？应该怎么改？
# 满意后 /code 让它落地

关键纪律：计划里要求 agent 显式列「不碰什么」。coding agent 最常见的越界是顺手「优化」了你没让它动的代码——在 plan 阶段划好边界，比事后 review 拦截高效。

自主度光谱与 Closing the Loop

背景与原理

「AI pair programming」不是一个模式，是一条自主度光谱。每往右一档，吞吐越高、但你审查每行的能力越弱、错误传播越远。选档的依据是任务的可验证性——能不能让 agent 自己知道对错：

• Tab 补全：你写、它续。你 review 每一个 token。适合你心里有代码、只想打字快。
• Chat / inline edit：你描述局部改动，它出 diff，你逐个 apply。适合明确的小改。
• Full-auto agent：给目标，它自己 explore→edit→test→fix 多轮。适合开放任务，但只在能闭环验证时才安全。

右端的 full-auto 能不能 work，几乎完全取决于 closing the loop：agent 改完能否自己跑 tests / lint / type-check，把失败信息回灌给自己再修。能闭环（有测试、报错清晰）→ 放手让它自主迭代；不能闭环（UI 微调、无测试的脚本）→ 退回低自主档，你来当那个「测试」。这也呼应 Day 3：error 回灌是 agent 自我修复的根因。

实战示例

给 full-auto agent 显式的验证闭环，而不是只给目标就撒手：

> 修复 #482 的 race condition。工作纪律：
  1. 先写一个能复现 bug 的失败测试（red）
  2. 改代码让它变绿（green）
  3. 跑 `pytest tests/ -q` + `mypy src/`，全绿才算完成
  4. 任何一步红：把完整报错贴出来，分析后再改，别跳过

# 关键：给它一个客观的「完成」判据（绿）和验证工具，
# agent 才能自主闭环。没有这条，它会自我宣布「修好了」然后留一堆隐性 bug

这就是为什么 test-first 对 AI agent 比对人更重要：测试是 agent 唯一可信的「对错信号」。没有它，agent 的 self-eval 极不可靠——它倾向宣布成功（backward rationalization，Day 5 讲过）。先有红测试，full-auto 才敢放手。