/agentsop-aider

name: agentsop-aider
version: 1.0.0
description: >-
  SOP for terminal-based, git-native AI pair programming with Aider (git work-tree + tree-sitter repo-map + edit-format + human-in-loop REPL). Use when editing code in an existing git repo via an LLM, when you need to converge a change to 2-5 files, pick an edit format that fits the model, run architect+editor mode, or wire an auto-test loop.
domain: terminal-based AI pair programming, git-native code editing
source: aider.chat docs + Paul Gauthier's blog + leaderboards
audience: coder-agents and human engineers who edit code via LLMs

Aider SOP — 终端结对编程的操作系统

> 一句话：Aider 是“**git 工作树 + tree-sitter 仓库地图 + 编辑格式 + 人类在环 REPL**”的四元组。理解这四个原语，剩下的都是配置。

1. 何时激活本技能

下列任一情形成立时，按本 SOP 进入 Aider 工作模式：

• 任务是**编辑已有 git 仓库**里的代码（不是从零起项目）。
• 你能把改动范围**收敛到 2–5 个文件**，或愿意先用 `/ask` 让模型借助 repo-map 把范围找出来。
• 你需要**逐步可回滚**的修改历史（每次编辑一个 commit，`/undo` 一步回退）。
• 你在**终端**里工作（tmux / 远程 ssh / CI）；或者你在写一个把 Aider 当子进程驱动的 agent。
• 你关心**编辑格式对模型质量的影响**（diff / udiff / whole / patch 的选择问题）。
• 你需要 BYOM（自带模型），跑本地 LLM 或非主流厂商。

**不应激活的反面信号**：见 §6 反模式与边界。

2. 核心心智模型

2.1 四个原语

+------------------+   +------------------+   +------------------+   +------------------+
| 1. Git working   |   | 2. Tree-sitter   |   | 3. Edit format   |   | 4. REPL loop     |
|    tree          |   |    repo-map      |   |    (wire proto)  |   |    (你在环里)    |
|                  |   |                  |   |                  |   |                  |
| - per-edit       |   | - symbol-level   |   | - diff / udiff   |   | - /ask /code     |
|   commit         |   |   summary        |   |   / whole /      |   |   /architect     |
| - /undo          |   | - PageRank over  |   |   patch          |   | - 每轮人手确认   |
| - dirty 文件     |   |   import graph   |   | - 模型适配选择   |   | - 不自主         |
|   先 commit 再编 |   | - 动态预算       |   | - JSON 是反模式  |   |                  |
+------------------+   +------------------+   +------------------+   +------------------+

四者缺一不可：

• 去掉 git → 失去回滚与审计；
• 去掉 repo-map → 大仓库里 LLM 找不到正确文件（SWE-Bench Lite 上 repo-map 让 Aider 70.3% 命中正确文件 [aider.chat/2024/05/22/swe-bench-lite.html]）；
• 用错 edit format → 出现“lazy coding”、SEARCH 块找不到、JSON 句法破坏（udiff 在 GPT-4 Turbo 上把 refactor 基准从 20% 拉到 61% [aider.chat/2023/12/21/unified-diffs.html]）；
• 放弃 REPL → 退化为自主 agent，但 Aider 在 SWE-Bench 上恰好证明“人在环 + 多次尝试”比纯自主链路更稳。

2.2 LLM 看到的上下文分三层（优先级递减）

| 层 | 内容 | 谁能改 | |---|---|---| | 系统提示 + 编辑格式说明 | Aider 固化 | Aider | | 只读上下文 | repo-map + `/read` 文件 + CONVENTIONS.md | 你（通过 `--read`） | | 读写上下文 | `/add` 的文件 | LLM **只能编辑**这里的文件 |

> **铁律**：LLM 只允许编辑 `/add`-ed 的文件。这是 Aider 的安全边界。模型“改错了文件”几乎总是因为该文件没 `/add` 或你 `/add` 了太多无关文件。

2.3 上下文预算（25k 信号阈）

> "Above about 25k tokens of context, most models start to become distracted." [aider.chat/docs/troubleshooting/edit-errors.html]

把这条当硬约束：超过 25k tokens，编辑准确率断崖式下降。`/tokens` 持续监控。

2.4 Repo-map 不是 RAG

repo-map 是 **tree-sitter 提取的符号清单**（类、函数、签名），用 PageRank 在源文件依赖图上排序，**塞给 LLM 当地图**。这不是 embedding 检索。

为什么不用 embeddings：

• LLM 能读签名，但读不懂向量。
• 不需要维护索引/重建/失效；代码改了下次自动重生成。
• `/map` 可以打印出来人工审计，向量做不到。

预算是**动态**的：你不 `/add` 任何文件时，map 占用大；`/add` 了正确文件后，map 自动缩小，省下的 token 给真正的代码。

