Usage-based billing brief

The product currently charges one flat monthly price. Leadership wants usage- based billing next quarter, but "usage" has not been defined. Candidate meters include API requests, processed records, and successful jobs.

Known constraints:

• Existing customers need a migration path.
• Billing events must be auditable and idempotent.
• Late-arriving events occur for up to seven days.
• Finance requires invoice reconciliation.

Unknowns include pricing tiers, free allowances, meter ownership, correction rules, customer-facing usage visibility, and regional tax behavior. Produce a spec and surface these decisions; do not implement them by assumption.

它不是产品文档，而是 [evals/cases/spec-driven-development.json](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/evals/cases/spec-driven-development.json?utm_source=gitcode_repo_files) 中行为评测的输入素材——评测 runner 会把它物化进一个一次性工作区，交给被测 Agent 处理。它的短小恰恰是设计目的，整个文档由三个要素构成：

### 1. 未定义的"usage"与三个候选计量口径

简报明确指出产品当前是"固定月费"，管理层要求下季度转向按量计费，但 `"usage" has not been defined`，并给出三个候选计量口径（meter）：**API 请求数、处理记录数、成功任务数**。这模拟了真实需求中最典型的危险状态：方向明确（要按量计费）、核心定义缺失（计量什么）。一个遵循 spec-driven-development 技能的 Agent 应当把它写进规格的 Open Questions，而不是自行挑选"successful jobs"就开始设计数据模型。

### 2. 四条已知约束

- **存量客户需要迁移路径**（Existing customers need a migration path）——规格必须回答老客户如何从固定月费过渡；
- **计费事件必须可审计且幂等**（auditable and idempotent）——这是事件流设计的硬性质：同一事件重放不能重复计费；
- **迟到事件最长可达 7 天**（Late-arriving events occur for up to seven days）——这一条直接决定窗口/结算周期的设计，规格必须说明 7 天内的迟到事件如何并入已生成的账期；
- **财务要求可对账的发票**（invoice reconciliation）——事件计量与最终发票之间必须存在可追溯链路。

这四条约束是"可验证的规格要点"：后续无论规格怎么写，这四条都必须被覆盖，评测的 `expectations[]` 因此可以客观判断 Agent 是否遗漏。

### 3. 六个未知决策项与一句明确的禁令

Unknowns 列出了 **定价层级、免费额度、计量口径归属、纠错规则、客户侧用量可见性、区域税务行为** 六项，并以最后一句收尾：

> Produce a spec and surface these decisions; do not implement them by assumption.
> （产出一份规格，并把这些决策显式暴露出来；不要靠假设去实现它们。）

这句是整份夹具的灵魂，它与 [skills/spec-driven-development/SKILL.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/skills/spec-driven-development/SKILL.md?utm_source=gitcode_repo_files) 中"Surface assumptions immediately"（立即暴露假设）"Don't silently fill in ambiguous requirements"（不要静默补全模糊需求）的指令直接对应——评测要检验的就是 Agent 能否把"未知"转化为"向人提问"，而不是"编一个合理默认值继续干"。

## 二、夹具如何接入 Tier-3 行为评测

### 评测案例：prompt、fixture 与期望断言

