AGENT SKILL

measure-before-hardcode

业务开发中遇到任何由外部系统/第三方决定、会随时间变化的数据(状态、数值、配置、接口返回结构、权限策略、资源限制、价格、版本等)时,必须先实测拿到正确值再写入,禁止凭猜写死静态默认值;并保持代码简洁可维护。接入第三方、处理外部数据、或要把某个值写进代码前启动。

License 许可
MIT
最近更新
2026-09-14
Stars
★ 53
Forks
8

01 前言 Front Matter

name
measure-before-hardcode
description
业务开发中遇到任何由外部系统/第三方决定、会随时间变化的数据(状态、数值、配置、接口返回结构、权限策略、资源限制、价格、版本等)时,必须先实测拿到正确值再写入,禁止凭猜写死静态默认值;并保持代码简洁可维护。接入第三方、处理外部数据、或要把某个值写进代码前启动。

03 SKILL.md 正文

Measure Before Hardcode(实测再写,不靠猜)

处理任何由外部系统/第三方依赖决定、且会随时间、环境或账号变化的动态数据时,遵循本准则。这类数据无法靠推断得出,只能实测。

这类数据的共同特征:来源不归你控制(第三方接口、平台页面、外部服务、远端 API),返回内容可能演进(新增/改名、改签名、改取值范围、分页行为变化),且往往因账号、地域、时间、套餐而异。

适用范围包括(但不限于):

  • 厂商/平台侧:额度、余额、剩余量、总限额、限流阈值、开通/激活状态、价格/计费。
  • 接口/数据侧:第三方接口的返回结构、字段名、类型、状态码/错误码枚举、分页约定、响应样例。
  • 配置/策略侧:远程配置、下发策略、权限点、功能开关、版本号、能力清单、枚举字典。
  • 资源/限制侧:文件/内存/网络上限、超时值、批量上限、硬件能力。

核心规则

  1. 先实测,再写入

    • 动态数据的正确值只能来自真实拉取/真实接口响应/真实页面抓取。先实际调用或抓取,确认拿到正确数据后,才允许体现在代码里。
    • 禁止在代码里填猜测或脑补的静态默认值。猜错会写错,还会误导依赖它的逻辑(例如"以为有额度 → 放行生成 → 意外扣费";"写死字段路径 → 接口改结构 → 运行时报错")。
    • 测试/临时用值一律标注 // TEMP: 实测后移除,联调阶段替换为实测逻辑,勿带入线上。
  2. 运行时优先,抓不到即「未知」

    • 动态数据默认走运行时获取(接口/页面抓取/远端读取),代码只保留稳定的元数据(id、名称、能力、固定枚举、固定路径结构)。
    • 运行时取不到时,显式标记为「未知/不可确认」(如把数值定义成可空 number | null),并走保守分支:UI 显示占位符、高风险操作拦截、引导用户刷新/重试。绝不借用假值冒充真实值,绝不因此放行可能造成损失的操作。
  3. 简洁,正确,可维护

    • 不为"可能未来变化"预置猜测常量;不为猜测值堆冗余注释、重复代码或层层兼容补丁。
    • 常量/目录/配置只声明稳定内容,动态值一律由实测层作为单一数据源写入,避免多处硬编码相同值、改一处漏一处。
    • 每处改动先验证(构建/类型检查/真实运行)通过再保留;发现猜错立即移除,不留"先用着以后改"的过渡性代码。宁缺毋滥——能简洁就简洁。

常规流程

  1. 识别:判断数据是否「外部动态数据」(非代码内部生成、可能因外部而变化)→ 是则默认走实测,不落常量。
  2. 实测:调用真实接口/抓取真实页面/读真实远端,确定返回结构与正确值范围;记录来源(哪个接口/哪个字段/哪个页面)。
  3. 建模:结构体、字段、枚举按实测结果定义,字段命名与来源一一对应,来源留痕。
  4. 未知处理:定义「未知」语义(如 remaining === null / { available: false }),UI 与业务都走保守分支,不崩溃、不误导。
  5. 验证:构建 + 类型检查 + 至少一次真实运行确认无回归。
  6. 清理:移除测试期临时值、猜测常量与冗余注释,交付最小正确实现。

反例 → 正例

场景1:厂商额度(已落地)

  • ❌ 在适配器写死 freeQuota: { remaining: 272120, total: 2000000 }(历史旧值)。平台一改额度就失真;假余额放行生成 → 额度耗尽时错误扣费。
  • ✅ 目录只声明元数据 { id, name, modes },额度由实测接口(如 ListModelTokenLimit)抓取后写入;抓不到则 remaining 为「未知」,前端显示 —、生成前保守拦截。

场景2:第三方接口返回结构

  • ❌ 假设接口固定:const d = JSON.parse(resp).result.data[0].name。接口新增嵌套层级/字段改名后直接报错。
  • ✅ 实测结构后防御式解析:const data = resp?.result?.data ?? [],再按实测字段读取,字段缺失不崩。

场景3:远端状态/枚举字典

  • ❌ 写死 if (status === 1) 已开通。平台新增状态码 2 后逻辑失效,用户数据被误判。
  • ✅ 动态映射:const enabledSet = await fetchEnabledList(); if (enabledSet.has(status)) ...,枚举从远端正源拉取,新增值不破坏判断。

场景4:配置下发 / 资源限制

  • ❌ 写死超时 timeout = 30000 或批量上限 maxBatch = 50("应该够用")。实际限制变化后超时/超限。
  • ✅ 从远端配置接口实测读取(带默认兜底语义为「未知→保守」),或按实测到的真实上限适配;实测值变化时自动跟随。

适用触发词

接入第三方系统/新厂商/新接口、处理外部接口返回、要把某个外部值(数值/状态/URL/字段名/枚举/配置)写进代码、调试"数据不对/显示假值/接口报错/间歇性异常"、涉及扣费放行/状态判定/权限校验时,启动本 skill。

04 同仓库更多 Skills