ECC Agentic Engineering 实战指南：评估优先执行、15 分钟任务分解与成本感知模型路由

导读：本文基于 ECC 仓库中的 Agentic Engineering 技能定义（仓库内还提供日文版 docs/ja-JP/skills/agentic-engineering/SKILL.md），系统讲解在"AI 代理承担绝大多数实现工作、人类负责质量与风险控制"的工程工作流中，如何以评估为先、按 agent 规模分解任务、按复杂度路由模型层级、并以成本纪律约束每次迭代。读完本文，你将掌握一套可直接落地的 Agentic Engineering 操作框架：从定义完成标准、搭建评估-基线-实现-复评循环，到用 15 分钟单位规则切分任务、按 Haiku/Sonnet/Opus 分层路由、以及用会话策略与成本追踪控制整个开发过程。

一、什么是 Agentic Engineering：人与代理的分工边界

在传统工程流程中，人类工程师同时承担"实现"与"质量控制"两重角色。Agentic Engineering 则重新划分了职责：AI 代理负责执行大部分实现工作，而人类把精力集中在定义标准、设定约束与验收结果上。

该技能在 ECC 中定位为一种可复用的工程工作流模板，其核心假设是：当代理承担端到端（end to end）实现时，风险不再来自"代码会不会写"，而来自"代理是否理解了该做什么、如何度量做得对不对、以及在失控前如何拦截"。因此这套方法论的全部动作，都围绕把"人的判断"前移到执行之前、后置到验收之中。

技能定义的适用场景十分明确："Use this skill for engineering workflows where AI agents perform most implementation work and humans enforce quality and risk controls."（用于 AI 代理完成大部分实现工作、人类强制质量和风险控制的工程工作流。）它与 ECC 中的 model-route 命令、cost-report 命令、eval-harness 技能、agent-eval 技能 等组件协同，构成一整套"代理代工"的工程治理方案。

二、四大动作原则：执行前先定义可度量的一切

技能的运行建立在四条操作原则上，它们同时也是后续所有小节的总纲：

1. 执行前定义完成标准（Define completion criteria before execution）——先明确"什么叫做完"，再让代理动手，避免以过程替代结果。
2. 将工作分解为 agent 规模的单元（Decompose work into agent-sized units）——把大任务切小，让每个单元都能被单个代理独立消化。
3. 按任务复杂度路由模型层级（Route model tiers by task complexity）——不一律用最强模型，也不一律用最便宜模型，而是让任务难度决定模型档位。
4. 用评估与回归检查度量（Measure with evals and regression checks）——所有进展都通过可重复的度量来验证，而不是凭感觉判断。

这四条原则合在一起回答了 Agentic Engineering 的三个根本问题：做什么（完成标准）、谁来做（分解 + 路由）、做得怎么样（评估）。其中"评估优先"被技能单列为一等流程，见下一节。

三、评估优先循环（Eval-First Loop）：让度量先于实现

技能的第五条核心流程是"评估优先循环"。它要求任何实现工作都以"可运行、可对比的评估"为起点，形成四步闭环：

1. 定义能力评估与回归评估（Define capability eval and regression eval）。
2. 运行基线并捕获失败签名（Run baseline and capture failure signatures）——在改动任何代码之前，先跑一遍现有评估，记录当前失败的模式，作为后续对比的参照系。
3. 执行实现（Execute implementation）。
4. 重新运行评估并比较增量（Re-run evals and compare deltas）——用前后两次评估的差异（delta）判断实现是否真正推进了目标。

这个循环的关键思想是："失败签名"是有价值的资产。基线阶段的失败不是坏消息，而是定义了"当前系统能力的边界"；实现结束后的重跑，则能精确回答"这次改动到底新增了哪些能力、又是否破坏了原有能力"。

在 ECC 中，这一思想与 eval-harness 技能 的实现直接呼应。eval-harness 将评估分为两类：

• 能力评估（Capability Eval）：测试代理能否做到以前做不到的事，即能力边界的扩张。典型定义模板包含 Task、Success Criteria、Expected Output。
• 回归评估（Regression Eval）：确保改动不破坏既有功能，记录基线 SHA 或检查点名称，逐项标记 PASS/FAIL，并统计通过率变化（如 "X/Y passed (previously Y/Y)"）。

eval-harness 还给出了度量可靠性的两个指标：

• pass@k：k 次尝试中至少成功一次，其中 pass@1 是一次成功率，pass@3 是三次内成功，典型目标为 pass@3 > 90%；
• pass^k：k 次尝试全部成功，是更高标准的稳定性指标（如 pass^3 表示连续 3 次全过），用于关键路径。

评测器的选择也遵循"确定性优先"：能用代码断言（grep 模式、跑测试、跑构建）就不依赖模型评判，模型评判（LLM-as-judge）用于开放式输出打分，人工评判仅用于高风险或模糊场景。这与评估优先循环中"用可复现度量代替主观印象"的取向完全一致。

四、任务分解：15 分钟单位规则

