maintainer-review

メンテナーレビュー

目的

一般的なコードレビューレポートではなく、メンテナーとして判断します。次の問いを切り分けます。

1. 主張されている動作は実際に起きていますか？
2. 報告者が提案する API や修正とは独立して、どのようなユーザーの成果や制約がありますか？
3. サポート対象の機能を妥当な組み合わせや設定で使えば、その成果をすでに実現できますか？
4. ギャップが残る場合、提案された解決策は最適な設計と実装レイヤーを選んでいますか？
5. 一般のユーザーがそのギャップに遭遇する可能性はありますか？遭遇した場合、何が起こりますか？
6. 今すぐ対応するほど重要ですか？
7. この PR がまだ存在していなかった場合、メンテナーは同じ作業を開始し、実装することを選びますか？
8. PR の場合、この解決策はマージし、保守する価値がありますか？
9. 重複または古くなった操作によって共有状態が破損したり、存続する作業が所有するリソースがクリーンアップされたりする可能性はありますか？
10. 競合する PR がある場合、メンテナーはどの実装経路を一つだけ選んで進めるべきですか？
11. 曖昧なスコープやセマンティクスのうち、どれがメンテナーが決めるべき製品／API 上の判断ですか？また、コントリビューターには具体的にどの方向で実装してもらうべきですか？
12. 終了や変更依頼を明確かつ丁寧に伝えるには、どのような簡潔なメンテナー向けメッセージが適切ですか？

issue で求められているフィールド、コールバック、フラグ、クラス、実装方針は、受け入れ済みの要件ではなく、提案された仕組みとして扱います。実装方法を尋ねることから始めないでください。まず、具体的なユーザー成果がまだサポートされていないことと、提案された仕組みが利用可能な代替手段より優れていることを確認します。

現在のレビュー状態を先に示します。判断に関わる証拠が揃っていない場合は Preliminary assessment、レビューを結論づけられる場合に限り Maintainer decision を使います。差分、issue の説明、コントリビューターの労力は証拠として扱い、影響の代わりにしてはいけません。

ワークフロー

1. 対象を正確に特定する

• 主な入力として GitHub の issue または PR の URL を受け取ります。レビュー前に、所有者、リポジトリ、項目の種類、番号を特定します。
• issue の場合、報告全文、コメント、再現手順、環境、関連資料、メンテナーの回答を確認します。
• PR の場合、現在のリモートのベースとヘッド、パッチ全体、関連する場合はコミット履歴、テスト、関連 issue、レビューでの議論を調べます。レビュー対象のリモート上の変更を、現在のローカルチェックアウトで代用してはいけません。
• 主張を、反証可能な一文で示します。報告された症状と、報告者が提案する原因や修正を区別します。
• 互換性やリグレッションに関する主張が重要な場合は、リリース済みの動作範囲を特定します。
• 提案された変更が、既存の観察可能な挙動や明示的な既存テストの期待値を削除、並べ替え、または再解釈する場合、肯定的に評価する前に、その挙動を導入したコミット、blame、当初のテストを調べます。意図的にリリース済みの範囲は、それだけで恒久的な公開契約を示すものではありませんが、互換性リスクの証拠です。
• 関連する証拠が、PR の正確な実行時バリアント、プロバイダーまたはツールの種類、発生条件、ユーザーの成果に当てはまるかを確認します。一般的な issue タイトル、概念上の類似性、Related to のような表現だけでは、隣接する拡張機能の必要性を示す証拠にはなりません。報告されたシナリオがすでに修正されている場合は、追加のバリアントを、それぞれ独自の証拠を要する新たなニーズとして扱います。

リモートアクセスや変更に関するリポジトリの指示を守ります。レビューを許可されたからといって、コメントの投稿、ラベルの付与、ブランチの変更、プッシュ、その他のリモートへの書き込みが許可されるわけではありません。

2. 満たされていないニーズを特定し、提案された解決策を検証する

提案された実装を詳しく評価する前、および issue や PR を肯定的に評価する前に、この確認を完了します。

まず、Need status を一つ割り当てます。

• 実証済み：正確な対象範囲について、具体的にサポートされているシナリオ、実際の経路での再現、リリース済みの互換性要件、繰り返し寄せられている要望、または重大な影響を伴う広範な不変条件があります。
• もっともらしいが未実証：その経路が存在する可能性はありますが、現実的なプロバイダーの挙動、ユーザーへの影響範囲、発生頻度、影響、または要望が確認されていません。
• 対応済み：妥当なサポート対象のワークフローですでに目的が達成されています。
• サポート対象外：その結果は SDK の契約範囲外であり、プロバイダー、アダプター、または呼び出し元が責任を負うレイヤーに属します。

