python-resilience

python-resilienceスキルの概要

python-resilienceができること

python-resilience は、依存先が不安定でも Python コードがより安全に失敗できるよう設計するためのスキルです。主眼は、実運用で使えるレジリエンスパターンにあります。たとえば、リトライ、指数バックオフ、jitter、タイムアウト、上限付きのリトライウィンドウ、外部呼び出しを包む耐障害ラッパーなどです。

このスキルを入れるべき人

この python-resilience skill は、API、データベース、キュー、そのほかネットワーク越しのシステムとやり取りするサービスを扱う開発者、プラットフォームチーム、エージェント利用者に向いています。特に、「とりあえずリトライを足す」レベルではなく、どこまでを失敗処理の境界にするべきかまで含めて妥当な判断をしたいときに役立ちます。

このスキルが本当に解決する仕事

多くの人に必要なのは、信頼性の理論解説ではありません。実際に動く Python のパターンです。たとえば次のような疑問に答えるためのものです。

• 「このエラーはリトライすべきか、それとも即失敗させるべきか？」
• 「負荷時でも安全なバックオフ戦略はどれか？」
• 「タイムアウトはどこに置くべきか？」
• 「無限リトライや thundering herds をどう防ぐか？」
• 「この外部呼び出しは、どの decorator や helper で包むべきか？」

python-resilience の価値は、こうした判断を明示的に扱う点にあります。リトライロジックを一行の応急処置として済ませないのが特徴です。

汎用プロンプトとの違い

一般的なコーディング用プロンプトだと、あらゆる箇所に無差別にリトライを足したり、一時的な障害と恒久的な障害の違いを無視したりしがちです。python-resilience for Reliability は、そこに明確な方針があります。リトライ可能な失敗だけを対象にし、jitter を加え、試行回数と総時間に上限を設け、レジリエンスロジックを入れる主な場所は外部境界だと捉えます。

ソースが実際にカバーしている内容

上流のスキルは SKILL.md 1ファイルだけですが、中身はしっかりしています。中心となるテーマは次のとおりです。

• transient failure と permanent failure の区別
• exponential backoff
• jitter
• bounded retries
• tenacity を使った実践的な Python 例

確認コストが低く、導入も早い一方で、提供されるのはあくまでガイダンスです。パッケージ化されたライブラリやテストハーネスが入っているわけではない、という前提で見ておくべきです。

python-resilienceが特にハマるケース

python-resilience を使うべきなのは、たとえば次のような場面です。

• サードパーティ API を呼ぶ
• 不安定なネットワークやサービス連携を包む
• マイクロサービスやワーカーを作る
• 共通のクライアントユーティリティに信頼性制御を入れる
• レート制限、一時障害、断続的なタイムアウトを扱う

コードの大半がプロセス内の純粋ロジックなら、このスキルはそこまで高いレバレッジを出さない可能性があります。

python-resilienceスキルの使い方

python-resilienceのインストール前提

wshobson/agents リポジトリからこのスキルをインストールします。

npx skills add https://github.com/wshobson/agents --skill python-resilience

インストール後は、まず次のスキルファイルを開いてください。

• plugins/python-development/skills/python-resilience/SKILL.md

このリポジトリ領域にはスキル文書だけが置かれているようなので、導入手順はシンプルです。まずスキルを読み、そのパターンを自分のコードベースに適用します。

最初に読むべきファイル

SKILL.md を上から順に読むのが基本です。特に最初に確認したい価値の高いセクションは次の3つです。

1. When to Use This Skill
2. Core Concepts
3. Quick Start

この順で読むと、モデルにコード修正を頼む前に、適用対象、設計ルール、実装の形を先に把握できます。

このスキルに渡すべき入力

python-resilience usage の質は、こちらが渡す文脈に大きく左右されます。スキルを呼ぶ前に、最低でも次をそろえておくと精度が上がります。

• 保護したい関数やサービス境界
• 依存先の種類: HTTP API、DB、queue、cache、filesystem
• 実際に観測している例外や障害症状
• その失敗が transient か permanent か
• タイムアウト要件
• idempotency の制約
• 許容できる最大レイテンシ
• リトライ予算: 試行回数または総時間
• 多数のクライアントが同時にリトライしうるか

この情報がないと、モデルは広すぎる雑なリトライロジックを出しがちです。

あいまいな依頼を強いプロンプトに変える

弱いプロンプト:

Add resilience to this Python API client.

より良いプロンプト:

Use the python-resilience skill to refactor this Python client method.

