ECC 性能规则详解：模型分级选择、上下文窗口管理、扩展思考预算与构建排障流程

本文以 ECC 仓库中始终生效（alwaysApply: true）的 Cursor 规则文件 .cursor/rules/common-performance.md 为主体，完整展开其四大主题：任务-模型匹配策略、上下文窗口预算管理、扩展思考（Extended Thinking）与 Plan Mode 的组合用法、构建失败排障流程，并结合 rules/common/performance.md、docs/token-optimization.md 以及 scripts/hooks/ecc-context-monitor.js 等仓库内实现，说明每条性能规则的底层依据与可落地的配置方法。读完本文，你能为 Claude Code、Cursor 等 Agent 工作流建立一套“成本可控、上下文不耗尽、构建快速转绿”的标准化性能实践。

规则文件的定位：一份 alwaysApply 的性能守则

该规则文件的 frontmatter 声明了它的作用方式：

---
description: "Performance: model selection, context management, build troubleshooting"
alwaysApply: true
---

alwaysApply: true 意味着它不依赖关键词触发，而是作为通用规则注入每次会话的上下文，约束所有后续操作：选什么模型、上下文用到什么程度该停、何时开启深度推理、构建挂了走什么流程。仓库中还存在一份内容同源的顶层规则 rules/common/performance.md，二者差异仅在于 .cursor/ 版本标注了具体模型代次（Haiku 4.5 / Sonnet 5 / Opus 5），可以推断前者是由后者同步生成的 Cursor 安装目标产物。无论使用哪一份，下述内容完全一致。

一、模型选择策略：按任务复杂度分层调度

文档给出的三级模型分工如下（以 .cursor/ 版本标注的代次为准）：

Haiku 4.5（约 Sonnet 90% 的能力，3 倍成本节省）：

• 频繁调用的小型 Agent
• 结对编程与代码生成
• 多 Agent 系统中的 Worker Agent

Sonnet 5（编码能力最强的主力模型）：

• 主要开发工作
• 编排多 Agent 工作流
• 复杂编码任务

Opus 5（推理深度最高）：

• 复杂架构决策
• 需要最大推理深度的场景
• 研究与分析类任务

这条“分级路由”在 docs/token-optimization.md 中被进一步量化为会话级操作：

/model sonnet     # 大多数工作的默认值
/model opus       # 复杂推理
/model haiku      # 快速查询

配套的推荐配置（写入 ~/.claude/settings.json）：

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

其中 CLAUDE_CODE_SUBAGENT_MODEL 指定子 Agent（Task 工具）使用的模型。按 token-optimization 文档的说明，子 Agent 承担的读文件、探索、跑测试等工作用 Haiku 即可完成，成本约低 80%——这正是上面“Haiku 负责多 Agent 系统中的 Worker”这条规则在配置层面的落点：主会话用 Sonnet 编排，子 Agent 用 Haiku 干活。

二、上下文窗口管理：避开最后 20%

文档的上下文管理规则非常明确——在上下文窗口的最后 20% 区间内，避免执行以下工作：

• 大规模重构（large-scale refactoring）
• 跨多个文件的功能实现
• 复杂交互关系的调试

而以下任务对上下文余量不敏感，可以在窗口接近满载时继续做：

• 单文件编辑
• 独立的工具函数创建
• 文档更新
• 简单 bug 修复

这条规则背后的逻辑是：长上下文尾部阶段，模型对早期信息的回忆质量会下降，而重构、跨文件改动恰好依赖对全局的准确回忆，因此需要在窗口还有 20% 余量时就完成收尾或主动压缩。

仓库里有一个与该规则强相关的实现证据：ECC 的 PostToolUse hook scripts/hooks/ecc-context-monitor.js 会持续监测上下文占用并在阈值处向 Agent 注入警告。其源码中的阈值定义（scripts/hooks/ecc-context-monitor.js#L18-L30）：

const CONTEXT_WARNING_PCT = 35;   // 剩余 35% 时警告
const CONTEXT_CRITICAL_PCT = 25;  // 剩余 25% 时进入严重状态
const COST_NOTICE_USD = 5;
const COST_WARNING_USD = 10;
const COST_CRITICAL_USD = 50;
const FILES_WARNING_COUNT = 20;   // 单任务触碰文件数警告
const LOOP_THRESHOLD = 5;         // 最近 5 次工具调用完全一致才判定为死循环

也就是说，ECC 在剩余 35% 就提前告警、25% 时升级为严重状态，恰好落在规则文档所说的“最后 20% 危险区”之外——hook 的阈值设计就是为了让 Agent 在进入危险区之前完成压缩或收尾。该 hook 的行为有对应测试 tests/hooks/ecc-context-monitor.test.js 覆盖。

配套的上下文操作习惯（来自 docs/token-optimization.md）：

命令	使用时机
/clear	无关任务之间。过期上下文会在后续每条消息上浪费 token
/compact	逻辑断点处：规划完成后、调试结束后、切换关注点前
/cost	查看当前会话的 token 花费

仓库中的 skills/strategic-compact/ skill 提供了“主动压缩”策略：在探索结束、里程碑完成、调试结束、重大上下文切换前执行 /compact，而不是依赖可能在中途触发的自动压缩；同时明确不要在相关改动的实现中途、正在调试活跃问题时、多文件重构进行中执行压缩。此外，用子 Agent 做探索（子 Agent 读 20 个文件只返回摘要）也是保护主会话上下文的主要手段。