Demonstrated の必要性がある場合に限り、Merge-worthy as-is または Merge-worthy after focused changes を選択できます。Plausible but unproven の場合は、Needs evidence または Not worth completing を優先します。Already covered または Unsupported の場合は、クローズするか、該当するより簡単な代替案を優先します。

実装を比較する前に、次の4つの判断を分けて記録してください。

1. 観察の妥当性：報告された出力、状態、またはコードパスの違いが実際に存在するかどうか。
2. 下流への影響：その違いによって、具体的なユーザー、運用、互換性、または永続状態の結果がどう変わるか。
3. 必要性の状況：上記4つの証拠分類のいずれか。
4. Issue の対応：優先する、受け入れる、範囲を絞る、証拠を求める、またはクローズする。

実際に観察できる現象であっても、実証済みの必要性がなく、対応が Close となる場合があります。観察だけが確認されている場合、Issue を単に「妥当」と表現しないでください。下流への影響が示されていない場合は、提案されている意味上の契約から選択したり、競合する PR を選んだり、実装変更を起草したりしないでください。

Demonstrated と判定するには、次のいずれかの証拠経路を必須としてください。

1. 影響の観察：サポート対象のシナリオ、実際の経路での再現、または信頼できるユーザー報告によって、ユーザーに見える重大な影響、運用上の影響、互換性への影響、または永続状態への影響が示されています。
2. 重大な被害の防止：サポート対象または通常の障害経路でその状態に至る可能性があり、違反された不変条件が本質的に重大な被害を防ぎ、完全なコードパスの追跡または現実的なプローブによってその影響が確認されています。この経路では、既知のインシデントは必須ではありません。

どちらの経路でも、現実的なトリガー -> サポート対象の実行経路 -> 観察可能な影響または永続的な影響 を追跡してください。ローカルな中間状態の不整合、構築可能な分岐、重複した処理、防御的な改善、または理論上より明快な不変条件だけでは、下流への重大な影響がなければ、必要性が実証されたとはいえません。差分が小さいこと、パッチが技術的に正しいこと、またはテストのコストが低いことによって、この基準が緩和されることはありません。重大な予防対象となる影響には、セキュリティまたはプライバシーの露出、認証情報の漏えい、永続データまたは状態の破損、外部副作用の重複、復旧不能な互換性の破壊、デッドロックまたは無期限のハング、現実的に繰り返し発生し得るリソース枯渇が含まれます。

表現だけを変更する場合は、パッチ適用前後で結果が異なる具体的なコンシューマーの計算、判断、または永続化される解釈を特定し、現在の結果が誤りである理由を明らかにしてください。パッチによってリストの形、プレースホルダーの有無、メタデータ、順序、または用語だけが変わり、情報が復元されたり、コンシューマーにとって意味のある結果が変わったりしない場合、その必要性は Demonstrated ではありません。

契約が曖昧であること自体は、契約を変更すべきだという証拠にはなりません。複数の現在の形式がリリース済みであるか、意図的にテスト対象となっている場合は、別の意味上の契約を選択することを正当化する実証済みの結果がない限り、コード変更を行わないことを優先してください。より対称的である、または説明しやすいという理由だけで、特定の形式を選ばないでください。

報告によって、無害または推測的なロジックレベルの改善しか示されていない場合は、実装の改善点を求めるのではなく、Not worth completing または Close を優先してください。具体的に不足している再現情報や影響の追跡によって、実用上の影響に関する判断が現実的に変わり得る場合に限り、Needs evidence を使用してください。

1. 要求された API、クラス、ファイル、オプション、実装には触れずに、ユーザーが望む結果を言い換えてください。実際の制約と、報告者が希望する手段を分けて考えてください。
2. 現行リリースおよび対象環境で、その結果を実現するためにサポートされている最も近い方法をたどってください。未知の機能がないと決めつけず、該当するコードパス、公開 API、テスト、関連ドキュメントを調べてください。設定、合成、複製、コールバック、拡張ポイント、プロバイダーアダプター、呼び出し元が管理するレイヤーでの処理も検討してください。
3. 報告が示しているのが、機能の不足、使いやすさや見つけやすさの問題、サポート対象外のユースケース、または実証された問題がない状態のどれなのかを判断してください。より便利な書き方があるだけでは、機能不足とは限りません。
4. 提案された解決策を、最も有力な既存の方法と、少なくとも1つのより良い設計候補と比較してください。候補には、コードを変更しないこと、ドキュメントや検証を明確にすること、より限定的な修正、既存の抽象化の再利用、より一貫性のある共通境界での適用が含まれます。
5. 実行可能な各アプローチについて、具体的なシナリオを満たすか、新たにどのような公開または内部の契約を設けるか、経路間の一貫性、互換性、継続的な保守コストを比較してください。

