agentsop-context-scope-discipline
Coder-agent working-file budget discipline: keep the editable working set (files you /add into writable context) under ~25k tokens, separate "read" from "edit", delegate breadth to a read-only repo-map, and drop files once edited. Use when an LLM coder-agent edits multiple files, when the working set must stay focused, or when the model starts editing the wrong file / missing targets because too much context dilutes attention. Search keywords: context window full, agent edits wrong file, too much context, /add /drop files, working file budget, context dilution, lost in the middle.
agentsope · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add agentsope/SkillAlchemy --skill agentsop-context-scope-discipline技能说明
name: agentsop-context-scope-discipline version: 0.1.0 description: >- Coder-agent working-file budget discipline: keep the editable working set (files you /add into writable context) under ~25k tokens, separate "read" from "edit", delegate breadth to a read-only repo-map, and drop files once edited. Use when an LLM coder-agent edits multiple files, when the working set must stay focused, or when the model starts editing the wrong file / missing targets because too much context dilutes attention. Search keywords: context window full, agent edits wrong file, too much context, /add /drop files, working file budget, context dilution, lost in the middle. domain: working-file budget management for LLM coder-agents (multi-file editing) source: aider.chat troubleshooting/edit-errors (25k distraction threshold) + /add /drop discipline; generalized across coder harnesses audience: coder-agents (Aider/Claude Code/Cursor/Cline/custom) editing multiple files where the working set must stay focused status: enhancement overlay — sharpens the generic token-budget rule into a coding-agent-specific working-file discipline type: enhance overlays: token-budget skills (this adds the coder-agent "only load what you'll edit" rule) crosslinks: "[[agentsop-repo-map]], [[agentsop-session-state-hygiene]]"
Context Scope Discipline — 只把你要改的文件放进工作集
一句话:编辑代码时,工作文件预算(你
/add-ed 进可写上下文的文件)要压在 ~25k tokens 以内。超过这个量,"more context ≠ better edits"——模型注意力被稀释,开始改错文件、漏看你刚加进去的目标。广度交给 [[agentsop-repo-map]](只读签名地图),深度只留给"这次真要编辑"的那几个文件。
这是一个增强叠加技能(enhance overlay)。它不替代任何"通用 token 预算"建议,而是把那条泛泛的"少塞上下文"打磨成一条 coder-agent 专属的硬规则:区分"读"与"改",只把"改"的文件加进工作集。借用 Aider 的实测阈值——
"Above about 25k tokens of context, most models start to become distracted." [aider.chat/docs/troubleshooting/edit-errors.html]
1. 何时激活本技能
下列任一情形成立时,把"工作文件预算纪律"作为该编辑会话的标准约束:
- 任务是多文件编辑:rename、抽函数、改 API 签名、加 hook 点——你需要理解 N 个文件,但只会真正修改其中一小部分。
- agent 正在改错文件:给出的 diff 落在你没想改的文件上,或编造了不存在的路径。这几乎总是"工作集不对"——目标没加进去,或加了太多无关文件把模型呛晕。
- 上下文窗口在涨:
/tokens(或等价物)逼近 25k;响应被截断;长会话里模型"记住了错的东西"。 - 你在大仓库里工作,凭"为了保险全加进去"的本能正在把整个目录、整个 repo 灌进可写上下文。
- 你在写自建 coder harness,需要一条明确的"可编辑文件白名单何时收/何时放"的规则。
不应激活的反面信号:单文件已知的小改动(工作集天然就是 1);纯讨论/架构问答(用只读上下文 + [[agentsop-repo-map]] 即可,不进工作集);非编辑任务。
2. 核心心智模型
2.1 一句话铁律
more context ≠ better edits. 过了约 ~25k tokens 的文件量,模型就开始失焦——只把你这一轮真要编辑的文件加进工作集,其余的靠 [[agentsop-repo-map]] 顶上。
2.2 "读" vs "改"是两种不同的上下文,需要两种不同的预算
LLM 看到的编辑上下文分三层,优先级与写权限递减:
| 层 | 内容 | 写权限 | 预算策略 |
|---|---|---|---|
| 系统提示 + 编辑格式 | harness 固化 | harness | 不可控 |
| 只读上下文 | [[agentsop-repo-map]] 签名地图 + /read 的参考文件 + CONVENTIONS.md | 人/agent 配置 | 给"广度"——用地图覆盖全仓,但只放签名不放函数体 |
| 工作集(写集合) | /add-ed 的文件 | LLM 唯一能编辑的 | 给"深度"——只放这次真要改的,压在 ~25k 以内 |
核心区分:repo-map 给"哪儿"(breadth,签名级,便宜),工作集给"怎么改"(depth,全文级,贵)。把这两种需求混进同一个篮子("全
/add进来再说")是本技能要根除的反模式。
2.3 25k 是稀释阈,不是上限
25k 不是"塞到 25k 就崩",而是"过了 25k 编辑准确率开始断崖式下降"。它是个信号阈:
- 工作集本身 + 对话历史 + repo-map 都算进这一份预算。
- 文件越多、越大,留给"模型对当前编辑点的注意力"越少。
- 模型越弱,对 25k 越敏感(弱模型"更容易违背系统提示" [aider.chat/docs/troubleshooting/edit-errors.html])。
2.4 "全加进去保险"是错觉——repo-map 已经替你覆盖了广度
凭直觉,"我要理解这 10 个文件才能改对,那就全 /add"。实测相反:
Aider 只靠 repo-map(不把文件加进工作集)在 SWE-Bench Lite 上仍 70.3% 命中正确文件 [aider.chat/2024/05/22/swe-bench-lite.html]。
即"找文件"这件事不需要把文件灌进工作集——只读地图就够了。工作集只为"编辑"存在。把这两件事拆开,是省预算的关键。详见 [[agentsop-repo-map]]。
2.5 动态预算:工作集涨,地图就该缩
预算是一份蛋糕,不是各自独立的盘子。/add 了正确文件后,[[agentsop-repo-map]] 应自动缩小("adjusts ... based on the state of the chat" [aider.chat/docs/repomap.html]),把 token 让给真代码。如果你的 harness 不会自动缩地图,编辑期就手动 --map-tokens 调小或归零。
2.6 与 [[agentsop-session-state-hygiene]] 的分工
本技能管文件维度(工作集里有哪些文件);[[agentsop-session-state-hygiene]] 管历史维度(对话历史是否污染当前任务)。二者共用同一份 25k 预算:
- 预算超了,先
/drop不再需要的文件(本技能); - 仍然超 / 话题已切换,再
/clear清历史([[agentsop-session-state-hygiene]])。 /drop保历史去文件;/clear保文件去历史;/reset两者都丢。
3. SOP 工作流
Phase 1 — 区分"要编辑"和"只要读懂"
任务进来,第一步不是 /add,而是分类。对每个相关文件问一句:"这一轮我会修改它的字节吗?"
会改它的字节 → 候选写集合(稍后 /add)
只需理解它的契约 → 只读:/read,或干脆只靠 repo-map 的签名
不确定改哪些 → 先不加任何文件,进 Phase 2 让 repo-map 帮你定位
经验法则:写集合目标 ≤ 5 个文件。超过,多半是任务没拆够。
Phase 2 — 不知道改哪个?让 repo-map 定位,而不是全加进来
> /ask which files implement <feature>?
< [模型基于只读 repo-map 回答候选文件]
模型命名出目标后,你再决定把哪些加进工作集(Op locate-then-add)。"找文件"和"改文件"永远两步走——这是 [[agentsop-repo-map]] 与本技能共享的设计哲学。
Phase 3 — 只 /add 你会编辑的,参考文件用 /read
/add src/auth.py tests/test_auth.py # 这两个会改 → 进写集合
/read src/config.py docs/auth.md # 只参考,不改 → 只读
铁律重申:少 /add,敢 /drop。"为了保险全加"恰恰是让模型改错文件的主因。
Phase 4 — 编辑过程中持续盯预算
/tokens # 看当前占用;接近 25k 是黄灯
| 信号 | 动作 |
|---|---|
/tokens 逼近 25k | /drop 已经改完、不再相关的文件 |
| repo-map 占比偏大 | 调小 --map-tokens(目标文件已定,地图可缩) |
| 模型反复改错文件 | /ls 检查工作集;/drop 多余的,/add 缺的 |
| 历史漂移(不是文件问题) | 转交 [[agentsop-session-state-hygiene]]:/clear |
Phase 5 — 一个文件改完就 /drop 它
工作集不是"会话期一直累积"的。某文件这一轮的修改告一段落、后续子任务不再碰它——立即 /drop。把腾出的预算还给下一批要改的文件。这是把工作集当滑动窗口用,而不是当垃圾堆。
Phase 6 — 任务太大撑不住时,拆,而不是塞
地图也缩了、能 /drop 的都 /drop 了,预算还是破 25k?这是任务太宽的信号,不是预算的问题:
1. 进子目录 + --subtree-only(缩小 repo-map 范围,见 [[agentsop-repo-map]] §3)
2. 拆任务:大需求拆成多个收敛子目标,每个子目标一个会话
3. 每个新会话只带它真正要改的那 ≤5 个文件
4. 操作模型
每条给 Trigger / Action / Output / Evidence。命令名以 Aider 为参考,行为框架无关。
Op 1 — classify(file) 区分"读"与"改"
- Trigger:任何相关文件进入视野。
- Action:问"这一轮会修改它的字节吗?"。会改 → 写集合候选;只读懂 → 只读层(
/read或仅 repo-map 签名)。 - Output:每个文件被标记为 EDIT / READ-ONLY / NAVIGATE-ONLY 三类之一。
- Evidence:LLM 只能编辑工作集里的文件 [aider.chat/docs/more/edit-formats.html];只读 vs 读写是 Aider 的安全边界。
Op 2 — locate-then-add(task) 先定位再加
- Trigger:写集合未定,不知道改哪个文件。
- Action:把 task + repo-map 喂给 LLM,让它只命名候选文件(不直接编辑);人/agent 再
/add命名出的目标。 - Output:≤5 个写集合文件 + ≤3 个只读参考。
- Evidence:repo-map 只读即可达 70.3% 文件命中 [aider.chat/2024/05/22/swe-bench-lite.html]—