Context:
- Dependency: third-party HTTP API
- Library: httpx
- Traffic: moderate, bursty
- Common failures: read timeout, connect timeout, occasional 429 and 503
- Permanent failures: 400, 401, 403 should not be retried
- Idempotency: safe to retry GET requests only
- SLO: fail within 8 seconds total
- Requirement: use bounded retries, exponential backoff with jitter, and clear logging

Task:
- Propose a retry policy
- Implement the wrapper/decorator
- Explain which exceptions and status codes are retryable
- Show where timeout configuration should live

こちらのほうがうまくいくのは、このスキルが判断できるよう設計されている境界条件を、きちんと与えているからです。

いきなりコードではなく、先に方針を聞く

強い python-resilience guide の進め方は、次の順番です。

1. 失敗の分類を確認する
2. リトライ/タイムアウト方針を出させる
3. トレードオフをレビューする
4. その後で実装コードを生成する

こうしておくと、「何をリトライすべきで、何をすべきでないか」を決める前に decorator に飛びつくのを防げます。

外部境界に対して使う

このスキルが最も効くのは、プロセス境界やネットワーク境界をまたぐコードに適用したときです。たとえば次のような箇所です。

• httpx や requests の呼び出し
• メッセージの publish / consume
• 一時的障害モードが既知のデータベースクエリ
• cloud SDK の呼び出し
• service client メソッド

最初から大きな業務ワークフロー全体を end-to-end で包むのは避けてください。まずは不安定な依存先の周囲にレジリエンス制御を置くのが先です。

良いpython-resilience出力に含まれるべきもの

スキルがうまく機能しているとき、出力には通常、次の要素が入ります。

• transient failure と permanent failure の明示的なルール
• 有限のリトライ上限
• exponential backoff
• jitter
• timeout の配置
• tenacity のような Python ツールを使った例
• idempotency と副作用に関する注意

もし結果が「3回リトライしましょう」だけなら、もっと明確な retry policy を求めたほうがよいです。

実装でリクエストしやすい実践パターン

元のスキルには tenacity ベースの quick start が含まれています。実務では、たとえば次のようなパターンを依頼できます。

• service client メソッドを包む decorator
• すべての outbound HTTP call を包む wrapper helper
• read と write で分けた retry policy
• 例外型や status code で絞る retries

更新系の操作では、リトライが安全かどうかをモデルに説明させてください。idempotency を無視した信頼性パターンは、重複した副作用を生みます。

python-resilience利用時によくあるミス

生成コードでは次の点を重点的に確認してください。

• 認証エラーやバリデーションエラーまでリトライしている
• タイムアウトがなく、リトライだけある
• 総量の上限がないリトライループになっている
• jitter なしのバックオフになっている
• 包みすぎて根本原因が見えなくなっている
• 非 idempotent な write をデフォルトでリトライしている

重要なのはコードスタイルより、こうした実運用上の詰まりどころです。

自分のリポジトリで使うときの実用ワークフロー

より良い結果を得るには、スキルに次を渡してください。

• 現在の client function
• ログに出ている exception class
• サンプルの status code
• レイテンシ予算またはリトライ予算
• 代表的な failure trace を1〜2件

そのうえで、次の順に依頼します。

1. policy summary
2. code changes
3. 追加すべき tests
4. ログに出すべき monitoring fields

コードだけをいきなり求めるより、この流れのほうが実装に載せやすい出力になりやすいです。

python-resilienceスキル FAQ

python-resilienceはWeb API専用ですか？

いいえ。python-resilience skill が扱うのは、広く「不安定な依存先」です。HTTP 呼び出しは最も説明しやすい例ですが、同じ考え方は queue、database、cache、cloud service など、一時的障害が起こりやすい対象にもそのまま当てはまります。

これはライブラリですか、それともガイダンススキルですか？

これはガイダンススキルであり、単独で使う Python package ではありません。tenacity ベースの例を含め、パターンや実装スタイルを教えてくれますが、それを自分のコードベースに適用するのは利用者側です。

python-resilienceを使わないほうがいいのはいつですか？

python-resilience を、すべての関数に載せるデフォルト層として使うべきではありません。特に相性が悪いのは次のケースです。

• 純粋な CPU バウンドのローカル処理
• 明らかに permanent なエラー
• リトライすると危険な副作用が重複するワークフロー
• retry window を取るには latency budget が厳しすぎるシステム

こうした場合は、fail fast にするか、統合の設計自体を見直すほうが適切です。

python-resilienceは初心者にも向いていますか？