代理规模的工作单元需要一个可操作的量化标准。技能给出的答案是 15 分钟单位规则（the 15-minute unit rule），即把工作切成"一个代理大约 15 分钟可完成"的单元，并满足三个约束：

• 每个单元应可独立验证（each unit should be independently verifiable）——单元完成与否不依赖其他单元的状态；
• 每个单元应只有一个主导风险（each unit should have a single dominant risk）——把风险拆开，避免一个单元同时赌多个不确定点；
• 每个单元应有明确的完成条件（each unit should expose a clear done condition）——"done"必须是可观察、可判断的，而不是模糊的"差不多"。

15 分钟的上限本质上是风险预算：单元越小，单次失败的爆炸半径越小，重试成本越低，也越容易被代理在单次上下文中完成。单元之间通过明确的完成条件衔接，就自然形成了可并行的流水线。当某个单元无法在预期时间内完成时，问题通常出在"单元过大"或"完成条件不清晰"，应回溯拆分，而不是让代理硬扛。

五、模型路由：让任务复杂度决定模型档位

不同的模型档位对应不同的能力与成本。技能给出了一张简洁的路由表：

模型档位	适用场景
Haiku	分类（classification）、样板代码转换（boilerplate transforms）、窄幅编辑（narrow edits）
Sonnet	实现与重构（implementation and refactors），即默认档位
Opus	架构设计、根因分析（root-cause analysis）、跨文件不变量维护（multi-file invariants）

路由的判断依据是任务复杂度：确定性高、风险低、机械性的改动交给最便宜的档位；常规实现与重构用默认档位；涉及架构判断、模糊需求与全局不变量的工作才动用最高档位。

ECC 将这套启发式规则固化成了可执行的 /model-route 命令：

/model-route [task-description] [--budget low|med|high]

该命令按"复杂度 + 预算"两个维度推荐模型档位，其内置启发式与技能文档完全对齐：

• haiku：确定性、低风险的机械性改动（deterministic, low-risk mechanical changes）；
• sonnet：实现与重构的默认选择；
• opus：架构、深度审查、需求模糊的任务（architecture, deep review, ambiguous requirements）。

命令要求输出五要素：推荐模型、置信度（confidence level）、推荐理由（why this model fits）、以及首选失败时的回退模型（fallback model if first attempt fails）。参数方面，[task-description] 是可选的自由文本描述，--budget low|med|high 用于显式约束预算档位。

注意路由与"升级"的纪律要配套：只有低档位模型因明确的推理缺口（clear reasoning gap）失败时，才升级到更高档位（详见第八节成本纪律）。换句话说，路由是主动规划，升级是被动补救，两者不能混淆——否则成本会随失败次数无限膨胀。

六、会话策略：在正确的时机开始、延续与紧凑化

代理工作流中，会话（session）的生命周期管理直接影响上下文质量与成本。技能给出三条会话策略：

• 紧密耦合的单元延续同一会话（Continue session for closely-coupled units）——单元之间共享大量上下文时，新开会话会丢失记忆、重复传递信息，延续会话更高效；
• 主要阶段转换后开启新会话（Start fresh session after major phase transitions）——从"设计"进入"实现"、从"实现"进入"验收"这类大跨度转换时，旧会话中过量的中间状态会成为噪音，新会话能获得干净的上下文窗口；
• 在里程碑完成后紧凑化，而非活跃调试中（Compact after milestone completion, not during active debugging）——紧凑化（compact）会压缩历史，若在调试正酣时进行，可能丢失关键的失败现场信息；等到里程碑收尾、上下文确实需要整理时再做。

这条策略与模型路由共享同一个底层考量：上下文是一种稀缺且昂贵的资源。会话的延续/重开/紧凑，本质上是在"信息连续性"与"上下文清洁度"之间做动态平衡。对代理而言，一个被无关历史污染的上下文窗口，其有效能力远低于一个干净的窗口。

七、AI 生成代码的审查焦点：把审查预算花在刀刃上

人类在 Agentic Engineering 中的核心职责是质量与风险控制，而代码审查是主要抓手。技能明确给出了 AI 生成代码的审查优先级清单，要求聚焦以下四类高风险点：

• 不变量与边缘情况（invariants and edge cases）——代理倾向于覆盖主路径，容易遗漏不变量被打破或边界输入；
• 错误边界（error boundaries）——错误处理是否到位，失败是否会静默吞掉或向调用方泄露错误状态；
• 安全与认证假设（security and auth assumptions）——代理对鉴权、权限、数据暴露范围的假设是否成立，是否存在默认信任；
• 隐藏耦合与上线风险（hidden coupling and rollout risk）——改动是否悄悄影响了未提及的模块，部署/回滚是否存在隐藏依赖。

同时技能给出一条反直觉但重要的建议：当自动化格式化/lint 已经强制风格时，不要浪费审查周期在纯风格分歧上（"Do not waste review cycles on style-only disagreements when automated format/lint already enforce style"）。审查是稀缺的人力资源，它的产出应该是"发现机器发现不了的问题"，而不是复述机器已经强制过的规则。把风格交给 lint、把逻辑交给审查，正是人与代理分工的又一次体现。