[billing-brief.md](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/evals/fixtures/spec-driven-development/billing-brief.md?utm_source=gitcode_repo_files) 由 [evals/cases/spec-driven-development.json](https://gitcode.com/GitHub_Trending/agentskill/agent-skills/blob/020ec10a788f5703108d093a4bd3d9a7c3847d36/evals/cases/spec-driven-development.json?utm_source=gitcode_repo_files) 中 id 为 1 的评测消费（该文件第 41–55 行）：

```json
{
  "id": 1,
  "prompt": "We want usage-based billing. Produce the spec before any implementation.",
  "expected_output": "A SPEC.md covering objectives, behavior, data model, testing strategy, and explicit boundaries",
  "files": ["spec-driven-development"],
  "expectations": [
    "The spec includes explicit boundaries and non-goals",
    "Ambiguities are surfaced as questions rather than silently resolved",
    "A testing strategy is part of the spec",
    "No implementation code is written"
  ]
}

几个字段的对应关系值得注意：

• files: ["spec-driven-development"] 指向 evals/fixtures/spec-driven-development/ 目录，即 billing-brief.md 所在目录。执行型评测（kind 默认 execution）要求非空 files[]，路径相对于 evals/fixtures/；
• 四条 expectations[] 是可判定陈述（verifiable statements），逐条对应夹具的设计：第一条对应约束清单要落成 boundaries/non-goals；第二条对应 Unknowns 与那句"不要靠假设实现"的禁令；第三条要求测试策略写进规格（呼应简报中可审计、幂等等性质可被测试验证）；第四条"No implementation code is written"直接检验 do not implement 的指令是否被遵守。

runner 的执行链路

评测的运行机制见 evals/README.md 与 scripts/run-evals.js。--behavioral 模式下：

1. 物化夹具：files[] 指向的真实项目输入从 evals/fixtures/ 拷贝进一次性 git 仓库并作为基线提交（fixture 路径解析见 resolveFixturePath，scripts/run-evals.js，会拒绝绝对路径与逃逸出工作区的路径）；
2. 执行：headless claude 以 --permission-mode acceptEdits 加预批准工具列表（Read,Glob,Grep,Edit,Write,Bash,WebFetch,WebSearch，见 scripts/run-evals.js）运行，执行器超时常量为 15 分钟（scripts/run-evals.js）；
3. 评分：完整 --output-format stream-json --verbose 执行轨迹（含工具调用）被作为不可信数据加围栏后，通过 stdin 喂给评分器（轨迹可能达数 MB，argv 会撞 OS 参数长度上限）；评分器输出必须校验为 JSON 后才写入 evals/results/（已 gitignore）。

对 billing-brief.md 这个案例，评分器会检查：规格是否把"usage 未定义"列成待决问题、七条类约束（迁移、幂等、迟到 7 天、对账）是否进入规格、Agent 是否真的没写实现代码。

# Tier 3 — behavioral, runs each eval through headless claude, then grades it
node scripts/run-evals.js --behavioral spec-driven-development            # 消耗 tokens
node scripts/run-evals.js --behavioral spec-driven-development --dry-run  # 只打印计划

三、与 Tier-2 路由评测的衔接：billing 相关 prompt 的触发验证

同一份案例文件还定义了触发（trigger）评测，其中与 billing 主题强相关的正例 prompt 包括：

{ "prompt": "Write a spec for the new billing feature before we write any code", "top_k": 3 }

负例则声明了 owner，把"不该被本技能接走"变成成对路由测试，例如"Break the approved spec into ordered implementation tasks" 的 owner 是 planning-and-task-breakdown（owner 必须在排序中压过本技能，否则算错误——见 scripts/run-evals.js 的实现）。Tier-2 用词干化 TF-IDF 对全部 25 个技能的 description 做词法近似评分，描述两两余弦相似度 ≥75% 报错、≥50% 警告（scripts/run-evals.js）。在当前仓库上实际运行 node scripts/run-evals.js 的结果为：

Running skill evals across 25 skills, 25 case files
140 checks passed — 0 error(s), 0 warning(s)
trigger rank-1 rate: 86% (76/88 positive prompts rank their skill first)
PASSED

也就是说，"billing spec"这类真实用户说法确实能把 spec-driven-development 排进 top-k，且整个描述目录没有近似碰撞。

四、被评测的技能本体：规格文档必须覆盖的六要素

夹具检验的技能流程定义在 skills/spec-driven-development/SKILL.md。billing-brief.md 的每个元素都映射到规格模板的某个部分：

简报元素	规格落点
"usage 未定义" + 三个候选 meter	Open Questions——作为待人类决策的问题列出
四条已知约束（迁移/幂等/迟到 7 天/对账）	Success Criteria 与 Boundaries——可测试的完成条件
六项 Unknowns	Open Questions——"Produce a spec and surface these decisions" 的直接执行
"do not implement by assumption"	Phase 4 之前的门禁——规格未获批不进入实现

该技能的核心是四阶段门禁工作流：

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews