kestra-flow-hardening

Kestra フロー堅牢化スキル

既存の Kestra フローを監査し、レジリエンス／冪等性／ガードレールの不足を重大度順のレポートとして提示した後、ユーザーが確認した変更を適用します。

これは、関連する次のスキルに対する監査用のスキルです。

スキル	担当
kestra-flow	作成 — 意図に基づいてフロー YAML を作成／変更／デバッグ
kestra-flow-hardening	監査 — 不足を見つけ、ガードレールを提案して適用
kestra-ops	運用 — kestractl を使って検証／デプロイ／実行

「新しいフローを作成する」場合は kestra-flow に、「これを検証／デプロイする」場合は kestra-ops に引き継ぎます。

使用するタイミング

堅牢化、監査、レビュー、本番環境への対応／レジリエンス／冪等性の向上を求める依頼が対象です。

• 「このフロー／これらのフローを本番環境向けに堅牢化してください。」
• 「フローを監査して、信頼性のために不足しているものを確認してください。」
• 「このフローにリトライ、タイムアウト、エラーハンドリングを追加してください。」
• 「この名前空間のフローをレビューして、レジリエンスの不足を確認してください。」

説明から新しいフローを作成する場合は、このスキルを使用しないでください。その場合は kestra-flow を使用します。

必須入力