新しいコードが機能し得ることを示すテストを、その機能が必要である証拠として扱わないでください。FakeModel の応答、手作業で構築したプロバイダー項目、モック、新しい回帰テストは、コードパスに到達できることや実装が正しいことを示せます。しかし、それだけでは、現実的なプロバイダーの挙動、ユーザーへの影響、発生頻度、実際の影響、需要、または実質的な予防効果は示せません。

API の対称性、命名の一貫性、隣接するツール、プロバイダー、出力タイプとの同等性は、設計上の論点であり、必要性の証拠ではありません。同等性を実現することで既存の複雑さを解消できる、または実証された広範な不変条件を適用できる場合には、作業を正当化できることがあります。しかし、分岐、テスト、ドキュメント、公開動作の追加には、それとは独立した実際上の根拠が必要です。

明示的な公開 Literal、列挙型、判別可能なユニオン型、または同等の静的型制約がある場合、その他の値はサポート対象の契約外であることを示す証拠として扱ってください。公開型がすでに除外している値を拒否するためだけに、クライアント側の実行時検証を重複して追加しないでください。SDK 自体が型なしデータを受け入れること、または副作用の前に速やかに失敗させることで文書化された契約や重大な不変条件を保護できること、または無効な値がサポート対象の経路で意味のある影響を引き起こすことを示す証拠を求めてください。ホスト言語で型ヒントを回避できること、敵対的な実行時オブジェクトを渡せること、構築後に属性を変更できることだけでは、恒久的な検証分岐やテストを追加する十分な理由になりません。

上流サーバーやプロバイダーがサポート対象外のリクエストをすでに拒否している場合、その境界を信頼できる判定元として扱い、クライアントで同じ受け入れルールを重複させないでください。サーバーからの拒否を待つことで、実証された重大な落とし穴や効率上の問題が生じる場合に限り、クライアントで早期に検証してください。たとえば、回避可能な課金対象の処理、繰り返し発生するネットワーク遅延やリソース消費、取り消せない副作用や状態変更、合理的な修正が難しいほど遅れて届く、または不明瞭なエラーなどです。変更され続けるプロバイダーの許容値リストや制約をコピーして、ずれが生じる恐れがある場合は、サーバー側の検証を優先してください。

合成エッジケースと極端な値のゲート

通常サポートされている生成元からは出力され得ない値や、サポート対象の使用方法では現実的な発生源がない値を作り出すことでしか必要性が示されていない課題や PR は受け入れないでください。これには、NaN や無限大などの非有限数、天文学的に大きな値、実在しない列挙型や判別共用体のメンバー、手動で破損させた型付きオブジェクト、所有する公開境界またはワイヤ境界を迂回するヘルパーの直接呼び出しが含まれます。ユニットテストでその分岐に到達できたとしても、それが証明するのは構築可能性であり、そのコードを保守する価値のある問題であることではありません。

次のいずれかを証拠が示さない限り、パッチが小さく技術的に正しい場合でも、これらの報告は原則として Close または Not worth completing としてください。

1. サポート対象のプロバイダー、パーサー、公開 API のワークフロー、または信頼できるユーザー報告により、現実的な条件下でその値が実際に生成される。
2. リリース済みの公開契約がその値の種類を意図的に受け入れており、通常の呼び出し元のコードが、その契約に違反することなく値を生成できる。
3. 攻撃者が制御する入力が実際の信頼境界を越え、現実的に悪用可能なリソース枯渇や、その他の具体的なセキュリティ境界違反を引き起こすことを示す、完全なセキュリティ上の経路がある。

「永久にスリープする可能性がある」「オーバーフローする可能性がある」「制限を無効にする可能性がある」といった主張は、その値の現実的な発生源と、結果に至るサポート対象の経路全体が証明されない限り不十分です。セキュリティというラベルだけを例外扱いしないでください。信頼境界、入力を制御できる主体、その入力が SDK に到達する経路、そして具体的に保護される対象への影響を明確にしてください。実際の信頼できないワイヤ境界から届いた不正な値であれば、経路全体が明らかな場合に修正を正当化できることがあります。一方、仮定上の悪意あるプロバイダー、モンキーパッチを適用したオブジェクト、または手動で構築したペイロードだけでは、その根拠になりません。

このゲートを通過できない場合は、実装、テスト、エラーメッセージの文言を細かく検討するためにレビューの労力を費やさないでください。該当する PR がある場合は、課題と PR の両方をクローズするよう提案し、再検討を正当化する現実の証拠が妥当な範囲で考えられる場合に限り、その具体的な証拠を述べてください。

必要性が Demonstrated でない場合、パッチは、その契約、リスク、保守コストを把握するのに必要な範囲だけ確認してください。必要性のゲートを通過した後に初めてマージを阻む問題となるため、実装上の欠陥、テスト不足、ドキュメントの不足を理由に変更を求めないでください。報告に具体的なシナリオがなく、既存の機能で十分に見える場合や、要求された仕組みが仮定上の利便性の問題しか解決しない場合は、報告者に代わって機能を設計するのではなく、Needs evidence、Close、Supersede with a simpler alternative、または Not worth completing を優先してください。

