fail-fast

快速失败

使用此技能，通过查找并移除隐藏的回退行为，让代码库更具确定性。此类行为本应是明确的契约、验证错误、迁移或测试夹具。

请在开头说明你正在使用 fail-fast 技能。

核心规则

优先选择一条规范路径和一种明确的失败模式。

只有当回退是真实的产品需求、已记录的迁移窗口或有意设置的本地测试夹具时，才允许使用。其他情况都应改为验证错误、必填输入、显式分支、删除兼容层或类型化配置契约。

工作流

1. 确定目标代码库及其包管理器。

2. 编辑前运行扫描器（路径相对于此技能所在目录）：

   python3 scripts/scan-fallbacks.py /path/to/repo
   

   有用的标志：--json（为大型审查或后续工具提供机器可读的输出）、--include-tests 和 --include-docs（扫描默认跳过的文件）、--fail-on medium|high（作为 CI 门禁，退出时返回非零状态）。

   python3 scripts/scan-fallbacks.py /path/to/repo --json
   

3. 如果发现涉及环境变量、旧版兼容性、宽泛的 catch 块或分阶段迁移，请阅读 references/remediation.md。

4. 对每项发现进行分类：

   • remove：无用的兼容逻辑、旧版别名、重复的选项名称、没有实际调用方的回退分支。
   • require：缺少配置、依赖不存在、用户输入无效，或应加入环境变量架构的环境变量。
   • validate：边界输入必须接受未知数据，但应清晰拒绝无效状态。
   • keep：已记录的产品行为、真实的外部 API 兼容性，或有负责人和移除日期的临时迁移。

5. 精简地编辑。移除回退状态，并更新调用点和测试，使其使用规范路径。

6. 添加或更新测试，证明依赖、输入、配置或架构中声明的环境变量缺失时，代码会以确定的方式失败。

7. 再次运行扫描器，以及代码库相关的测试、类型检查、lint 或构建。

8. 明确报告剩余的回退行为。不要让它们悄无声息地遗留。

环境变量

环境变量是配置契约，不是可选建议。

在使用经过验证的环境变量架构的项目中，必填值应在应用代码使用前通过验证，缺失时立即失败。从项目的环境变量模块导入类型化的值。如果架构中缺少必填项，应在该处声明并验证，而不是添加应用层回退。

使用项目现有的环境变量验证和构建检查。检查其脚本和验证器文档，确认实际命令；不要仅为遵循此技能而安装新包。

只有在环境变量架构模块、生成的环境变量接线代码、NODE_ENV 和 CI 等范围有限的系统键，或有明确文档说明的迁移逃生口中，才接受直接读取 process.env。

移除如下模式：

const apiKey = process.env.OPENAI_API_KEY || "dev-key";
const databaseUrl = process.env.DATABASE_URL ?? "postgres://localhost";

替换为类型化的环境变量访问：

const apiKey = env.OPENAI_API_KEY;

如果不存在环境变量架构，请按照项目现有约定，在配置边界显式验证必填值。

错误处理

快速失败不意味着含糊地崩溃，而是要在边界处以有用、类型化或带上下文的错误失败。

优先采用：

• 对外部输入进行架构验证，
• 对不可能出现的内部状态显式抛出错误，
• 使用范围有限的 catch 块，并附带上下文重新抛出错误，
• 启动前预检必需的配置和服务。

避免：

• 空的 catch 块，
• 返回虚假成功结果的 catch 块，
• 会悄然降低必需功能的可选依赖导入，
• 让测试通过、却导致生产行为出错的回退数据。

兼容性

必须有意识地处理向后兼容性。

区分永久支持的契约与临时迁移。保留公共 API、协议或受支持的产品行为所要求的兼容性；这类兼容性不需要设定移除日期，也不需要逐一列出使用方。临时兼容性应明确负责人、迁移期限，并对两种路径进行检查。文档缺失是调查并记录契约的理由，而不是可以安全删除的证明。只有在确认没有受支持的调用方或契约仍需要它们后，才能移除别名、旧版分支和适配器。

必须保留兼容性时，应明确标示：

// TODO(compat): remove after API clients stop sending `workspaceId` on 2026-07-01.

标记开头应使用 TODO/FIXME/HACK，以便扫描器的 todo-compat 规则检测到它——单独的 // Compatibility: 注释不会被标记（关键词规则会跳过注释行）。

扫描器

scripts/scan-fallbacks.py 会对源代码进行确定性扫描，以查找常见的回退问题：

• 环境变量默认值（os.getenv/os.environ.get/process.env.X ||）和直接读取环境变量，
• || / ?? 回退值，
• legacy、deprecated、backwards-compatible 和 migration 等关键词，
• 空的或吞掉异常的 catch 块（JS/TS）和吞掉异常的 except 块（Python），
• 可选依赖回退，
• 别名和双配置键。

检测注意事项：legacy/compatibility 关键词规则只会匹配代码行，不会匹配注释行，因此单独的 // Compatibility: ... 标记不会被检测到。只有以 TODO/FIXME/HACK/XXX 开头的临时兼容性注释才会被检测到（由 todo-compat 规则处理）——请参阅“兼容性”部分的标记格式。关键词规则还会跳过声明式清单（package.json、tsconfig.json），以避免匹配依赖名称。--fail-on 只接受 medium 或 high（没有低严重级别的规则）——之前可接受的 --fail-on low 现在会因 argparse 错误而退出，因此请更新所有传入该参数的脚本。

扫描器不能代替判断。应将其视为待检查位置的索引，然后让代码变得更简单、更确定。

完成检查

完成前，请确认：

• 每个发现项都已分类（移除 / 必须保留 / 验证 / 保留），而不只是列出。
• 已移除的回退有更新调用点，并有测试证明在缺少依赖、输入、配置或环境变量时会确定性地失败。
• 保留的回退有明确理由（产品需求、外部契约，或由负责人负责且有明确期限的迁移）。
• 编辑后重新运行了扫描器，以及代码库中相关的测试／类型检查／lint／构建。
• 明确报告了所有剩余的回退，而不是将其隐去。