implementation-strategy

実装方針

ワークフロー

1. 変更またはレビューする対象を特定します。公開済みのパブリック API、未リリースのブランチ内 API、内部ヘルパー、永続化されたスキーマ、ワイヤープロトコル、CLI／設定／環境変数のインターフェース、またはドキュメント／サンプルのみのいずれかです。
2. リリース済みの互換性が関係する場合は、まず origin から最新のリリースタグを特定し、リモートタグが利用できない場合に限りローカルタグを使用します。新たなリリース情報やスコープの変更によって古くならない限り、タスク内で検証済みのベースラインを再利用します。

   BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*' 2>/dev/null || git tag -l 'v*' --sort=-v:refname | head -n1)"
   echo "$BASE_TAG"
   

   ローカルタグを代替として使用した場合は、古い可能性があることを報告します。
3. コーディングを始める前に、以下の実装スコープ契約を記録します。
4. 影響を受ける各懸念事項について、最も近い既存の実装パイプラインと、信頼できる情報源となる関数、型、またはモジュールを特定します。並行するスキーマ、メタデータ、検証、識別、変換、または実行の仕組みを作るのではなく、必要な入力を既存のパイプラインに適合させることを優先します。
5. 中核となる判断ルールに従い、まとまりのある最小限の変更を選びます。互換性の仕組みは、必要なサポート対象の境界に限って追加します。
6. フィードバックによってサポート対象の動作、互換性、所有権、プロトコル経路、実装の形、テストの組み合わせが変わる場合、または複雑さのリセットが必要になった場合は、レビューの確認事項を見直します。それ以外の場合は、スコープ契約を維持して、対象を絞った修正を進めます。
7. 引き継ぎの前に、有効性チェックを実行します。回答が1つでも「いいえ」であれば、設計を見直します。

実装スコープ契約

以下の4項目を既存の計画または作業メモに記録し、実装範囲を広げたり狭めたりする前に更新します。局所的な修正であれば簡潔な1段落にまとめてもかまいません。該当しない項目は、根拠のないケースを作り出したり別のドキュメントを作成したりせず、「該当なし」と記します。

1. 必須の動作： 動作する必要がある、ユーザーに見える最小限のシナリオ。
2. 互換性の要件： 引き続き利用可能である必要がある、サポート対象のリリース済み動作または永続的な境界。
3. 意図的にサポートしないケース： 拒否する周辺の入力や形式、および拒否のタイミングと方法。
4. サポート対象の代替手段： 既存のラッパー、オーバーライド、アダプター、設定、または下位レベル API。存在しない場合は none と記します。

意図的にサポートしないケースを明確に記述できない場合は、汎用リゾルバーの追加から始めないでください。まず、より限定的な動作契約を定めます。適切なサポート対象の代替手段がない場合は、タスクで必要なときに限り追加します。推測で作り出してはいけません。

リリース済みバージョンで再現できることが証明するのは、その動作に到達可能であることだけであり、サポート対象であることではありません。その形式がパブリックドキュメント、サンプル、テスト、または型定義で意図的に網羅されている場合、永続的な境界で必要とされる場合、あるいはユーザーの具体的な利用実績やメンテナーの意図に裏付けられている場合に限り、厳密にその形式を互換性要件として扱います。それ以外の場合はリスクを記録し、既存のサポート対象の代替手段を使って早期に拒否することを優先します。

レビュー・フィードバックのゲート

フィードバックによってスコープの契約や実装の形が変わる場合は、このチェックポイントを使用してください。変更のないエビデンスは再構築せず、そのまま再利用してください。

Review checkpoint:
- Root cause and required behavior:
- Compatibility evidence and unsupported cases:
- Source of truth:
- Behavior-space change: narrows / unchanged / widens
- Action: focused patch / complexity reset / reject as unsupported

各指摘を、必須動作の不具合、サポート対象の互換性要件、同じ実装上の次元の別の組み合わせ、または無関係な問題に分類してください。動作の範囲を広げるには、新たな契約のエビデンスが必要です。

