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),返回内容可能演进(新增/改名、改签名、改取值范围、分页行为变化),且往往因账号、地域、时间、套餐而异。
适用范围包括(但不限于):
- 厂商/平台侧:额度、余额、剩余量、总限额、限流阈值、开通/激活状态、价格/计费。
- 接口/数据侧:第三方接口的返回结构、字段名、类型、状态码/错误码枚举、分页约定、响应样例。
- 配置/策略侧:远程配置、下发策略、权限点、功能开关、版本号、能力清单、枚举字典。
- 资源/限制侧:文件/内存/网络上限、超时值、批量上限、硬件能力。
核心规则
-
先实测,再写入
- 动态数据的正确值只能来自真实拉取/真实接口响应/真实页面抓取。先实际调用或抓取,确认拿到正确数据后,才允许体现在代码里。
- 禁止在代码里填猜测或脑补的静态默认值。猜错会写错,还会误导依赖它的逻辑(例如"以为有额度 → 放行生成 → 意外扣费";"写死字段路径 → 接口改结构 → 运行时报错")。
- 测试/临时用值一律标注
// TEMP: 实测后移除,联调阶段替换为实测逻辑,勿带入线上。
-
运行时优先,抓不到即「未知」
- 动态数据默认走运行时获取(接口/页面抓取/远端读取),代码只保留稳定的元数据(id、名称、能力、固定枚举、固定路径结构)。
- 运行时取不到时,显式标记为「未知/不可确认」(如把数值定义成可空
number | null),并走保守分支:UI 显示占位符、高风险操作拦截、引导用户刷新/重试。绝不借用假值冒充真实值,绝不因此放行可能造成损失的操作。
-
简洁,正确,可维护
- 不为"可能未来变化"预置猜测常量;不为猜测值堆冗余注释、重复代码或层层兼容补丁。
- 常量/目录/配置只声明稳定内容,动态值一律由实测层作为单一数据源写入,避免多处硬编码相同值、改一处漏一处。
- 每处改动先验证(构建/类型检查/真实运行)通过再保留;发现猜错立即移除,不留"先用着以后改"的过渡性代码。宁缺毋滥——能简洁就简洁。
常规流程
- 识别:判断数据是否「外部动态数据」(非代码内部生成、可能因外部而变化)→ 是则默认走实测,不落常量。
- 实测:调用真实接口/抓取真实页面/读真实远端,确定返回结构与正确值范围;记录来源(哪个接口/哪个字段/哪个页面)。
- 建模:结构体、字段、枚举按实测结果定义,字段命名与来源一一对应,来源留痕。
- 未知处理:定义「未知」语义(如
remaining === null/{ available: false }),UI 与业务都走保守分支,不崩溃、不误导。 - 验证:构建 + 类型检查 + 至少一次真实运行确认无回归。
- 清理:移除测试期临时值、猜测常量与冗余注释,交付最小正确实现。
反例 → 正例
场景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
postgrest-egress-optimization
降低 Supabase/PostgREST 出口流量(Egress)与请求量的排查落地方法论。用户反馈流量超额、请求数过高、查询慢、或要做数据库访问优化时调用。
★ 53
karpathy-guidelines
Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
★ 53
skill
暂无简介
★ 53