• 優先順位順に並べた 1 つ以上のフロー：
  1. チャットに貼り付けたインライン YAML
  2. ファイルパス、glob、またはディレクトリ（例：./flows/、./flows/*.yml）
  3. ライブインスタンス — kestra-ops／kestractl 経由で取得したフロー（ユーザーがスキルを組み合わせて使用します。このスキルでは稼働中のインスタンスは必須ではありません）
  4. 名前空間／ディレクトリ内の一括フロー
• Kestra のバージョンとエディション（OSS／EE）。 不明な場合は一度確認し、既定では最新の OSSを使用します。バージョン／エディション固有の推奨事項を判断するために使用します。

ワークフロー

ステップ 1 — フロースキーマを取得する（信頼できる情報源）

curl -s https://api.kestra.io/v1/plugins/schemas/flow

生の JSON を読み込みます。スキーマは、対象バージョンに存在するプロパティと型を判断するための信頼できる情報源です。スキーマに存在しないプロパティは決して推奨しないでください。これにより、retry.maxAttempt（0.24 より前）と retry.maxAttempts のようなバージョンによる落とし穴を検出できます。

ステップ 2 — 対象範囲とコンテキストを確認する

• 入力形式（貼り付け／ファイル／glob／ディレクトリ／名前空間）を特定します。
• バージョンとエディションを確認します（指定がない場合は最新の OSS が既定です）。
• ディレクトリまたは名前空間の場合は、レポートを作成する前に対象となるフローをすべて収集します。

ステップ 3 — フローの兆候に応じて調整する（比例性）

堅牢化は、フローの内容と実行場所に応じて調整する必要があります。次の兆候を読み取り、監査内容を合わせてください。すべてのフローに固定のチェックリストを適用しないでください。

• トリガー／スケジュールがある → 同時実行、SLA、重複実行の動作が関係します。手動実行のフローでは、その必要性は大幅に低くなります。
• 実際の副作用（書き込み、外部呼び出し、クラウドジョブ、スクリプト）がある → レジリエンスと冪等性に関する指摘が重要です。純粋な計算処理やログ出力のみのフローでは必要ありません。
• 環境のヒントとなる名前空間 — prod.*／staging.* では基準を高く設定し、dev.*／sandbox.*／tutorial.* では軽めに対応します（「開発環境のようです。昇格するまでは堅牢化を保留します」）。
• すでに存在する制御 → その点を認識し、すでに存在する項目を再度指摘しないでください。

リスクを決して捏造しないでください。 フローに実際に問題がない場合は、*「重大または高リスクの指摘はありません。このフローは適切に堅牢化されています」*と返すことが正しく、推奨されます。忙しく見せるために重大度の低い細かな指摘を作り出さないでください。

ステップ 4 — 監査の分類体系を実行する

関連する各項目を評価します。各構成要素に対する正確でコピー＆ペースト可能な YAML と、「適用する場合／適用しない場合」のガイダンスについては、 references/hardening-patterns.md を読み込んでください。

レジリエンス

• 一時的な失敗が発生しやすいタスク（HTTP、JDBC、クラウド API）でリトライを設定します。以下の冪等性の段階を参照してください。
• 実行可能なすべてのタスクにタイムアウトを設定します（スクリプト、クエリ、クラウドジョブのハングやコストを制御します）。
• 実行全体の再試行が適切な場合は、フローレベルの retry を設定します。

失敗処理

• アラートにはグローバルな errors を使用し、対象を絞ったクリーンアップにはフロー対応タスク内のローカルな errors を使用します。
• リソースの破棄（コンテナ、一時的なインフラ）には finally を使用します。実行がまだ RUNNING の間に実行されます。
• runIf を介した最終状態ベースの通知（SUCCESS / FAILED / WARNING）には afterExecution を使用します。
• 真に重要度の低いタスクに限り、allowFailure / allowWarning を設定します。

並行処理と冪等性

• 共有システムやレート制限のあるシステムにアクセスするフローには、concurrency の上限と behavior（QUEUE / CANCEL / FAIL）を設定します。
• 冪等性ガードを設けます。system.correlationId と重複チェック（EE）、または KV ベースの状態ガード（OSS）を使用します。
• トリガーの allowConcurrent / スケジュールの重複実行時の動作を設定します。

ガードレールとコントラクト

• 実行前の入力検証には checks（≥ 1.2）を使用します。
• sla — 違反ラベルとアラートを伴う MAX_DURATION / EXECUTION_ASSERTION を設定します。
• 入力の型付けには、自由形式の STRING ではなく SELECT / ENUM / SECRET を使用します。

衛生管理

• フローが約 100 個を超えるタスクを含む場合、または実行コンテキストが肥大化する場合は、サブフローを切り出します。
• 大きな出力を実行コンテキストに保持する代わりに、store: true / stores を使用します。
• 説明、ラベル、命名規則を整備します。
• ハードコードされたシークレットや認証情報を使用しません（kestra-flow のルールを再利用します。以下の「共通ルール」を参照してください）。

プラットフォーム適合性と保守性（参考情報 — 強化項目ではなく、ブロッカーにもなりません） これらはリスクではなく推奨事項です。重大度が付くことはなく、ブロックもしません。別個の 参考情報 セクションに表示されます（レポート形式を参照）。フローを制限するのではなく、より適切に保守されたフローへユーザーを促すために使用してください。

• インラインスクリプトが長い場合 → Namespace Files。 インラインの script: / commands: ブロックが大きい（およそ 15～20 行超）Script タスクや、実際のプログラムロジックを含む Script タスクは、読み取り、テスト、バージョン管理が難しくなります。コードを Namespace File に移して Commands タスクから呼び出す（namespaceFiles: {enabled: true, include: [...]}）、または Script タスク内で read('path') を使って読み込むことを推奨します。Kestra 自身のガイダンスでは、本番ワークロードには Commands、素早い反復には Script を使用します。
• プラグインの機能を重複して実装するスクリプト → ネイティブプラグイン。 スクリプトが Kestra プラグインの機能を再実装している場合は、保守するカスタムコードを減らすため、ネイティブタスクを推奨します。一般的な使用方法をプラグインファミリーと照合し、名前を挙げる前に、取得したスキーマにそのタスクが存在することを確認してください。
  • curl / wget / requests → io.kestra.plugin.core.http.Request / Download
  • psql / mysql / sqlite3 → 対応する JDBC プラグイン（io.kestra.plugin.jdbc.*）
  • aws / gcloud / az CLI → クラウドプラグイン（io.kestra.plugin.aws|gcp|azure.*）
  • dbt → io.kestra.plugin.dbt.*、git clone → io.kestra.plugin.git.Clone
• Namespace Files をコンテキスト内で利用できる場合は、スクリプトロジックのうちどの程度をネイティブタスクに置き換えられるかを評価し、その量を数値で示します（「N ステップ中約 X ステップをネイティブプラグインタスクに置き換え可能」）。

Step 5 — 各指摘を重大度で分類する

重大度	定義	例
Critical	本番環境でデータ破損、副作用の重複、または気付かれないデータ損失を引き起こします	冪等でない書き込みに対する Retry / allowFailure、アトミックでない状態更新に対する同時実行数の制限がない、ハードコードされたシークレット
High	停止／ハング／コストの急増、または検知されない障害を引き起こします	クラウド／スクリプトタスクにタイムアウトがない、errors のアラートがない、ビジネス上重要なスケジュールに SLA がない
Medium	レジリエンス／復旧可能性が低下します	HTTP / JDBC に一時的なリトライがない、finally によるティアダウンがなくリソースがリークする、入力の型指定が緩い
Low	衛生面／保守性に関する問題です	説明／ラベルがない、命名、大きな出力に対して store が未設定

プラットフォーム適合性に関する推奨事項（長いスクリプト → Namespace Files、スクリプト → ネイティブプラグイン）には、 重大度を割り当てません。別途 Advisory として報告し、ブロックすることはありません。

Step 6 — リトライを推奨する前に、冪等性を判断する

不安定な読み取りに対するリトライは適切なアドバイスですが、冪等でない書き込みでは致命的です （二重請求、挿入の重複）。候補となる各タスクを、推奨の前に分類してください。

区分	検出方法	リトライの推奨
Safe	型から読み取り専用と判断できる（HTTP GET、SELECT、fetch / list、Log）	制限なくリトライを推奨
Conditionally safe	自然な冪等性キーを持つ書き込み、またはトランザクション／アップサートのタスク	前提条件を明記したうえでリトライを推奨
Unsafe / unknown	内容が不明なスクリプト、未知のエンドポイントへの POST / PUT、非トランザクションの書き込み	無条件のリトライは推奨しないでください。 レポートで冪等性に関する確認事項を、両方の選択肢とともに提示してください。重複排除ガード（correlationId / KV）と、安全性が確認できた場合のリトライを示します。確認時にユーザーが判断できるようにしてください。

Step 7 — レポートを出力する

形式（ユーザーが番号で選択できるよう、指摘には全体を通した番号を付けます）：

## Hardening audit: <flow id> (<namespace>, v<X.Y>, OSS/EE)

### Critical
1. **<title>** — `tasks.<id>`
   Risk: <what breaks in production if unfixed>
   Caveat: <e.g. only safe if this endpoint dedupes on a key>
   Proposed: <the edit, or both branches for unknown-safety tasks>

### High
2. ...

### Medium
### Low

### Advisory (platform-fit) — not hardening, optional
- **Long inline script** — `tasks.transform`
  Move the ~40-line script into a Namespace File and call it from a `Commands` task
  (versioned, testable, editable in the Code Editor).
- **Script duplicates a plugin** — `tasks.fetch`
  This `curl` shell task can be `io.kestra.plugin.core.http.Request` (verified in schema).

---
Summary: N Critical · N High · N Medium · N Low · N Advisory
Reply with the numbers to apply (e.g. `1,4,7`), `all`, or `none`.

• 重大度ごとにまとめ、各指摘にはリスク＋注意事項＋修正案＋重大度を記載します。
• 差分は確認時まで提示しません — レポートは一覧しやすくしてください。
• タスクを追加する構造的な編集（冪等性ガードの挿入、フローレベルのリトライ動作など）は、1 行だけの変更ではないことが明確に分かるようにしてください。
• 一括処理：すべてのフローを横断して重大度順に並べた統合レポートを、フローごとのサマリーテーブルとともに出力し、確認後にフローごとに編集してください。
• EE 専用の指摘（例：correlationId ガード）には必ず EE と明記し、OSS での代替策（KV ガード）を示して、EE の方法は付加価値として提示してください。

Step 8 — 確認済みの編集を適用する

apply 1,4,7 / all の場合：

• 構造を保ちながら、必要箇所だけを編集します。 関連するタスク／ブロックのみを変更してください。ルートの id / namespace、タスクの順序、コメントを保持します。無関係な部分は決して再構成しないでください。
• ファイル入力 → ファイルをその場で編集します。貼り付けられた YAML → 変更後の YAML を返します。一括処理 → 各ファイルを編集します。
• すべての編集を、取得済みスキーマに照らして再検証します（プロパティと型が存在している必要があります）。
• 最初の番号選択は、インフォームドコンセントとして扱います（レポートですでに各リスク／注意事項を示しています）。指摘ごとに再確認を求めず、適用時に差分を表示してください。
• 最終チェックとして kestractl flow validate（kestra-ops 経由）の使用を任意で提案してください。稼働中のインスタンスは必須としないでください。

共有ルール（kestra-flow から継承）

繰り返し記載せず、ルールに揺れが生じないよう kestra-flow スキルのルールを再利用してください。

• スキーマ準拠 — スキーマで定義されたタスクの種類とプロパティのみを使用します。
• シークレット／認証情報のハードコード禁止 — 型が SECRET の inputs または {{ secret('...') }} を使用します。
• 引用符 — 二重引用符を優先し、必要な場合は内側で単一引用符を使用します。
• 構造の維持 — 関連する部分のみを変更し、id / namespace を保持します。

プロンプトの例

• 「このフローを本番環境向けに堅牢化してください。」（インライン貼り付け）
• 「./flows/ingest.yml を監査し、安全な箇所にリトライとタイムアウトを追加してください。」
• 「./flows/ 内のすべてのフローを確認し、レジリエンスの不足箇所を洗い出して、深刻度の高い順に並べてください。」
• 「このスケジュール実行フローを冪等にしてください。ときどき2回実行されます。」（冪等性の段階を判断）
• 「このビジネスクリティカルなフローにアラートと SLA を追加してください。」