2.5 编辑格式是“模型适配问题”，不是“用户偏好”

| 格式 | 谁用 | 强项 | 弱项 | |---|---|---|---| | `whole` | 弱模型 / GPT-3.5 / 应急回退 | 解析最稳，无 merge 错误 | 贵；4k 输出上限会截断 | | `diff` (SEARCH/REPLACE) | GPT-4o, Sonnet, 多数强模型 | token 高效 | SEARCH 块必须字节匹配 | | `diff-fenced` | Gemini 系列 | 路径放在 fence 内 | 非主流 | | `udiff` | GPT-4 Turbo (1106) | 模仿 patch 程序的严格性，降低 laziness | 提示更重 | | `patch` | GPT-4.1 (OpenAI patch 协议) | 多动作鲁棒 | 模型特定 | | `editor-diff` / `editor-whole` | architect 模式的 editor 子模型 | 提示更瘦，专注编辑 | 仅在 architect 下有意义 |

Aider 已经对常见模型选好默认值；**只有出现编辑错误时才覆盖**。

> ⇒ **不要**把代码编辑包进 JSON tool-call。所有模型在 Aider 的实测里都因此变差，包括 Sonnet（详见 §5 案例 6 与引文）。

3. SOP 工作流

Phase 1 — Bootstrap（每次会话开始）

# 0. 在 git 仓库根目录。stash 或 commit 在途修改。
git status

# 1. 选模型（榜单当前前列：gpt-5, claude-3.7-sonnet, o3-pro, gemini-2.5-pro）
#    [aider.chat/docs/leaderboards/]

# 2. 最小启动 — 让 repo-map 帮 LLM 自己找路
aider

# 3. 范围已知 — 直接预加 + 风格文件
aider src/auth.py tests/test_auth.py --read CONVENTIONS.md

# 4. 强思考 + 廉价编辑（architect 模式）
aider --architect --model o1-preview --editor-model gpt-4o

# 5. 自动测试回路
aider --test-cmd "pytest -x" --auto-test

# 6. 巨型 monorepo
cd packages/feature-foo && aider --subtree-only
# 并维护 .aiderignore

Phase 2 — 收敛范围（`/add` 纪律）

不知道改哪个文件？
  → /ask which files implement <feature>?     (LLM 用 repo-map 回答)
  → /add 它命名的文件（只加这些）

知道改哪个文件？
  → 启动时 CLI 直接传，或 /add path/to/file.py

需要参考但不允许改的文件（schema, config, conventions）？
  → /read path/to/ref.md

铁律重申：**少 `/add`，敢 `/drop`**。`/tokens` 看现状。

Phase 3 — 讨论再动手（`/ask` → `/code`）

> /ask 当前的 auth 怎么实现？如果改成 JWT 会有什么破坏？
< [模型基于 repo-map + 已 /add 的文件作答]

> /ask 那我们用 PyJWT 还是 authlib？给出权衡。
< [...]

> /code 按刚才讨论的方案，把 sessions 改成 JWT。
< [模型给出 diff]
[Aider 自动应用 → 自动 git commit]

> /test pytest
< [失败时模型看到输出并尝试修复]

> "Break your goal down into bite sized steps. Do them one at a time." [aider.chat/docs/usage/tips.html]

Phase 4 — Architect 模式（reasoning ≠ editing）

何时开启：**你最好的 reasoner 编辑能力差**（典型：o1-preview 单独跑 79.7%，搭配 Sonnet 当 editor 拉到 82.7% [aider.chat/2024/09/26/architect.html]）。

| 组合 | Polyglot Pass@2 | 备注 | |---|---|---| | o1-preview (architect) + o1-mini (editor, whole) | 85% | SOTA 当时；慢，不适合交互 | | o1-preview + Sonnet | 82.7% | "entirely practical" | | Sonnet + Sonnet | 80.5% | 比单跑 77.4% 高 | | GPT-4o + GPT-4o | 75.2% | 比单跑 71.4% 高 |

启用：`--architect` 或 `/architect`。Aider 自动把 editor 切到 `editor-diff` / `editor-whole`。

Phase 5 — 验证（lint / test / run）

/lint                  # 默认 --auto-lint 已开
/test pytest -x        # 失败时输出回填到 chat
/run npm run typecheck # 输出可选择性回填
/diff                  # 看上一轮的 diff

> "Aider will try and fix any errors if the command returns a non-zero exit code." [aider.chat/docs/usage/lint-test.html]

formatter 注意：把会重写文件并返回非零的 formatter 包装在双跑脚本里（第一遍 format，第二遍验证）。

Phase 6 — 上下文卫生

| 症状 | 操作 | |---|---| | `/token