SuperAPI AI 工具集

signal-first-plan

编程与开发

查看项目

更新于 10-26 17:48

技能介绍

Signal-first-plan 是一个面向开发前规划的技能,核心主张是:在构建功能之前,先决定如何看出功能正常工作、以及如何看出它出故障。功能往往在其“出口”处出问题,也就是功能的数据或行为离开进程的位置。该技能要求列出每个出口、为每个出口设定一个信号,并在编写功能前让每个信号可检查。改动较小可能只有一个出口,此时计划只有一行。

用途与主要流程

第一步:列出出口。出口指功能的数据或行为离开进程的任何位置,包括响应(渲染页面、页面数据、API 响应体、重定向、状态码)、消息(邮件、webhook、通知、订阅源、站点地图、徽章、嵌入)、外部调用(HTTP、DNS、队列、第三方 API)、写入(数据库行、文件、缓存、日志)。应从数据出发追踪出口,而非从计划修改的文件出发:从功能读取或更改的每个表、列、标志或配置值开始,沿读取它的每个查询、控制器、路由和任务追踪到数据离开进程之处。未计划触碰的读取者仍是出口。完成标准是:被触碰数据的所有读取者都已列入出口,或被标记为内部并注明理由。

第二步:为每个出口设定一个信号。信号是一个在功能损坏时会变化的数字,例如每请求 DNS 查询次数、每任务写入行数、每次结账支付 API 调用次数、每次注册发送邮件数。需为功能区分的每种情况写出预期值:每类查看者、每类输入、每个配置值。对响应出口,应对客户端收到的整个响应体(序列化页面数据或 JSON)计数,而非仅对预期承载数据的字段计数。正常与损坏版本共享的数字是噪声,需另选。p99、错误率等聚合指标较弱,因为多种原因都会使其变化,优先选择与单一出口绑定的计数。若项目根目录存在 .claude/debug-layers.md,应读取其中以往缺陷所需的信号,凡触及本功能出口的信号都成为第三步的检查项。完成标准是:每个出口都有一个信号,且每种情况都有预期值。

第三步:让每个信号可检查。优先选择能像客户端一样到达出口并断言信号的测试,一个测试可遍历多个出口和情况。当只有生产环境能显示信号(延迟、真实规模下的调用次数)时,在现有日志或度量位置发出该信号,以便后续调试会话在第一层找到它。发出信号时应带上便于日后提问而无需重新部署的字段:请求或任务 ID、输入类别、出口、计数;仅有聚合值只能回答计划内的问题。在主分支上运行检查:新行为的检查在此失败,必须保留行为的检查在此通过;若保留检查在主分支失败,说明缺陷已存在,应在构建之上先向用户报告。完成标准是:每个信号都有测试或已发出的指标,并知道哪些检查在主分支通过。随后以表格形式向用户展示计划:出口、信号、各情况预期值、检查(测试名或指标)、主分支结果,然后开始构建。

第四步:合并前对比。构建完成后,在主分支和功能分支上运行所有检查,列出发生变化的每个信号。每个变化都必须是计划预期的;其他任何变化须在合并前修复。对于只有生产或预生产环境能显示的信号,当发布提供金丝雀群体与对照群体时,应在同一时间按群体对比两者;回退方案是对单个群体与其上次成功运行做前后对比,但需在 PR 中说明时段与负载会影响结果。同时应将对照组与其自身基线比较,因为不良金丝雀可能影响作为对照的群体。不能只依赖绝对阈值或仅比较通过/失败。这适用于计划中的每个信号,包括来自 .claude/debug-layers.md 的信号。提交前列出差异中的每个文件:生成的文件(如测试截图和附件)除非计划明确列出,否则不应包含。在 PR 中提供出口表和对比结果。

适用场景与限制

该技能适用于在开发新功能前建立可观测性与验证计划的场景,尤其适合关注数据泄漏、意外出口行为、回归检测的团队。资料未提供具体收费、平台支持范围、安装命令或代码示例,这些信息暂未提供。