関連する2つ目の指摘によって、同じ抽象化に別の条件、プロトコルの段階、互換性ケース、またはテストの組み合わせが追加される場合は、パッチの追加をやめ、複雑さのリセットを実行してください。具体的なエビデンスによって、そのケースが必須またはサポート対象の契約に含まれると確認できた場合にのみ、作業を続けてください。

リセット後に仕様が確定したら、その後の指摘をそれぞれ、その仕様への違反、仕様を改訂する根拠となるエビデンス、意図的にサポートしていないケース、または無関係な問題に分類してください。新たな指摘を局所的に修正できるというだけで、段階的なパッチ適用を再開しないでください。

例：複数の指摘によって、直接のラッパー、ネストされたラッパー、ジェネリックアダプター、モジュール間連携の境界、バインドされたメソッドを順にたどる必要が生じた場合、別の段階を追加しないでください。任意のラッパーグラフがサポート対象でない限り、必須のプレーンな呼び出し可能オブジェクトの動作を維持し、呼び出し前に曖昧なラッパーを拒否してください。

基本的な判断ルール

• リリース済みのパブリック API、文書化された動作、サポート対象の永続的な境界を維持するか、明示的な移行手段を用意してください。
• ブランチ固有のインターフェース、内部ヘルパー、同じブランチのテスト、リリース後に追加された要素は、すでにサポート対象の永続的な境界を定義している場合を除き、main で直接書き換えてください。
• 中間のスナップショットを意図的にサポートしない場合は、未リリースの永続化スキーマのバージョンを振り直すか、次のスキーマに統合できます。その場合、サポート対象のセットとテストを一緒に更新してください。
• 広範な構造型、オーバーロード、ジェネリック、JavaScript のリフレクション機能、モジュール境界、サードパーティのインターフェースが、表現可能なすべての形をサポートしているとみなさないでください。
• スキーマ、ドキュメント、検証、識別情報、パッケージのエクスポート、変換、呼び出しには、既存のパイプラインのうち最も近いものと、単一の信頼できる情報源を優先してください。
• インターフェースとは、呼び出し側が動作を正しく利用するために把握しなければならないすべての事項を指します。該当する場合は、順序、エラー、ライフサイクル、設定、パフォーマンス上の制約も含みます。シグネチャだけで規模を判断しないでください。
• 新たな抽象化を維持する前に、削除テストを行ってください。削除すると必須の複雑さが呼び出し側に分散する場合は維持し、複雑さそのものが解消される場合は削除してください。
• 置き換え可能な境界は、変動、所有権、またはテスト可能性が実証されている場合にのみ追加してください。既存のパイプラインがすでに安定した境界を提供しているなら、仮定上のアダプターやテスト専用の間接層だけでは追加する理由になりません。
• 抽象化、状態、分類、分岐、設定、依存関係、並行する経路は、明示された要件、サポート対象の契約、または検証済みのリスクがある場合にのみ追加してください。
• 未リリースのコードでは、削除または直接置き換えることを優先してください。ブランチ固有の実装とテストは破棄可能なものとして扱ってください。
• インターフェースを部分的にエミュレートするよりも、構築時または検証時に実行可能なエラーを出し、既存の代替手段を示すことを優先してください。
• 無関係なリファクタリングや既存の失敗をパッチに含めないでください。
• 必須の動作、最も近いサポート対象の経路、サポート対象外のカテゴリごとに代表的なケースを1つテストしてください。構築可能な組み合わせをすべてテストする必要はありません。
• サポート対象のリリース済み動作や永続的な形式に変更がある場合は、計画、変更履歴、引き継ぎで明示してください。

複雑さのリセット

次のような場合は、現在の設計の拡張を止めてください。

• ラッパー、オーバーロード、ユニオンのメンバー、ジェネリクス、バインディング、コンテキストの注入、同期／非同期やストリーミングの分類、ランタイムのターゲット、プロバイダーのバリエーションなど、同じ次元を組み合わせた関連する指摘が続く場合。
• パッチが TypeScript、JavaScript のリフレクション、モジュール解決、またはサードパーティーのインターフェースを解釈している場合、あるいは互いにずれが生じうる表現を別々に推論している場合。
• 狭い要件への対応に、再帰的な解決、キャッシュされたモード、新しい状態、または無関係なパッケージやランタイムアダプターの変更が必要な場合。
• テストが仕組みを網羅している場合、または必要なシナリオは小さいままなのに差分全体が拡大し続けている場合。