3. 競合するオープン PR を適切に洗い出す

指定された PR を詳しく評価する前に、必ず実施してください。PR の URL は比較の起点を指定するものであり、比較対象のすべてを必ずしも限定するものではありません。

• 明示的なクローズキーワード、リンクされた Issue、Issue のタイムラインまたは開発リンク、PR の本文とコメント、再現された症状から、主な Issue を特定します。関連付けが明示されておらず推定による場合は、その根拠を示します。
• Issue が明示的にリンクされている場合は、Issue のタイムライン、開発リンク、相互参照、クローズキーワード、通常の参照を通じて、その Issue に対応するすべてのオープン PR を列挙します。ドラフト PR も含め、ドラフトであることを明記します。
• Issue がリンクされていない場合は、タイトル、再現手順、破られている不変条件、実行時の経路から最も有力なシグナルを 2～3 個使って、範囲を限定した重複検索を行います。追加のクエリで信頼できる競合実装が見つかる可能性が低くなった時点で終了します。
• クローズ済みまたはマージ済みの PR は、関連する場合に履歴として利用しつつ、進行中の比較対象から除外します。
• 同じサブシステムに言及しているというだけで PR をまとめてはいけません。同じ Issue、症状、破られている不変条件、または実質的に重複する修正があることを条件とします。
• 検索方法と候補の一覧を内部で記録します。リポジトリへのアクセスだけでは網羅性を確認できない場合は、すべてのオープン PR を見つけたと断言せず、その旨を伝えます。最終報告では、無関係な検索結果を列挙しないでください。

候補が複数ある場合は、ニーズへの対応度、実行時の正確性、スコープ、実装レイヤー、テスト、互換性、複雑さ、準備状況、メンテナーに残る作業、有用な部分を組み合わせられるかどうかを比較します。最初に提出された案や差分が最小の案をデフォルトで選ぶのではなく、保守性に優れた最適な解決策を選びます。

4. デスクレビューのエビデンスフローを使用する

必ずデスクレビューから始めてください。小さな変更を些細なもの、または重要なものと判断する前に、具体的な実行時の経路を調査してください。呼び出し元、関連するヘルパー、検証レイヤー、フォールバック経路、既存のテストを確認してください。判断が変わる場合に限り、履歴やドキュメントを調べてください。テストコードの調査はデスクレビューの一部です。テスト、インポート、サンプル、再現処理、ベンチマーク、サービス呼び出しの実行は、実行時プローブです。

このスキルでは、実行時プローブの計画や実行は行いません。このスキルの呼び出し、レビューの依頼、または課題やプルリクエストの URL の提示は、テスト、インポート、サンプル、再現処理、ベンチマーク、サービス呼び出し、または別の実行時プローブ用スキルの利用を許可するものではありません。デスクレビュー後も判断に関わる実行時エビデンスが残る場合は、評価を暫定的なものとし、別途実行時調査を提案してください。未解決の問い、それが判断を変え得る理由、必要なエビデンス、適切なベース、リリース、または正常動作が確認されたコントロールを示してください。正確なコマンドを提示したり、承認を求めたり、別のスキルを呼び出したり、このスキルからコードを実行したりしないでください。

リポジトリ固有の実行時不変条件については、.agents/references/README.md から始め、影響を受ける境界に該当する参照だけを開いてください。課題や PR のレビュー中、.agents/references/ は読み取り専用として扱ってください。期待される不変条件、関連する箇所、回帰リスクの特定に使用し、そのうえでリモート変更、現在のコード、テスト、ドキュメント、リリース境界、対象を絞った実行時エビデンスに照らして、現在の主張を検証してください。レビューに伴って参照を編集したり、そこから現在の課題や PR の状態を推測したり、過去の課題や PR の結果を現在のエビデンスとして扱ったりしないでください。レビューで再利用可能な不変条件が明らかになり、それを記録すべき場合は、ユーザーが同じタスクで参照の更新を明示的に求めていない限り、別途リポジトリを保守する際に更新するよう提案してください。

以下のエビデンスの順序に従ってください。

1. 最も近い既存のサポート済み機能を追跡し、それらが根本にあるユーザーの目的をすでに満たしているか判断します。
2. 既存のテストを調査し、変更される動作のカバレッジと、以下で条件に該当する場合の相互作用の確認を含め、コードパスの追跡を完了します。コードは実行しません。
3. 実装と既存のエビデンスを、リリース済みバージョン、ベースブランチ、または正常動作が確認されたコントロールと比較します。コードは実行しません。
4. 判断に関わる実行時の不確実性が残る場合はそこで止め、以下のエビデンス要件に沿った別途の実行時調査を提案します。

デスクレビュー

静的エビデンスに基づいて結果を出してください。

