superior-logic

Superior Logic

入力から観測可能な結果まで、正しさを明確に保ちます。リポジトリの既存アーキテクチャに合わせて解決策を構築し、契約に関わる変更はすべての関連箇所に反映します。

主な目的が差分、コミット、ブランチ、プルリクエスト、または作業ツリーの問題点を指摘することである場合は、代わりに superior-code-review を使用してください。対象を絞ったドメインロジックのレビューや、確認済みの動作変更の実装には、このスキルを使用してください。

動作をモデル化する

コードを選ぶ前に、次の点を特定してください。

• 信頼できる入力と信頼できない入力
• 出力と観測可能な副作用
• 不変条件と認可ルール
• 利用側と互換性の制約
• 想定される失敗、再試行、重複、順序、並行実行の条件

コードやドキュメントから確認できない場合に限り、重要な前提を明示してください。複数の解釈によってプロダクトの契約が変わる場合は、ユーザーに確認してください。

複数のバージョンにまたがる可能性がある、再試行や部分的なデプロイが発生する、共有 API、イベント、ファイル形式、クライアント／サーバー間の契約、ステートマシン、または複数段階のワークフローを変更する場合は、references/contract-evolution-and-workflows.md を読んでください。

責任の所在を明確にする

• 既存アーキテクチャで境界がサポートされている場合は、ドメイン上の判断をレンダリング、トランスポート、永続化から分離してください。
• データが信頼できるシステムに渡る時点で検証してください。クライアント側の検証はユーザー体験を向上させますが、サーバー側の正しさを保証するものではありません。
• 状態遷移を担う権威ある所有者は一つにし、状態のコピーを同期するのではなく、依存する状態を導出してください。
• リポジトリの信頼できる情報源となっている場合は、共有スキーマと型を使用してください。
• 共有契約を変更する場合は、プロデューサー、コンシューマー、検証、テスト、ドキュメントをまとめて変更してください。

状態と副作用を保護する

• 部分的な完了が不変条件に違反する場合は、関連する書き込みをアトミックに実行してください。それ以外の場合は、復旧可能な部分状態または補償処理を定義してください。
• 再試行や重複配信によって二重作成、二重請求、またはデータ破損が発生しうる場合は、繰り返し実行される操作を冪等にしてください。
• 処理が競合する可能性がある場合は、順序と並行実行時の動作を定義してください。根拠のない遅延は同期手段ではありません。
• リモート処理には、確立されたプロジェクトのパターンに従って、タイムアウト、キャンセル、上限付きの再試行を使用してください。一時的な状態に限って再試行してください。
• 安全な場合は、想定される失敗の後もユーザー入力と有用な復旧手段を保持してください。

スキーマ設計、クエリの形状、インデックス、トランザクション分離、マイグレーション、バックフィル、またはデータストアの展開安全性が依頼の主な部分となる場合は、superior-database を読み込んでください。基盤となるデータ契約が変わらない場合、通常の永続化のオーケストレーションはここで扱います。

レイテンシー、スループット、リソース使用量、キャパシティ、またはスケーラビリティが主な懸念で、測定とプロファイリングが必要な場合は、superior-performance を読み込んでください。通常の範囲制限と、明らかに不要な処理を避けることは、このスキルの対象です。

サービス目標、障害の分離、縮退運転、フェイルオーバー、または運用上の復旧が主な目的の場合は、superior-reliability を読み込んでください。パイプライン、成果物、環境への昇格、ロールアウト、またはロールバックの動作を担当するタスクでは、superior-delivery を読み込んでください。

信頼できる境界でセキュリティを徹底する

• 認証は呼び出し元を識別しますが、各リソースとアクションに対する認可は引き続き必要です。
• 可能な場合は、読み取りと書き込みの対象を認可された主体に限定します。
• ルートパラメーター、ヘッダー、非表示フィールド、ファイル名、クライアントの状態、Webhook、外部ペイロードは、信頼できないデータとして扱います。
• 認証情報と暗号化には、メンテナンスされているライブラリを使用します。トークン、暗号化、署名、シークレット保存の方式を独自に設計しないでください。
• シークレット、機密性の高い個人データ、支払い情報をログやユーザーに表示されるエラーに含めないでください。

API の強化、レート制限、トークンのセキュリティ、不正利用の防止、SSRF、または専用のセキュリティレビューが依頼に含まれる場合は、superior-api-security を読み込みます。ドメインの契約と不変条件は superior-logic の担当とし、脅威に基づく制御と否定的な検証にはセキュリティスキルを使用します。

原因が不明な障害を診断する

具体的な障害が発生しているものの、原因が不明、環境に依存、断続的、または因果関係の追跡を要する場合は、superior-debugging を読み込みます。原因を特定した後、対象範囲内のドメインルール、状態、永続化、または API 動作を修正する際には、このスキルを使用します。原因がすでに証明されている単純な実装上の欠陥には、専用のデバッグワークフローは必要ありません。

障害を把握できるようにする

• 復旧、変換、または有用なコンテキストの追加が可能なレイヤーでエラーを処理します。
• エラーをラップする際は、元の原因を保持します。
• 不明な障害を成功として扱ったり、処理を続行するためだけに握りつぶしたりしないでください。
• ユーザーには安全で実行可能なメッセージを示し、診断の詳細はプロジェクトで確立されている可観測性の経路に送ります。
• データに依存するループ、キュー、結果セット、再帰、再試行、メモリー内での蓄積には上限を設けます。

契約を検証する

内部の手順ではなく、観測可能な動作をテストします。通常の経路に加え、変更によって影響を受ける重要な境界、無効な入力、認可、部分的な障害、重複、再試行、並行処理のケースをテストします。可能であれば、対象を絞った失敗テストでバグを再現します。

テスト設計、テストレベルの選択、フィクスチャ、テストダブル、不安定な挙動、またはテストスイートの信頼性が依頼の主な内容である場合は、superior-testing を読み込みます。通常の実装検証はこのスキルの範囲に含まれ、専用のテストワークフローを読み込む必要はありません。

ドメインの動作を複数ステップのユーザージャーニー、情報アーキテクチャ、フィードバック、または復旧体験に合わせて設計する必要がある場合は、superior-ux を読み込みます。強制可能な状態遷移、不変条件、API、永続化はこのスキルの対象とします。

既存のテスト規約に従い、関連する範囲で最も限定的な lint、型、テスト、ビルドのチェックを実行します。未検証の条件と互換性のリスクを明示します。

最終的な契約、影響を受けるデータの生成元と利用側、障害時の動作、互換性やロールアウトに関する前提、実際に実施したチェックを報告します。実装と基盤システムによって保証されない限り、ワークフローをアトミックまたは厳密に 1 回だけ実行されるものとして説明しないでください。