fail-fast

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. スキャナーを再実行し、リポジトリに関連するテスト、型チェック、リント、またはビルドも実行します。

8. 残っているフォールバックを明示的に報告します。見えないまま残さないでください。

環境変数

環境変数は設定の契約であり、任意の候補ではありません。

検証済みの環境スキーマがあるプロジェクトでは、必須値をアプリケーションコードで使用する前に、検証エラーとして失敗させてください。プロジェクトの環境モジュールから型付きの値をインポートします。必須キーがスキーマにない場合、アプリケーションにフォールバックを追加するのではなく、そのスキーマで宣言して検証してください。

プロジェクトで既に使われている環境検証とビルドチェックを使用します。実際のコマンドについては、スクリプトとバリデーターのドキュメントを確認してください。このスキルに従うためだけに新しいパッケージをインストールしないでください。

process.env を直接読み取ってよいのは、環境スキーマモジュール、生成された環境設定、NODE_ENV や CI など範囲の狭いシステムキー、または明示的に文書化されたマイグレーション用の例外に限ります。

次のようなパターンを削除します。

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-compat ルールで検出されるよう、マーカーの先頭に TODO／FIXME／HACK を付けてください。コメント行はキーワードルールの対象外であるため、// Compatibility: だけのコメントは意図的に検出されません。

スキャナー

scripts/scan-fallbacks.py は、一般的なフォールバックの兆候をソースコードから決定論的にスキャンします。

• 環境変数のデフォルト値（os.getenv／os.environ.get／process.env.X ||）と環境変数への直接アクセス
• ||／?? によるフォールバック値
• レガシー、非推奨、後方互換、移行に関するキーワード
• 空の catch ブロック、例外を握りつぶす catch ブロック（JS/TS）、例外を握りつぶす except ブロック（Python）
• オプションの依存関係に対するフォールバック
• エイリアスと二重の設定キー

検出に関する注意事項：レガシー／互換性キーワードのルールはコメント行ではなくコード行でのみ動作するため、// Compatibility: ... だけのマーカーは意図的に検出されません。一時的な互換性に関するコメントは、先頭に TODO／FIXME／HACK／XXX を付けた場合にのみ検出されます（todo-compat ルール）。マーカーの形式については「互換性」セクションを参照してください。依存関係名との誤一致を避けるため、キーワードルールは宣言的なマニフェスト（package.json、tsconfig.json）も対象外です。--fail-on で指定できるのは medium または high のみです（低重大度のルールはありません）。以前は受け付けられていた --fail-on low は、現在は argparse エラーで終了するため、これを渡していたスクリプトを更新してください。

スキャナーは判断の代わりにはなりません。調査すべき箇所を示す一覧として扱い、そのうえでコードをより単純かつ決定論的にしてください。

完了チェック

作業を終える前に、以下を確認してください。

• 各検出項目を単に列挙するのではなく、分類している（削除／必須とする／検証する／維持する）。
• 削除したフォールバックについて、呼び出し箇所を更新し、依存関係、入力、設定、環境変数がない場合に決定論的に失敗することをテストで確認している。
• 維持するフォールバックについて、その理由（製品要件、外部との契約、または担当者がいる期限付き移行）を明示している。
• 編集後にスキャナーと、リポジトリに関連するテスト／型チェック／Lint／ビルドを再実行している。
• 残っているフォールバックをすべて明示的に報告し、見えないままにしていない。