企业官网建设流程全解析

Usage-based billing brief

【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills

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://link.gitcode.com/i/182082249c4113aaa4bfa947e41fa669) 中行为评测的输入素材——评测 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://link.gitcode.com/i/70889c7902d7b7d0466b54e1c39c75e3) 中"Surface assumptions immediately"（立即暴露假设）"Don't silently fill in ambiguous requirements"（不要静默补全模糊需求）的指令直接对应——评测要检验的就是 Agent 能否把"未知"转化为"向人提问"，而不是"编一个合理默认值继续干"。 ## 二、夹具如何接入 Tier-3 行为评测 ### 评测案例：prompt、fixture 与期望断言 [billing-brief.md](https://link.gitcode.com/i/01d885e66717c1bc28535c470eaf8ce0) 由 [evals/cases/spec-driven-development.json](https://link.gitcode.com/i/182082249c4113aaa4bfa947e41fa669) 中 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. 执行：headlessclaude以--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的每个元素都映射到规格模板的某个部分：

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

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

【免费下载链接】agent-skillsProduction-grade engineering skills for AI coding agents.项目地址: https://gitcode.com/GitHub_Trending/agentskill/agent-skills