必須の未充足ニーズおよび設計の確認

肯定的な評価を行う前に、ステップ 2 の確認を完了し、具体的なエビデンスに基づいて以下のすべてを説明できるようにしてください。

1. 現在サポートされている動作では実現できないユーザーの目的。
2. 最も近い既存の API または組み合わせによる実現方法と、それが不十分である正確な理由。
3. 提案された動作を、呼び出し元、アダプター、検証、ドキュメント、既存の拡張ポイントではなく、選択した抽象化レイヤーに置くべき理由。
4. 提案された恒久的な仕様が、変更を行わない場合や、最も有力なより限定的な代替案より優れている理由。
5. 新たな保守対象を正当化する、現実のシナリオ、互換性要件、または繰り返し寄せられた要望。
6. 貢献者がすでにパッチを提供していなかったとしても、メンテナーが同じ作業に取り組むことを選ぶかどうか。

答えが一つでも欠けており、それがコード自体を存在させるべきかどうかを左右し得る場合、その課題を対応可能、または PR をマージに値すると判断しないでください。真の機能ギャップと、使い方、見つけやすさ、または解決策の設計に関する問題を見分けるために必要なエビデンスだけを求めてください。これはプロダクトおよびアーキテクチャに関するエビデンスの不足であり、それだけで実行時プローブの実施理由になるものではありません。

必須の変更動作網羅性チェック

必要性ゲートを通過した後、パッチが以前は受け入れられていた入力、出力、または状態を拒否、破棄、置換、もしくは再分類する場合は、肯定的な PR 評価を行う前、または追加の実行時調査は不要と結論づける前に、このチェックを実施してください。

1. 変更された条件に一致するサポート対象のケース全体について、実際の正規化、変換、利用側の各処理経路をたどってください。報告された再現例やパッチで確認されたフィールドだけで調査を止めず、新しい条件が見落としている情報や意味を既存の処理経路で確認してください。呼び出し元が以前は何を読み取り、永続化し、再生し、または処理できたのか、そして head では代わりに何が返されるか、あるいはどのような例外が発生するかを特定してください。
2. 実質的に異なる表現や意味を持つプロバイダー、アダプター、または生成元をグループ化してください。その違いは、関連する依存関係のバージョンとサポート対象のリリース範囲に照らして検証してください。現在の上流コードだけでは、古い依存関係における動作は立証できません。共通インターフェースがあることや、あるアダプターに修正が入っていることだけでは、別のアダプターでも同じ動作が保証されるわけではありません。網羅的なプロバイダーマトリックスではなく、変更された条件の影響を受けるグループだけを調査してください。
3. 必要性を示す証拠と互換性を示す証拠は分けてください。貢献者から報告された実環境での結果、確認したテストのアサーション、権威ある仕様、独立して観測した実行時の結果を、それぞれ正確に区別して示してください。あるプロバイダーでの再現はバグの存在を示せても、新しい条件が他のサポート対象の出力形式を保持することの証明にはなりません。構築したレスポンスを使う単体テストも、そのレスポンスをどのプロバイダーが返すかの証明にはなりません。

実質的に異なるケースごとに、簡潔な作業メモを記録してください：トリガーと表現 -> base/head の結果 -> 呼び出し元への影響 -> 証拠と残る不確実性。ケースの記載漏れはレビュー作業の未完了を意味し、実行時の懸念がないことの証拠にはなりません。まず静的な処理経路の追跡を完了してください。それによってサポート対象のリグレッションが証明された場合は、実環境での再現を必須とせず、対象を絞った修正を依頼してください。具体的なプロバイダー依存の不確実性によって互換性や推奨判断が変わり得る場合は、評価を暫定的なものとし、既存のデスクレビューの範囲内で必要となる、対象を絞った実行時の証拠と対照条件を明示してください。一般的なプロバイダーの不確実性を、必須の実行時テストに変えてはなりません。

必須のインターリーブと所有権のチェック

パッチで、クリーンアップ、再試行、再接続、キャンセル、リスナー、共有フューチャーまたはタスク、接続またはストリーム、状態フラグ、あるいは可変状態を、await、コールバック、イベント、または遅延完了の前後で追加、削除、または並べ替える場合は、肯定的な PR 評価を行う前にこのチェックを実施してください。

