/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]—