inngest-brownfield-audit

Inngest ブラウンフィールド監査

既存のコードベースを調査し、「意味のある箇所に」Inngest を追加したり、壊れやすいバックグラウンド処理を移行したり、変更を加える前に耐久性のギャップを見つけたりするよう依頼されたときに、このスキルを使用します。

これはエージェントファーストのワークフローです。リポジトリ内の証拠に基づいて監査を行い、各結論の根拠となった具体的なファイルとコールサイトを明示し、現在の動作を維持する小さな統合の変更を行います。

トリガーするタイミング

次のようなリクエストにこのスキルを使用します。

• 「このリポジトリを Inngest の活用機会について監査してください」
• 「このコードベースに Inngest を追加してください」
• 「私たちの Webhook / cron ジョブ / バックグラウンドタスクを信頼できるものにしてください」
• 「デプロイやプロセスクラッシュで処理が失われる可能性がある箇所を見つけてください」
• 「壊れやすいポーリング、遅延ジョブ、fire-and-forget の Promise を置き換えてください」
• 「この AI ワークフロー / エージェントを耐久性のあるものにしてください」

ユーザーがブラウンフィールドのリポジトリではなくゼロから始める場合は、inngest-setup、inngest-durable-functions、inngest-events、inngest-steps を使用し、AI ワークフローについてはこのスキルのエージェントパターンを使用してください。リクエストにスコアリング、セッション、実験、遅延スコアラー、Insights、または結果ベースの評価が含まれる場合は、inngest-agent-evals を使用してください。

監査ループ

1. プロジェクトの形を把握します。

   • package.json、ワークスペースファイル、アプリ/ルーターの構造、サーバーエントリポイント、デプロイ設定、テストスクリプトを読みます。
   • フレームワークを特定します: Next.js App Router、Next.js Pages Router、Express、Hono、Fastify、Remix、SvelteKit、Astro、NestJS、worker 専用サービス、その他。
   • ファイルを追加する前に、パッケージマネージャーと TypeScript の規約を検出します。