三、Extended Thinking + Plan Mode：深度推理的开关与预算

文档指出，扩展思考默认开启，最多预留 31,999 个 token 用于内部推理。四个控制手段完整继承如下：

• 切换：Option+T（macOS）/ Alt+T（Windows/Linux）
• 配置：在 ~/.claude/settings.json 中设置 alwaysThinkingEnabled
• 预算上限：export MAX_THINKING_TOKENS=10000（bash）或 $env:MAX_THINKING_TOKENS = "10000"（PowerShell）
• 详细输出：Ctrl+O 查看思考过程

对需要深度推理的复杂任务，文档给出的完整工作流是四步：

1. 确认扩展思考已开启（默认开启）
2. 启用 Plan Mode 采用结构化推进
3. 进行多轮批判（critique rounds）以完成彻底分析
4. 使用拆分角色的子 Agent 获得多元视角

从仓库其他文档交叉印证，MAX_THINKING_TOKENS 的默认值就是 31,999，将其降到 10,000 可以削减约 70% 的每请求隐藏推理成本，设为 0 则可在琐碎任务中完全禁用（见 docs/token-optimization.md#L27-L31 的设置效果表）。因此一个实用的分档策略是：日常任务保持 MAX_THINKING_TOKENS=10000 甚至更低，架构级难题临时调高，而不是全局放开 31,999 的默认预算。

四、构建排障：build-error-resolver 的四步法

文档对构建失败的处置只有四步，但每一步在仓库中都有对应实现：

1. 使用 build-error-resolver agent
2. 分析错误信息
3. 增量修复（fix incrementally）
4. 每次修复后验证

对应的 Agent 定义在 agents/build-error-resolver.md，其关键设计值得展开：

诊断命令（该 agent 的标准工具集）：

npx tsc --noEmit --pretty
npx tsc --noEmit --pretty --incremental false   # 显示全部错误
npm run build
npx eslint . --ext .ts,.tsx,.js,.jsx

“最小 diff”纪律——这是该 agent 与通用重构 agent 的本质区别：只做类型标注、空值检查、import 修复、缺失依赖补齐这类最小改动；明确禁止重构无关代码、改变架构、顺手改名、添加功能或做性能/风格优化。其成功标准包括：npx tsc --noEmit 退出码为 0、npm run build 成功、未引入新错误、改动行数少于受影响文件的 5%、既有测试仍然通过。

优先级分级：

级别	症状	动作
CRITICAL	构建完全损坏、dev server 起不来	立即修复
HIGH	单文件失败、新代码类型错误	尽快修复
MEDIUM	Linter 警告、弃用 API	见缝插针修复

边界规则同样清晰：需要重构时转 refactor-cleaner，需要架构变更转 architect，需要新功能转 planner，测试失败转 tdd-guide，安全问题转 security-reviewer——构建排障 agent 只负责“让构建转绿”，不承担其他职责。

五、成本监控开关：与性能规则配套的 hook 配置

性能规则中关于“成本控制”的部分，在 hook 侧还有一个可观察点。ecc-context-monitor.js 中的成本警告受环境变量控制（scripts/hooks/ecc-context-monitor.js#L42-L44）：

function costWarningsEnabled(env = process.env) {
  return isEnabledEnv(env.ECC_CONTEXT_MONITOR_COST_WARNINGS, true);
}

默认开启；对订阅制用户，若本地 hook 遥测给出的 API 计费估算与实际账单不符，可只关闭面向 Agent 的成本警告而保留上下文耗尽、范围蔓延（scope creep）、死循环等警告：

export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')

这不会禁用 /cost 或成本遥测文件，仅影响警告文案——即“性能监控”与“计费估算”在实现上是解耦的两条通道。

小结：四条规则构成的性能闭环

把 .cursor/rules/common-performance.md 的四个章节串起来，ECC 的性能方法论是一个闭环：

1. 模型分层（Haiku 4.5 / Sonnet 5 / Opus 5）解决“用多大的模型”；
2. 上下文窗口管理（避开最后 20%、/clear、/compact、strategic-compact）解决“在什么状态干活”；
3. Extended Thinking + Plan Mode（MAX_THINKING_TOKENS、alwaysThinkingEnabled、Option/Alt+T、Ctrl+O）解决“推理预算给多少”；
4. build-error-resolver 四步法解决“出错后如何低成本收敛”。

这四条规则通过 alwaysApply: true 注入每次会话，并由 scripts/hooks/ecc-context-monitor.js 在运行时用 35%/25% 上下文阈值、$5/$10/$50 成本阈值和死循环检测提供硬信号，形成“规则软约束 + hook 硬告警”的双层性能治理。适用前提需要说明：模型代次与 MAX_THINKING_TOKENS、alwaysThinkingEnabled 等配置项针对的是 Claude Code 系 Agent 环境；在不同 harness（Codex、Cursor 等）下，快捷键与配置文件位置需以各平台实际文档为准，而规则中“分级选模、避开尾部上下文、最小 diff 修构建”的策略本身是通用的。