八、成本纪律：跟踪五个指标，仅在推理缺口时升级

Agentic Engineering 的可持续性取决于成本可控。技能要求按任务跟踪五个指标：

• 模型（model）——本次任务实际使用了哪个档位；
• token 估算值（token estimate）——输入输出的大致消耗；
• 重试次数（retries）——失败与重试的次数，反映路由判断的准确度；
• 墙钟时间（wall-clock time）——任务实际耗时，反映效率；
• 成功/失败（success/failure）——最终结果。

这五个指标共同构成每个任务的"成本档案"，既可用于事后复盘（哪类任务被过度路由到了高成本模型），也可用于实时决策（重试是否已超过阈值）。技能同时给出升级纪律：仅在低档位模型因明确的推理缺口失败时，才升级模型档位。如果失败原因是提示不清晰、任务拆分不当或外部依赖问题，升级模型只会放大成本而不会解决问题。

ECC 将这一纪律落地为可观测的工具链。/cost-report 命令 从 ECC 的 stop:cost-tracker 钩子写入的指标日志中生成成本报告：每次会话结束时，追踪器向 ~/.claude/metrics/costs.jsonl 追加一条 JSON 记录，行结构为 { timestamp, session_id, transcript_path, model, input_tokens, output_tokens, cache_write_tokens, cache_read_tokens, estimated_cost_usd }。

cost-report 的处理逻辑本身也体现了成本纪律的两处细节：

• 每行是该会话的累计快照（cumulative snapshot），因此报告按 session_id 取每个会话的最新一行再跨会话求和，若对所有行直接求和会重复计数；
• 报告依赖追踪器预先计算的 estimated_cost_usd，而不从原始 token 重新估算价格，避免口径漂移。

报告输出三部分：摘要（today / yesterday / total / session 数）、按模型分组的成本排行、最近 7 天的逐日成本；传入 csv 参数时则导出最近 100 行原始记录。成本指标与 agent-eval 技能 中"Pass rate、Cost、Time、Consistency"四维对比的度量口径一致——成本必须与成功率并列观察，一个 95% 通过率但成本高 10 倍的方案未必是正确选择。

九、与 ECC 其他能力的协同：把方法论接入现有工作流

Agentic Engineering 技能并非孤立存在，它在 ECC 中与多个技能/命令形成完整闭环：

本技能环节	协同组件	协同方式
评估优先循环	eval-harness 技能	提供能力/回归评估模板、pass@k/pass^k 指标、三类评测器（代码、模型、人工），并将评估产物存于 .claude/evals/ 作为一等工件
模型路由	/model-route 命令	将 Haiku/Sonnet/Opus 启发式固化为命令行推荐，输出置信度与回退模型
回归检查	benchmark 技能	提供 /benchmark baseline 与 /benchmark compare 前后对比，将基线存入 .ecc/benchmarks/ 并纳入 git 跟踪，用于度量性能类回归
成本纪律	/cost-report 命令	从 stop:cost-tracker 钩子的 JSONL 日志生成按日、按模型、按会话的成本报告
代理选择与回归	agent-eval 技能	用 YAML 任务定义 + git worktree 隔离做多代理横向对比，度量通过率、成本、耗时与一致性

从仓库结构看，技能体系与命令体系相互印证：/model-route 命令 与 /cost-report 命令位于 commands 目录，技能定义则集中维护于 skills 目录，两者共享同一套路由与成本语义。使用流程通常是：接到任务 → 用 15 分钟单位规则分解 → 用 /model-route 决定档位 → 按评估优先循环执行 → 用 /cost-report 复核成本、用 eval-harness/benchmark 验证增量 → 在里程碑处按会话策略整理上下文。

十、落地建议：从技能到团队工作流

将本技能落地到实际工程中，建议按以下顺序推进：

1. 建立评估资产：参考 eval-harness 技能 为当前项目定义 3～5 个代表性能力评估与回归评估，存入 .claude/evals/，并纳入版本控制。
2. 用 15 分钟单位拆任务：任何交给代理的工单都先拆到"独立可验证、单一主导风险、明确完成条件"的粒度，写清 done condition 再放行。
3. 固定路由策略：以 /model-route 为入口，明确 Haiku 处理机械改动、Sonnet 处理常规实现、Opus 处理架构与根因分析，并约定回退模型。
4. 执行评估优先循环：先跑基线捕获失败签名，实现后重跑评估比较 delta，用 pass@k / pass^3 把关能力新增与回归。
5. 绑定成本观测：启用 stop:cost-tracker 钩子，用 /cost-report 按任务核对模型、token、重试、耗时与成败，发现成本异常时先查路由与拆分，而非盲目升级模型。
6. 把人力审查留给高价值点：聚焦不变量、错误边界、安全假设与隐藏耦合，风格问题交给 lint。

这套流程的核心价值在于把"代理化开发"从不可控的试探，转变为可分解、可度量、可路由、可计价的工程过程——人类不再逐行写代码，但每一行由代理生成的代码都在评估、审查与成本三重约束之内。