2. 既存の Inngest の使用箇所を見つけます。

   • inngest、createFunction、serve(、/api/inngest、INNGEST_、step.run、step.sleep、step.waitForEvent、step.sendEvent、step.invoke、step.ai、inngest.send、@inngest/realtime を検索します。
   • Inngest が存在する場合は、何かを変更する前に、バージョン、クライアント設定、serve エンドポイント、登録済み関数、イベントの命名、環境変数、v3/v4 の API の形を調べます。

3. 耐久性のギャップを見つけます。

   • fire-and-forget の処理を検索します: void someAsync()、await されていない Promise、.then( チェーン、setTimeout、setInterval、HTTP レスポンス後の切り離されたジョブ、ルートハンドラー内のバックグラウンド処理。
   • cron とスケジューラーを検索します: cron、node-cron、agenda、bull、bullmq、bee-queue、qstash、sqs、temporal、trigger.dev、デプロイの cron 設定、スケジュールされた API ルート。
   • Webhook と at-least-once のプロデューサーを検索します: Stripe、Clerk、GitHub、Slack、Shopify、HubSpot、Linear、Svix、および一般的な webhook。
   • 長時間実行される処理を検索します: PDF 生成、エクスポート、動画/画像処理、埋め込み、一括メール、インポート、ETL、同期ジョブ、ポーリングループ、リトライ、外部 API 呼び出し。
   • AI エージェントの形を検索します: ツールループ、LLM 呼び出し、トークンのストリーミング、人手による承認、マルチステップ推論、ベクトル検索、eval ループ、スコアリング、実験の割り当て、ユーザーフィードバックのシグナル、レート制限やリトライセーフな状態を必要とするプロバイダー呼び出し。

4. 各候補を分類します。

   • P0: ユーザーに視認できる損失、重複した課金/メール/アクション、タイムアウト、見逃された Webhook、クラッシュしやすいワークフロー。
   • P1: 壊れやすいが回復可能なバックグラウンド処理、手動リトライの負担、ノイズの多い 429、不十分な可観測性。
   • P2: クリーンアップ、人間工学、または将来の移行の機会。
   • 各候補について記録します: ファイル、現在のトリガー、副作用、冪等性キー、障害モード、推奨される Inngest プリミティブ、移行の規模、確信度。

5. 最小の安全な統合を選びます。

   • 広範な書き換えよりも、1 つの縦方向のスライスを優先します。
   • 可能な限り既存のドメイン関数とデータモデルを維持します。
   • Inngest クライアントと serve エンドポイントは 1 回だけ追加します。
   • 副作用は一度に 1 つの境界ずつ step.run に移動します。
   • リトライを追加する前に、イベント ID とデータベース書き込みを冪等にします。
   • 既存の動作と新しいイベント/関数の境界の周りにテストを追加します。

便利な検出コマンド

リポジトリに合ったコマンドを実行してください。rg を優先し、出力は焦点を絞ってください。

rg -n "inngest|createFunction|step\\.|serve\\(|/api/inngest|INNGEST_" .
rg -n "setTimeout|setInterval|Promise\\.all|void [a-zA-Z0-9_]+\\(|\\.then\\(" .
rg -n "cron|node-cron|schedule|bull|bullmq|bee-queue|agenda|qstash|sqs" .
rg -n "webhook|stripe|svix|clerk|github|shopify|slack|hubspot|linear" .
rg -n "retry|backoff|poll|status|timeout|429|rate limit|rate-limit" .
rg -n "openai|anthropic|ai\\.|generateText|streamText|tool|agent|embedding" .

リポジトリが大きい場合は、検索をアプリのソースディレクトリに絞り、生成物やベンダーのフォルダを除外してください。

ブラウンフィールドの判断マトリクス

既存の形	Inngest の適合性	主なプリミティブ
HTTP ハンドラーが応答前に遅い副作用を実行する	イベントを発行し、すぐに応答する	inngest.send、イベントトリガー、step.run
Webhook はすばやく確認応答する必要があるが、確実に処理する必要がある	署名を検証し、冪等なイベントを発行する	イベント ID、step.run、リトライ
Cron ジョブが途中で進捗を失う	Cron トリガーの耐久性のある関数	Cron トリガー、ページ単位の step.run、フロー制御
ポーリングループが外部の非同期処理を待つ	耐久性のある待機または耐久性のあるポーリング	step.waitForEvent、step.sleep、step.run
大規模なファンアウトがリクエストやサーバーレスの制限を超える	オーケストレーションと項目単位の処理を分割する	step.sendEvent、項目単位の関数、同時実行数
外部 API が 429 を返す	制限を関数の設定に移す	throttle、rateLimit、concurrency
人によるレビューに数日かかることがある	待機を Inngest に永続化する	step.waitForEvent、タイムアウト、リアルタイム
AI エージェントやツールのループにリトライ安全な進捗が必要	ツールやモデルの境界ごとに 1 ステップ	step.ai、step.run、step.sleep、リアルタイム
AI ワークフローに本番環境での評価が必要	成果シグナルを耐久性のある実行に紐付ける	meta.sessions、step.score、createScorer、defer、group.experiment
既存のキューが脆弱な処理を隠しているだけ	キューの境界を段階的に置き換える	イベントトリガー、冪等性、関数レベルのリトライ

統合計画の形式

編集する前に、調査結果を次の簡潔な形でまとめてください：

Inngest audit:
- Existing Inngest: none / partial / healthy / risky
- Framework: <framework and evidence>
- Best first slice: <file + workflow>
- Why: <loss/timeout/retry/idempotency failure>
- Proposed primitives: <event, steps, flow control, waits, realtime>
- Idempotency key: <source of truth>
- Files likely touched: <short list>
- Tests/checks: <commands or focused cases>

その後、ユーザーが監査のみを依頼していない限り実装してください。

既存の Inngest チェックリスト

Inngest がすでに導入されている場合は、次を確認してください：

• 単一の共有クライアントが安定したモジュールからエクスポートされている。
• アプリの id が安定したスラッグであり、デプロイ固有のデータから派生していない。
• v4 のローカル開発では INNGEST_DEV=1 を使用し、本番環境では INNGEST_SIGNING_KEY を使用する。
• Serve エンドポイントのパスが発見可能であり、通常は /api/inngest である。
• Serve ハンドラーが、同期すべきすべての関数を登録している。
• 副作用と非決定的な処理がステップの内部にある。
• ステップ ID が安定しており、説明的である。
• イベント名が domain/noun.verb に従っている。
• 再生される可能性のあるイベントが決定的な ID を使用している。
• Webhook ハンドラーがイベントを発行する前に署名を検証している。
• 外部 API に制限がある箇所でフロー制御が設定されている。
• リアルタイムは v4 ネイティブの inngest/realtime を使用しており、v3 の @inngest/realtime パッケージを使用していない。

耐久性のあるエージェントパターン

AI またはエージェントのワークフローで、モデル呼び出し、ツール呼び出し、待機、承認、またはストリーミング UI 更新をまたいだ耐久性のある進捗が必要な場合は、Inngest を使用します。

適した候補:

• ツールや外部 API を呼び出すマルチステップエージェント。
• 1 回の HTTP リクエストのライフタイムを超える可能性がある LLM ワークフロー。
• ヒューマン・イン・ザ・ループによるレビュー、承認、修正、またはエスカレーション。
• 外部イベントやスケジュールされたフォローアップのために一時停止する必要があるエージェント。
• プロバイダーレベルのレート制限とコスト保護が必要なバルク AI 処理。
• 耐久性のある実行からストリーミングすべき、ユーザーに表示されるエージェントの進捗。

推奨される構成:

1. HTTP/UI リクエストがユーザーの意図を保存し、安定した id を持つイベントを発行します。
2. Inngest 関数が step.run 内で状態を読み込みます。
3. 各モデル呼び出し、ツール呼び出し、ベクトル検索、外部の副作用は、それぞれ独自の step.ai または step.run の境界内に配置します。
4. 人間による一時停止には、タイムアウト付きの step.waitForEvent または step.waitForSignal を使用します。
5. 進捗更新には、ステップ間で step.realtime.publish を、既存の step.run 内では inngest.realtime.publish を使用します。
6. プロバイダーのレート制限には、その場しのぎのプロセス内スロットラーではなく、concurrency、throttle、または rateLimit を使用します。

避けるべきこと:

• エージェントの状態をメモリ内にのみ保持すること。
• 1 回のツール失敗の後にエージェントループ全体をリトライすること。
• 結果がメモ化されていないために、繰り返し成功したモデル呼び出しに対して課金すること。
• フォローアップと承認に setTimeout や cron ポーラーを使用すること。
• ワークフロー自体が別の場所で耐久性を持っているのに、プロセスローカルの WebSocket サーバーから進捗をストリーミングすること。

実装ガードレール

• 動作しているキュー、cron、webhook を盲目的に置き換えないでください。まず薄い Inngest スライスで動作を維持します。
• リポジトリにすでに存在する場合は、クライアントを重複して作成したり、エンドポイントを提供したりしないでください。
• 新しい関数では、データベース書き込み、API 呼び出し、ランダム ID、タイムスタンプ、LLM 呼び出しをステップの外に置かないでください。
• 欠落した冪等性をリトライの背後に隠さないでください。リトライには冪等な副作用が必要です。
• シークレットや開発モードのフラグをソースにハードコードしないでください。
• アプリが同期できなくなる状態のままにしないでください。新しい関数を serve エンドポイントに登録し、利用可能な型チェック/テストを実行します。

検証

統合パスを証明するチェックを選択します:

• 変更したアプリの型チェック/ビルド/lint。
• 移行したハンドラーまたはワークフローに関する既存のテストの実行。
• リポジトリがサポートしている場合は、「ハンドラーがイベントを発行して素早く戻る」および「関数がステップ境界内で同じドメイン操作を呼び出す」ための焦点を絞ったテストを追加します。
• ローカルランタイムが利用可能な場合は、アプリと Inngest dev サーバーを起動し、関数が同期することを確認してから、サンプルイベントを送信します。
• 静的なチェックのみが利用可能な場合は、ランタイム同期が検証されなかったことを明示的に述べます。