1. 共有リソースまたは状態値をそれぞれ特定し、それらを変更し得るすべての経路を列挙します。異なる公開メソッドやラッパー、委譲経路も含めてください。リスナー、フューチャー、タスク、接続、ストリーム、ロック、キャッシュ、状態フラグ、永続化、テレメトリーも含めます。
2. 2 つ以上の重複する操作 A と B を、すべての中断点または再入点にわたって追跡します。B には、A の 2 回目の呼び出しだけでなく、最も強力で異なる変更経路を選びます。A pending -> B starts -> A fails -> B succeeds、A pending -> B starts -> B fails -> A succeeds、セットアップから完了までの間のクローズまたはキャンセル、そして新しい処理の後に古い処理が完了するケースを確認します。
3. スナップショットベースのクリーンアップまたはロールバックでは、必ず A snapshots -> A destructively mutates -> B commits newer state -> A rollback resumes の順序で追跡します。A の前の状態と B がコミットした変更が、正しい順序で保持されることを求めます。永続化された状態、キャッシュ、インデックス、フラグ、および関連する所有権状態も整合していなければなりません。
4. すべてのクリーンアップまたはロールバックについて、破棄を許可される対象の試行とリソースの世代を正確に特定します。実際の変更境界で、所有権トークン、世代、同一性チェック、比較交換、トランザクション、実証済みの直列化、または同等の不変条件を必須とします。意図された使い方から排他性を推定してはいけません。重複実行を明示的な契約またはフェイルファスト検証で制限している場合に限り、その重複を非サポートとして扱います。
5. 生存操作の不変条件について、ベースとヘッドを比較します。重複作業を、ハンドラーの欠落、共有リソースのクローズ、状態の巻き戻り、または生存タスクの失敗に置き換えることは、クリーンアップの成功ではなくリグレッションです。パッチによって別の失敗、キャンセル、または再試行の経路で新たに呼び出されるようになった古いクリーンアップを、以前から存在していた問題として片付けてはいけません。
6. 制御されたインターリーブを伴うテストを、遅延フューチャー、コールバック、またはイベントを使って調べます。リスナー数や個々の例外結果だけでなく、失敗する操作と生存する操作の観測可能な挙動、および最終的なリソースの整合性に関するアサーションを必須とします。

順次実行される再接続、再試行、失敗、クローズのテストに合格したというだけで、並行処理に関わるパッチを「そのままマージ可能」と判定してはいけません。所有権の確認が必要になったレビューは、すべての変更経路、具体的な所有権の仕組み、最も強力な異なる変更経路とのインターリーブ、および生存操作と整合性の結果を証拠として記録しない限り、完了していません。コードの追跡から安全でないインターリーブが証明された場合は、静的な証拠に基づいて結論を出し、対象を絞った修正とリグレッションテストを求めます。所有権が不明確なままなら、結果は暫定のままにし、解決に必要な具体的なランタイムの証拠を明記します。

• 到達可能なコードパスを完全に追跡した結果、主張または PR に明確な否定的結論が出る場合は、ランタイム検証を行わずにレビューを完了します。例として、実行不可能またはサポート対象外の経路、既存処理の重複、実証された無操作、直接的な互換性の破壊、明らかに不適切な抽象化などがあります。ランタイム検証を避けるためだけに、曖昧な結果を否定的と判定してはいけません。
• 初期結果が肯定的で、未解決のランタイム上の懸念がなく、変更された挙動を対象とするテスト範囲とインターリーブの確認が完了している場合、デスクレビューだけで最終的なメンテナーの判断を下せることがあります。判断を変える可能性のない証拠を言い直すためだけに、追加のランタイム調査を提案してはいけません。
• 主張の妥当性、重大度、マージ可否、必要な変更、または優先する競合 PR の判断を変え得る未解決のランタイム上の懸念がある場合は、「暫定評価（Preliminary assessment）」を報告します。未解決の疑問点、それが判断を変え得る理由、必要な証拠、適切な制御策を明記し、計画や実行はせずに、別途ランタイム調査を提案します。
• 純粋にスタイル、ドキュメント、CI の状態、またはリポジトリの準備状況に関する懸念は、ランタイム上の疑問点を覆い隠している場合を除き、ランタイム調査を提案する理由にはなりません。 判断に関係する実行時の懸念が未解決の間は、メンテナーとしての肯定的な判断を確定してはいけません。必要な実行時の証拠が得られない、または未検証のままであれば、結果は暫定的なものとし、確信度の制約を具体的に明示してください。

検証、フェイルファスト動作、クリーンアップ、再試行、中断、または並行処理に関する変更では、主な動作に加えてライフサイクルの順序も追跡してください。

• 新しいチェックまたは失敗箇所より前に取得されるリスナー、タスク、接続、ファイル、ロック、状態変更、その他のリソースを特定してください。
• 通常のティアダウンが実行される前に、構築、コンテキストマネージャーへの入場、検証、接続、または実行が例外を発生させた場合のクリーンアップを検証してください。
• 失敗によって観測可能な状態やリソースが残る可能性がある場合は、異常系テストを必須としてください。

調査に過度に時間をかけないでください。追加の証拠が妥当性、深刻度、またはメンテナーの推奨を変える可能性が低くなった時点で終了してください。

5. 妥当性と影響を適切に評価する