次のことを行ってください。

1. 編集を止め、コメントに一つずつ対応するのではなく、分析のために現在のリビジョンを固定します。
2. 指摘を根本原因ごとにまとめ、元の要件、スコープの契約、サポート対象のリリース境界または長期的な境界を読み直します。
3. それらの入力を使って、指摘から導いたリセット仕様の候補を作成します。蓄積されたレビューの説明、ブランチ固有の仕組み、同じブランチのテストを要件として扱わないでください。
4. 候補仕様を、影響を受けるすべてのエントリーポイントと、最も近い既存のサポート対象パスに照らして監査します。必要に応じて修正し、編集を再開する前に固定します。
5. 完全な差分を、意図したマージベースまたは最新のリリースタグと比較し、各抽象化、分岐、テストを固定した仕様に対して retain、replace、delete のいずれかに分類します。
6. 対応付けのない仕組みを削除し、契約の範囲を絞り、副作用が発生する前にサポート対象外のケースを拒否します。
7. 必須の動作、サポート対象の互換性、エントリーポイント間の一貫性、代表的なサポート対象外のカテゴリを中心にテストを再構築します。
8. 以降の指摘は固定した仕様に照らして評価します。仕様を変更したり動作範囲を広げたりする前に、新たな契約上の根拠を記録して作業を止めます。

計画または作業メモでは、次の簡潔なリセット仕様を使用してください。

Finding-derived reset spec:
- Original required outcome:
- Supported release or durable boundaries:
- Grouped findings and common root cause:
- Invariants across affected entry points:
- Allowed states and behavior:
- Rejected states, failure timing, and side-effect boundary:
- Trusted and untrusted boundaries:
- Single sources of truth:
- Persistence, resume, cleanup, or other lifecycle semantics:
- Non-goals and supported alternatives:
- Representative test categories:
- Diff reset: retain / replace / delete:

候補仕様は反証可能な設計仮説であり、現在の実装の記録ではありません。監査では、固定する前に仕様を修正できます。固定した後は、仕様を修正する際に明示的な根拠を求め、修正後に差分全体の対応付けを再実行してください。

すでに兆候が見られる場合は、ユーザーやレビュー担当者からこのリセットを求められるまで待たないでください。

SDK 固有の判断ルール

• リリース済みパッケージのエクスポートマップ、ESM／CJS のエントリーポイント、公開型シグネチャ、RunState、セッションの永続化、サンドボックスの状態、文書化されたモデル／プロバイダーの設定は、プロセス、ランタイム、マシンをまたいでサポートされる場合、互換性に関わるものとして扱います。
• 永続化または再開された状態は、信頼できない入力として扱います。RunState、サンドボックスのセッション状態、プロバイダーのスナップショット状態、シリアル化されたセッションデータによって、baseUrl、認証情報、secretRefs、launchParameters、environment、userParameters、マニフェストのルート、プロバイダーのブループリントなど、信頼されたランタイム設定が上書きされないようにします。
• リクエストがサーバー側で受理されていないと安全に判断できる場合に限り、再試行または再送します。WebSocket のタイムアウト、MCP の再接続、Realtime の response.create、ホスト型ツールの呼び出し、サンドボックス操作は、サーバーがリクエストを受信した可能性がある状況で再送すると、モデルやツールの副作用が重複する場合があります。
• OpenAI API の各サーフェス間で、情報が失われる変換は避けます。Responses のアイテム、Chat Completions のメッセージ、Realtime のツール、圧縮出力、SDK のプロトコルアイテムでは、サポートされるデータを保持するか、厳格な処理経路では、サポート対象外のコンテンツ、ID、メタデータを黙って破棄せず、速やかにエラーにします。
• ポリシー判断は、主要な実行ループだけでなく、すべての入力経路に適用します。ストリーミングと非ストリーミングの実行、セッションコールバック、ローカルセッション、OpenAI Conversations セッション、圧縮セッション、RunState の再開、公開履歴の再生において、reasoningItemIdPolicy、承認ポリシー、厳格な検証、モデルのデフォルト値などの設定を確認します。
• 破壊的なストレージ更新の前に、置換データを正規化して検証します。圧縮、セッションの置換、復元の各経路では、新しいペイロードへの変換が正常に完了してから、永続化された履歴を消去または置換します。また、部分的な消去に失敗した場合は、アイテムを重複させることなく元のスナップショットを復元します。
• undefined に意味がある場合は、API のデフォルト値を維持します。API 契約で求められていない限り、省略された OpenAI またはプロバイダーの設定を、具体的な SDK のデフォルト値に正規化しないでください。これは特に、承認ポリシー、ライフサイクルのデフォルト値、モデル設定、プロバイダーオプションで重要です。
• プロバイダーの動作は、信頼できる一次情報源と照合し、可能であれば小規模な実環境での確認も行います。プロバイダーのドキュメント、生成された SDK 型、稼働中のバックエンドの間で、フィールド名、タイムアウトの単位、認証情報の更新動作、ライフサイクルのセマンティクスが一致しない場合があります。

