One Three One Rule

1-3-1 形式の提案書です。課題ひとつ、選択肢三つ、推す案ひとつでまとめます。

skill の情報

参考: SKILL.md 全文

1-3-1 Communication Rule

やり方がいくつも考えられて、どれを選ぶべきかをはっきり示してほしいときのための、決めごとの型です。課題を短く言い切り、長所と短所つきの選択肢を三つ並べ、推す案について実行できる段取りまで書きます。

こんなときに使います

• 「1-3-1 で」と名指しで頼まれたとき。
• 技術的な判断について「選択肢を出して」「どんな手があるの」と言われたとき。
• やり方が複数あり、それぞれに無視できない差があるとき（設計、道具立て、移行の進め方など）。
• チームや関係者にそのまま回せる提案書がほしいとき。

答えがひとつに決まっている単純な質問、不具合を追っている最中、すでにやり方が決まっている作業には使いません。

手順

1. 課題（一文で）

• 決めるべきことや、たどり着きたい結果を、短い一文で言い切ります。
• *何を* に絞ります。*どうやって* は書きません。実装の詳しい話、道具の名前、個別の技術には触れません。
• 短くまとめます。「〜と〜」でつなぎたくなったら、それは課題が二つある証拠です。

1. 選択肢（ちょうど三つ）

• 実現できて、互いにはっきり違うやり方を三つ、A・B・C として並べます。
• どれにも、短い説明と長所・短所を付けます。
• 三つは本当に別の道筋にします。同じやり方の細かい違いを並べても意味がありません。

1. 推す案（ひとつ）

• どれを推すのか、そしてなぜそうなのかを、相手の状況と優先度に照らして書きます。
• はっきり書きます。ここは逃げ道を用意する場所ではなく、専門家としての判断を示す場所です。

1. 完了の条件

• 推す案について、何がどうなれば終わりなのかを具体的に並べます。
• 曖昧な願望ではなく、確かめられる具体的な結果にします。
• 相手が別の案を選んだら、この節はその案に合わせて書き直します。

1. 進め方

• 推す案を実行するための具体的な手順です。
• 使うコマンド、道具、作業を、書けるところは具体的に書きます。
• 相手が別の案を選んだら、この節もその案に合わせて書き直します。

確かめかた

• 課題がちょうど一文になっている。
• 選択肢がちょうど三つ（A・B・C）あり、それぞれに長所と短所が書かれている。
• 推す案がひとつだけ示され、理由が添えられている。
• 完了の条件と進め方が、推す案と食い違っていない。
• 相手が別の案を選んだときは、推す案・完了の条件・進め方がそれに合わせて更新されている。

例

利用者:「API クライアントに再試行の仕組みを入れる件、1-3-1 で出して」

エージェント:

課題: 外部サービスへの API 呼び出しが負荷のかかる時間帯にときどき失敗するため、うまく再試行する仕組みが要ります。

選択肢:

• 案 A: 共通のユーティリティに、ゆらぎ付きの指数バックオフを実装する。

長所: 単純で、誰でも知っているやり方。実装がひとつで済み、呼び出す側すべてで共有できます。 短所: 回路遮断の仕組みがない。再試行のあいだ、呼び出した側は待たされたままです。

• 案 B: 再試行ライブラリ（tenacity）をデコレータとして各エンドポイントの呼び出しに付ける。

長所: エンドポイントごとに設定でき、回路遮断や回数制限にも対応しています。 短所: 依存が増えます。デコレータなので、処理の流れが見えにくくなることがあります。

• 案 C: キューを使った非同期の再試行と、失敗分の退避先を用意する。

長所: 呼び出した側を待たせません。失敗した呼び出しは記録され、後から流し直せます。規模の拡大にも耐えます。 短所: 複雑さが大きく増えます。キューの基盤が要り、呼び出しの少ないサービスには過剰です。

推す案: 案 A。呼び出しの量からしてキューの基盤を用意するほどではなく、指数バックオフとゆらぎを備えた共通のユーティリティがあれば、依存を増やさずにこの失敗のしかたにきちんと対処できます。

完了の条件:

• api_retry() ユーティリティが、一時的な HTTP エラー（429、502、503、504）を処理する。
• 指数バックオフとゆらぎを使い、最大 3 回まで試し直す。
• 外部 API への呼び出しがすべてこのユーティリティを通る。
• 再試行のたびに、対象のエンドポイントと何回目かを記録する。
• 再試行を使い切った場合、すぐ成功した場合、いったん失敗してから成功した場合を、テストが押さえている。

進め方:

1. utils/api_retry.py を作り、最大再試行回数、待ち時間の基準値、試し直す対象のステータスコードを設定できるようにします。
2. random.uniform(0, base_delay) でゆらぎを加え、再試行が一斉に集中しないようにします。
3. api_client.py にある既存の API 呼び出しを、このユーティリティで包みます。
4. HTTP の応答を差し替えたテストを書き、再試行のそれぞれの筋道を確かめます。
5. わざと失敗するエンドポイントを立てて簡単な負荷試験を行い、実際の負荷のもとで確かめます。