references/evaluation-framework.mdを使用して、主張の妥当性、現実的な到達範囲、結果、範囲、頻度、回復可能性、互換性、および深刻度を評価してください。観測された事実と推論を分け、判断を変え得る不足情報があれば明示してください。

必要性を機能ギャップ、使いやすさまたは見つけやすさのギャップ、未サポートのユースケース、または実証されたギャップなしに分類する前に、Need statusを報告してください。既存のサポート対象ワークフローですでに要求された結果が得られる場合、要求された仕組みがないことに実用上の影響を割り当てないでください。到達可能性、APIの非対称性、または技術的に成功したパッチだけから、実用上の重要性を推測しないでください。

PRの場合、Severityは根本にある問題またはユーザーのニーズのみを表すものとしてください。提案されたパッチが生み出すリスクと混同しないでください。パッチによって生じる有意なリグレッション、互換性、ライフサイクル、または保守上のリスクは、Patch riskとして別途報告してください。

AIが報告を見つけた、または作成した可能性があるという理由だけで、その報告の価値が低いと推測しないでください。作成者や動機を憶測しないでください。再現可能な動作がない、現実的でない入力である、実行不可能な呼び出し経路である、既存の処理が重複している、主張を検証できていないテストである、または修正を適用しても実行時の結果が何も変わらない、といった客観的な兆候に基づいて、報告が実態を伴うものかどうかを判断してください。

6. メンテナーの労力に見合うかを判断する

フレームワークのイシューの判定基準と PR のチェックを使って、その成果が恒久的なコード、テスト、ドキュメント、メンテナーの対応に見合うかを判断します。コードの品質とリポジトリへの取り込み準備状況は別々に分類してください。

コードに関する推奨事項を 1 つ選びます。

• 現状のままマージする価値がある：実際のニーズがあり、実装が適切で、スコープが妥当で、テストも十分です。
• 限定的な変更後にマージする価値がある：実際のニーズがあり、方向性も妥当ですが、範囲の限られた修正が必要です。
• よりシンプルな代替案で置き換える：実際のニーズはありますが、より小規模で一貫性のある修正が望ましいです。
• 完成させる価値がない：影響がごくわずか、または裏付けがない、動作に変化がない、抽象化が不適切、あるいは完成までのコストが過大です。

Need status が Demonstrated でない限り、現状のままマージする価値がある と 限定的な変更後にマージする価値がある は選べません。実装上の修正が限定的な範囲に収まるとしても、Plausible but unproven のニーズをマージに値するという推奨へ引き上げることはできません。

現状のままマージする価値がある と 限定的な変更後にマージする価値がある では、統合状況を伝えるうえで有用な場合に、リポジトリへの取り込み準備状況を 1 つ選びます。

• Ready：現在のヘッドはレビュー可能で、必須チェックはすべて成功しています。
• CI or review pending：コードに関する推奨は固まっていますが、必須の外部ゲートが未完了です。
• Rebase or conflict resolution required：ヘッドを問題なくマージできないか、大幅に古くなっています。
• Blocked：信頼できるマージ判断を妨げる具体的な外部要因またはリポジトリ上の条件があります。

よりシンプルな代替案で置き換える と 完成させる価値がない では、リポジトリへの取り込み準備状況を省略してください。CI、レビュー、マージ可能性、ブランチの新しさによって、これらの判定が変わることはありません。判断の確信度に重大な影響を及ぼす検証上の制約があれば、代わりに根拠の中で述べてください。準備状況を記載する場合は、上記 4 つのステータスから必ず 1 つだけ選び、機械的には準備完了 のような独自の表現を使わず、意味的な陳腐化に対してリベースのステータスを使わないでください。

CI が未完了という理由だけで、ほかの点では妥当なコードの推奨を格下げしないでください。意味的な競合の解消や大幅なコード変更が残っている PR を、準備完了と判断しないでください。

同じイシューに対応するオープンな PR が複数ある場合は、ポートフォリオ全体を踏まえた推奨を 1 つ提示します。最も優れた PR を選ぶ、候補の 1 つに限定的な変更を求める、具体的なアイデアを 1 つの PR にまとめる、すべての候補をよりシンプルな方法で置き換える、または重複をクローズする、といった方法があります。行ごとのレビューにならないようにしながら、推奨する方針が各代替案より優れている理由を説明してください。

提案されたパッチを、既存の最も優れた実証済みの方法と、少なくとも 1 つの代替案と必ず比較してください。代替案としては、コードを変更しない、検証またはドキュメントで対応する、より狭い範囲の修正にする、既存のヘルパーを再利用する、不変条件を一貫して適用できる別のレイヤーで対応する、といった方法があります。パッチが動作することだけを示し、現行のプロダクトでは根本的なニーズを満たせない理由と、この設計が望ましい理由を示さないレビューは不十分です。

