agentsop-aider
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.
agentsope · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add agentsope/SkillAlchemy --skill 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 |