跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
AI 与知识库

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-fencedGemini 系列路径放在 fence 内非主流
udiffGPT-4 Turbo (1106)模仿 patch 程序的严格性,降低 laziness提示更重
patchGPT-4.1 (OpenAI patch 协议)多动作鲁棒模型特定
editor-diff / editor-wholearchitect 模式的 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 + Sonnet82.7%"entirely practical"
Sonnet + Sonnet80.5%比单跑 77.4% 高
GPT-4o + GPT-4o75.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
阅读完整来源 ↗