有効性の確認

設計の完了を宣言する前に、以下のすべてに具体的な根拠を示して回答してください。

• 必要な動作を、内部ヘルパー型やリフレクションの仕組みに触れずに説明できますか？
• 並行する解釈を維持するのではなく、最も近い既存のパイプラインを実装で再利用していますか？
• 新しい抽象化や分岐は、すべてスコープの契約または検証済みのリスクに対応していますか？
• 新しい抽象化を削除した場合、必要な複雑さが複数の呼び出し元に移るだけですか？また、新しい境界はそれぞれ、実証された差異、責任の所在、またはテスト容易性に対応していますか？
• サポート対象外の隣接ケースは、副作用が生じる前に拒否され、既存の代替手段が示されていますか？
• テストでは、必要な動作を再現できる、安定性が最も高い呼び出し元の境界を使用し、実装ロジックに依存しない期待値を検証していますか？
• 完全な差分とテストで契約の範囲を網羅しつつ、構築可能なあらゆる組み合わせをサポート対象にしていませんか？
• 最新のレビュー修正によって、根拠なく動作範囲を広げることなく、縮小または維持していますか？
• 複雑さをリセットした場合、保持したすべての抽象化、分岐、テストが、凍結したリセット仕様に対応していますか？また、その後に見つかった指摘は、その仕様に照らして分類されていますか？

停止して確認するタイミング

• 変更によって、最新のリリースタグで提供されているサポート対象の動作が変わる場合、またはリリース時に偶然受け入れられた動作に実質的な依存があることを示す具体的な証拠がある場合。
• 変更によって、永続的な外部データ、プロトコル形式、またはシリアル化された状態が変わる場合。
• 正しい解決策が依頼された結果を実質的に超える範囲に及ぶ場合、または無関係なアーキテクチャ作業が必要な場合。
• 複雑さのリセット条件が発生し、より限定的な代替案によって、ブランチ内のコードではなく、すでにリリース済みのサポート対象の契約が変わる場合。
• ユーザーが後方互換性、非推奨化、または移行サポートを明示的に求めている場合。

出力に関する期待事項

このスキルが実装方針に実質的な影響を与える場合は、判断を推論または引き継ぎの中で簡潔に示してください。例：

• 互換性の境界：最新リリースタグ v0.x.y。ブランチ内のインターフェースを書き換えるため、シムは不要です。
• 実装範囲の契約：X をサポートし、Y を維持し、副作用が発生する前に Z を拒否します。サポートされている代替手段 W を使用します。代替手段がない場合は、その旨を示します。
• 複雑さのリセット：エッジケースの組み合わせが繰り返し発生し、方針の範囲が広すぎることが分かりました。分岐をさらに追加するのではなく、元の要件に立ち返って設計し直してください。
• 調査結果に基づくリセット仕様：調査結果 F1～F3 により、エントリーポイント A～C 全体にわたる不変条件 X が明らかになりました。その契約を確定し、対応付けられない仕組みを削除したうえで、後続の調査結果を照らし合わせてください。