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. 引き継ぐ前に、有効性の確認を実施します。いずれかの回答が「いいえ」の場合は、設計を見直してください。

実装スコープ契約

既存の計画または作業メモに次の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 へのリリース後の追加は、すでにサポート対象の永続的な境界を定義している場合を除き、main 上で直接書き換えます。
• 未リリースの永続化スキーマのバージョンは、中間スナップショットを意図的にサポート対象外としている場合、番号を振り直すか統合できます。その場合は、サポート対象の集合とテストを一緒に更新します。
• Python やサードパーティーの広範なプロトコルを、表現可能なあらゆる形式のサポートと同一視しないでください。
• スキーマ、ドキュメント、検証、識別、呼び出しには、既存のパイプラインのうち最も近いものと、唯一の信頼できる情報源を優先します。
• インターフェースとは、動作を正しく使うために呼び出し側が知る必要のあるすべての事項を指します。必要に応じて、順序、エラー、ライフサイクル、設定、パフォーマンス上の制約も含まれます。シグネチャだけを見て規模を判断しないでください。
• 新しい抽象化を残す前に削除テストを行います。削除すると必須の複雑さが呼び出し側に分散するなら残し、複雑さ自体がなくなるなら削除します。
• 置き換え可能な境界は、実証された差異、所有権、またはテスト容易性がある場合に限り追加します。既存のパイプラインがすでに安定した境界を提供している場合、仮定上のアダプターを1つ用意するだけ、またはテスト専用の間接層を設けるだけでは不十分です。
• 抽象化、状態、分類、分岐、設定、依存関係、並列経路を追加するのは、明示された要件、サポート対象の契約、または検証済みのリスクがある場合に限ります。
• 未リリースのコードには、削除または直接置換を優先します。ブランチ内の実装とテストは破棄可能なものとして扱います。
• 部分的なプロトコルのエミュレーションより、構築時または検証時に実行可能なエラーを出し、既存の代替手段を示すことを優先します。
• 無関係なリファクタリングや既存の失敗をパッチに含めないでください。
• 必須の動作、最も近いサポート対象の経路、サポート対象外の各分類につき代表的なケースを1つテストし、構築可能なすべての組み合わせをテストすることは避けます。
• サポート対象のリリース済み動作や永続形式に変更がある場合は、計画と引き継ぎで明記します。

複雑さのリセット

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

• ラッパー、記述子、ジェネリクス、バインディング、コンテキスト注入、同期／非同期の分類、プロバイダーのバリエーションなど、同じ側面を組み合わせた関連する指摘が続く場合。
• パッチがホスト言語やサードパーティのプロトコルを解釈する場合、または、乖離するおそれのある表現を個別に推論する場合。
• 限定的な要件を満たすために、再帰的な解決、キャッシュされたモード、新たな状態、または無関係なサブシステムの変更が必要な場合。
• テストが仕組みを網羅するようになっている場合、または、必要なシナリオは小さいままなのに差分全体が拡大し続ける場合。

次のいずれかに該当したら：

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 固有の判断ルール

• リリース済みのRunState、セッション永続化、および明示的に永続化されるその他のシリアライズ済み状態は、コミット、プロセス、マシンをまたいだ互換性に影響するものとして扱ってください。
• サポート対象外のOpenAI APIまたはプロバイダーアダプターの挙動について、すでにリリース済みのデフォルトパスがある場合は、最新リリース時点での変更が正当化されない限り、デフォルトでハードエラーにしないでください。strict_feature_validation=Trueのようなオプトインの厳格モードを優先し、警告の表示、サポート対象外データの無視、または明らかに空ではないプレースホルダーによって、デフォルトパスの互換性を維持してください。
• OpenAI APIの機能不足を評価する際は、ストリーミングパスと非ストリーミングパスを併せて評価してください。カスタムツール呼び出し、複数選択肢のChat Completionsチャンク、テキスト以外のツール出力など、プロバイダーペイロードの違いについて、一方のパスでは厳格にし、もう一方では許容的、または不正な状態にしないでください。
• 変更によって新たなパブリックSDKの挙動を導入する場合、それをハードコードされたモジュールグローバルだけで公開しないでください。明示的なパブリック設定オブジェクトまたはパラメーターを優先し、互換性が重要な場合は既存のデフォルト挙動を維持して、オプトインのSDKデフォルトを明示してください。
• SDKが所有するパブリック設定では、内部の型付き表現を維持しつつ、パブリックな入力境界で既存の型付きオブジェクトと同等の辞書形式を受け付けてください。任意のサードパーティーのスキーマ仕様を再現するのではなく、所有元モデルの検証と追加フィールドのポリシーに従ってください。
• モデル固有の設定は既存のmodel_settingsパラメーター内に保持してください。辞書形式への対応を追加する際も、リリース済みのコンストラクター引数、型付きオブジェクトの挙動、プロバイダーリクエストのペイロードを維持してください。
• パブリックなデータクラスおよびコンストラクターに新しいオプションフィールドやパラメーターを追加する場合は、末尾に追加してください。互換性レイヤーと旧来の位置指定引数の呼び出し形式に対するリグレッションテストを用意しない限り、既存のパブリックフィールドより前に挿入しないでください。
• 実行時の挙動に影響するしきい値やクォータの値は、API設計の一部として扱ってください。OpenAIプラットフォームのクォータに由来する値と、SDKの防御的なデフォルト値を区別してください。値が文書化されたプラットフォームの制限に基づかない場合は、常時有効なデフォルトの挙動にしないでください。
• パブリック設定におけるNoneの意味は慎重に定義してください。たとえば、暗黙の真偽値チェックに頼るのではなく、「機能を無効にする、またはSDKの制限を設けない」「SDKのデフォルト制限を使用する」「この特定の制限だけを無効にする」をそれぞれ別の意味として扱ってください。

停止して確認する場合

以下の重大な判断は、ユーザーの依頼または承認済みのスコープ契約ですでに解決されていない場合に限り、確認してください。その契約の範囲内で通常の修正を行う場合は、レビューと検証を続けてください。

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

出力に関する期待事項

このスキルが実装方針に大きく影響する場合は、たとえば次のように、判断内容を推論または引き継ぎで簡潔に述べてください。

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