はい。ただし、基本的な Python と例外処理は理解している前提です。スキルの核となる考え方自体は追いやすいものの、retry の安全性、timeout budget、どの失敗なら再試行してよいかといった業務文脈は利用者が渡す必要があります。

LLMにリトライを書かせるだけより何が良いのですか？

python-resilience for Reliability の強みは、単なるコード生成ではありません。失敗の種類、bounded retries、backoff の挙動を、モデルに筋道立てて考えさせやすくする点です。汎用プロンプトだと、こうした境界条件を落としやすく、負荷時に危険だったりノイジーだったりするリトライロジックを出しがちです。

python-resilienceは最適なretry policyを自動で決めてくれますか？

自動では決まりません。強力なパターン語彙は提供してくれますが、最適な policy は依存先の挙動、レイテンシ要件、idempotency ルール次第です。試行回数、待機レンジ、retry filter などは、自分の環境に合わせて調整する前提で考えてください。

python-resilienceスキルを改善する方法

失敗分類をより明確に渡す

python-resilience の結果を最も手早く改善する方法は、どの失敗が transient で、どれが permanent かを明示することです。たとえば次のように伝えます。

• transient: ConnectTimeout, ReadTimeout, 503, 一部の 429
• permanent: 400, 401, 403, schema error, bad credentials

この区別ひとつで、生成される policy が安全かどうかは大きく変わります。

レイテンシ予算とリトライ予算を渡す

予算を与えないと、モデルは根拠の薄いリトライ回数を選びがちです。たとえば次のような制約を具体的に伝えてください。

• max 3 attempts
• total retry window under 8 seconds
• single request timeout 2 seconds
• background job can tolerate 30 seconds total

こうした制約があると、より現実的なコードになりやすくなります。

操作がidempotentかどうかを伝える

レジリエンス実装で起こるミスの多くは、副作用の文脈が抜けていることに由来します。python-resilience usage を改善するには、各操作を次のようにラベル付けすると有効です。

• safe to retry
• safe only with idempotency key
• unsafe to retry automatically

これによって decorator の設計も exception filter も変わります。

明示的な「リトライしない条件」も聞く

「何をリトライすべきか？」だけを聞かないでください。あわせて次も確認しましょう。

• 何は fail fast させるべきか？
• 何は呼び出し元に即座に返すべきか？
• 何はログだけ残してリトライしないべきか？

ここを明確にすると、出力は本番利用にかなり近づきます。

実装とセットで可観測性も要求する

良い python-resilience guide は decorator の提示で終わりません。モデルには次の情報も出力させると有効です。

• ログ内の attempt count
• exception type
• elapsed time
• final failure reason
• retry exhaustion message

これがないと、レジリエンス層のせいで「なぜ呼び出しが失敗したか」が見えにくくなります。

初稿のあとに具体的に詰める

最初の出力のあと、次のような具体的なフィードバックで詰めていくと改善幅が大きくなります。

• “Do not retry POST requests.”
• “Cap total time, not just attempts.”
• “Handle 429 differently from 500.”
• “Use jitter to avoid synchronized retries.”
• “Separate timeout config from retry config.”

こうした反復は、実装品質を目に見えて上げます。

スキルが提案した失敗経路をテストする

モデルには、次の観点のテスト生成も依頼してください。

• transient exception の retries
• permanent exception の fast-fail 挙動
• retry exhaustion
• timeout enforcement
• backoff policy の境界

レジリエンスコードは、テストされていないと設定ミスを起こしやすく、安心して運用しにくいものです。

実際のトレースでpython-resilienceの出力を改善する

ログや stack trace のサンプルがあるなら、それを含めてください。抽象的な依頼よりも、実際の失敗証跡があるほうが、python-resilience は例外フィルタや timeout/backoff 設定をより狭く、実態に近い形で提案しやすくなります。

抽象度は上げすぎない

よくある失敗は、信頼性の高い client wrapper が欲しいだけなのに、フル機能の resilience framework 設計を頼んでしまうことです。最初は小さく始めてください。

• one function
• one dependency
• one retry policy

そのパターンが実際に有効だと確認できてから、必要に応じて広げるのが安全です。

python-resilienceをレビュー観点として使う

コードをすでに書いている場合でも、python-resilience はレビュー用プロンプトとして有効です。既存の retry logic を次の観点で点検させてください。

• unbounded retries
• missing jitter
• bad timeout placement
• retrying permanent failures
• hidden side-effect risks

成熟したコードベースでは、新規実装よりもこのレビュー用途のほうが高い価値を出すことも少なくありません。