複数の妥当な意味上のスコープ、互換性の境界、またはパブリック API の契約が残っている場合、メンテナーが決めるべき選択肢をコントリビューターに選ばせないでください。根拠、互換性の契約、プロダクトや API の設計原則に基づき、望ましいスコープを決めて具体的な変更を依頼してください。根拠が不十分で選べない場合は、レビューを暫定的なものとするか、メンテナーに判断を求めてください。実装方法の選択肢をオープンエンドのままコントリビューターに委ねないでください。

7. 調査結果とメンテナーへの対応を報告する

次の優先順位に従って評価言語を選択してください。

1. 現在の会話で明示された言語の指定に従います。
2. ~/.codex/AGENTS.md、リポジトリの AGENTS.md、またはその他の適用される指示ファイルに記載された言語の指示に従います。
3. 直近の会話が一貫して特定の言語で行われている場合は、その言語を使用します。
4. それ以外の場合は、英語を使用します。

GitHub の URL、コントリビューター、コード、ブラウザーのロケールから評価言語を推測しないでください。メンテナー向けコメントの下書きは、評価言語にかかわらず英語にしてください。報告は意思決定に役立つ簡潔なものにします。通常、根拠の箇条書きは 5 項目以内にし、意思決定に本当に必要な場合に限り項目を追加してください。

references/evaluation-framework.md の該当する簡潔な報告形式を使用してください。意思決定に関わる根拠が未確定の場合は、同ファイルの暫定評価形式を使い、最終的な推奨事項を示す代わりに、最後に根拠の限界と、必要に応じて別途ランタイム調査を提案してください。単純なケースでは回答を長くするのではなく、セクションをまとめてください。予想外または否定的なランタイムの調査結果を先に示し、候補が競合する場合は、優先する PR またはアプローチを明示してください。

PR では、コードの推奨事項より先に Need status を記載してください。Need が Demonstrated でない場合は、その結果を最初に示し、リポジトリの準備状況には触れず、パッチの修正をメンテナーの主な対応として提示しないでください。

既存の機能やよりよい代替案が意思決定に大きく影響する場合は、根拠と推奨事項の中で明示してください。具体的にサポートされている手段、その手段でできることとできないこと、そしてなぜそれが望ましいのかを示します。Not worth completing または Supersede with a simpler alternative という結論を、実装の品質への称賛の陰に隠さないでください。

クローズ、追加の根拠、コード変更を求める場合、または PR を別の対応で置き換える場合は、フレームワークで定義されている、英語でそのままコピーして使えるメンテナー向けコメントを付けてください。複数の PR に異なる対応が必要な場合は、対象となる PR ごとに下書きのラベルを付けてください。メインの対応段落にはマージを妨げる要件だけを記載し、任意のドキュメント整備や仕上げは、必須ではないことを明確にするか、省略してください。

メンテナー向けコメントの下書きを返す前に、AGENTS.md のリポジトリ全体に適用されるルールと references/evaluation-framework.md の詳細なガイダンスに従って、GitHub にそのまま貼り付けられる状態か確認してください。下書きでは、同一リポジトリ内の Issue や PR には #123 を、別リポジトリへの参照には owner/repo#123 を使います。Markdown の Issue または PR ラベル、Codex のナビゲーションリンク、ローカルファイルへのリンク、Codex 専用の引用マーカーや脚注、アプリのディレクティブは、コピー用の下書きから削除してください。GitHub の Issue やプルリクエストの構文を使わない、API ドキュメントや設計ノートなどへの通常の説明的なリンクは残してください。

また、アクション差分も確認してください。命令形の文はすべて、現在のリモートのヘッドと目標の状態との具体的な差分に対応していなければなりません。現在のヘッドですでに満たされていること、またはマージを妨げないことについて、「維持する」、ドキュメントを追加する、テストする、動作を変更する、といった要求は削除してください。Merge-worthy as-is の判定に変更要求を含めてはいけません。重複または置き換えが対象 PR への対応である場合を除き、コントリビューター向けの下書きに複数 PR の比較を含めないでください。

変更を求めるコメントでは、メンテナーが決めるべき意味上の判断を、複数の選択肢ではなく指示として述べてください。却下する選択肢に理由の中で簡潔に触れるのは問題ありませんが、依頼する対応では、採用する動作、範囲、または互換性の境界を特定してください。SDK の契約やユーザーに見える動作が変わる X と Y の選択を提示するのではなく、「なぜ必要か」を添えて「X を実装してください」と依頼してください。

依頼されない限り、行単位のレビューは行わないでください。テストに合格したことだけを理由にマージに値すると判断したり、パッチが論理的に正しいことだけを理由に実用的な価値があると判断したりしないでください。

リソース

• references/evaluation-framework.md には、重大度の基準、証拠の確認、ライフサイクルのレビュー、課題の処置、PR の品質確認、メンテナーコメントのガイダンス、レポートのバリエーションが記載されています。