用途:footgun-finder 是一个只读审查视角,寻找「易被合理误用却让人以为做对了」的代码与接口形态。判定式:可用诱因 + 合理的用户/调用方认知 + 意外或危险后果 = 疑似 footgun。若不存在可信的行为者与动作,即使代码怪异也归类为 not_a_footgun。它不实施修复、不解决评论、不建工单、不认证结项,只产出排序后的 footgun 台账、缓解候选与移交路由。
主要能力:类型学包括 unsafe_default、misleading_name_or_shape、silent_degradation、ambiguous_authority、irreversible_or_expensive_easy_path、copy_paste_trap、state_or_lifecycle_trap、validation_gap、observability_gap、concurrency_or_idempotency_trap、security_or_privacy_trap、compatibility_trap。严重度按预期危害与可能性排序:P0 可能数据丢失、安全隐私暴露、不可逆破坏、生产中断或策略绕过;P1 高概率误用导致错误行为、虚假证明、持久状态损坏;P2 有界影响或昂贵调试;P3 轻微锐边与低概率陷阱。
使用方式:流程为确定审查面(制品状态、接口面、主要用户/调用方)并先预测正常、失败与生命周期行为,再扫描诱因陷阱,要求具体误用轨迹:行为者 → 动作 → 合理认知 → 隐藏事实 → 后果 → 当前表面为何允许。区分危害类与补救类,选择最小真实缓解类,如 make_safe_default、require_explicit_opt_in、rename_or_retype、fail_closed_or_block、surface_degraded_state、validate_at_boundary、add_dry_run_or_preview 等。默认输出紧凑审查,按需输出完整审查。
适用场景:接口、CLI、配置、示例、默认值、标志、回退、重试、清理、权限、持久化或状态机易被用错;审查要求寻找尖锐边缘、危险默认、未来误用、隐藏耦合;变更技术上正确但可能造成误导性诱因;成功路径与降级路径太易混淆;测试只证明当前行为却不防误用。
限制:不用于通用风格审查、宏观架构文章、纯性能工作或无合理误用面的普通 bug。可与 $invariant-ace、$complexity-mitigator、$review-fold 配合,但不能替代;若根因是有主的不变量,移交 $invariant-ace;若是局部理解成本,移交 $complexity-mitigator;若是审查压力分类,移交 $review-fold。不得实施、不得把每个 bug 都膨胀为 footgun、不得无轨迹使用 unsafe 等宽泛词。