共有ライブラリやSDKを、公開APIを壊さずにAIに直させる

## 完了と言う前に、テストとビルドの確認をすべて回す 変更がランタイムコード、テスト、またはビルド／テストの挙動に影響する場合は、変更完了を宣言する前に必ずプロジェクトの検証スタック一式を実行する。以下を変更した場合、検証の対象となる。 - コアライブラリのコードや共有ユーティリティ - スナップショットテストを含むテスト - サンプルプロジェクト - ビルドまたはテストの設定（依存関係マニフェスト、タスクランナーのファイル、ドキュメントビルド設定、CIワークフロー） ドキュメントのみ、またはリポジトリのメタ情報のみの変更（ドキュメント、コントリビューターガイド、メタデータファイル）については、ユーザーが明示的にフル検証を求めない限り、フル検証を省略してよい。検証を行うかどうかは、変更の規模についての主観的な感覚ではなく、実際に変更したファイルに基づいて判断する。修正を適用した後は必ずスタック全体を再実行する — 部分的な再実行では、修正自体によって発生した回帰が見逃されてしまう。 外部プラットフォームのAPIと連携する際は、一般的なAPIの想定に頼るのではなく、そのプラットフォームの公式ドキュメントを参照し、あわせてライブラリ自身の挙動についてローカルのコードパスを確認する。 ## 許可なく、Gitのブランチやワークツリーを切り替えない デフォルトでは、ユーザーの現在のチェックアウト内・現在のブランチ上で作業する。タスクがすでに選択済みのワークツリー内で実行されている場合は、追加の許可を求めることなくそのワークツリーを使用する。 現在の会話でユーザーがその具体的な操作を明示的に求めるか承認しない限り、別のワークツリーを新規作成したり切り替えたりしない。また、ブランチを新規作成したり切り替えたりしない。実装・調査・レビュー・テスト・検証を行ってほしいという依頼それ自体は、アクティブなワークツリーやブランチを変更する権限を意味しない。 隔離環境や別のチェックアウトが本当に必要な場合は、その理由を説明したうえで、Gitの状態を変更する前に必ず確認を取る。これは、他のルールやワークフローがリンクされたワークツリーの使用を推奨している場合でも変わらない。自動的に選択・作成するのではなく、いったん止まって承認を求めること。 ## 公開APIの新しい引数は末尾に足し、今の呼び出しを壊さない エクスポートされたランタイムAPIのパラメータやフィールドの順序は、実装の詳細ではなく契約である。 - 既存の公開コンストラクタ引数やデータクラスのフィールドが持つ位置的な意味を保持する。既存の公開順序の途中に新しいパラメータやフィールドを挿入してはならない。 - 新しいオプションの公開フィールドやパラメータは末尾に追加し、既存のフィールドは元の順序のまま維持する。 - 順序の変更がどうしても避けられない場合は、明示的な互換レイヤーを追加し、旧来の位置引数による呼び出しパターンを検証する回帰テストも合わせて追加する。 - 呼び出し側では偶発的な破壊を減らすためにキーワード引数を優先して使うが、それを理由に位置引数の互換性を壊してよいことにはならない。 - 意図されたインポートパスや公開エクスポート一覧も契約として扱う。公開シンボルを追加または移動する際は、それを所有するモジュール、意図されたトップレベルもしくはサブパッケージの再エクスポート、そしてインポートの回帰テストを更新する。 - トップレベルのインポートは、オプション依存関係の失敗やランタイムの副作用が発生しない状態に保つ。必要に応じて遅延エクスポートを使用する。 ## 最新リリースを基準に互換性を判断し、大きい作業は計画を立てる 破壊的変更かどうかは、未リリースのブランチ内での変動ではなく、最新リリースを基準に判断する。最新リリース以降に導入・変更されたインターフェースは、それがリリース済みまたは明示的にサポートされた永続的な外部状態境界を定義するものでない限り、またユーザーが明示的に移行パスを求めない限り、互換シムなしで直接書き換えてよい。中間スナップショットが意図的にサポート対象外とされている場合、未リリースの永続化フォーマットはリリース前に番号の振り直しや統合を行ってよい。リリース後のブランチ内の変動については、互換レイヤーよりも直接的な置き換えを優先する。 互換性のリスクは早い段階で指摘する — ただし、それは変更が最新リリースで出荷済みの挙動、またはリリース済みでサポートされている永続的な状態境界に影響する場合に限る。そのうえで、実装に入る前に方針を確認する。 作業が複数ステップにわたる、複数ファイルにまたがる、新機能やリファクタリングを伴う、あるいはおよそ1時間を超えそうな場合は、実行計画を用いる。計画の中の生きたセクション（進捗、発見事項、意思決定ログ、成果）は実行しながら常に最新の状態に保ち、スコープが変わった場合は計画を書き直す。複雑なタスクに対して意図的に計画作成を省略する場合は、レビュー担当者がその判断を理解できるよう理由を書き残す。 ## サブシステムの資料を先に読み、変更が届く所をすべて直す ライブラリのランタイムは、相互に作用し合う複数のサブシステムの集合である — 実行ループ、ツール実行、モデル／プロバイダーアダプター、トレーシング、セッションと永続化、リアルタイム／音声パイプライン、サンドボックス化、そしてシリアライズされた実行状態などである。いずれかを変更する前に、そのサブシステム専用のアーキテクチャリファレンスを読み、自分が触れようとしている境界を理解していることを確認する。 システム全体に波及するバリアント — 新しいモデル出力、ツール呼び出し、承認、実行アイテムの種類など — を追加または変更する場合は、該当するすべての面を更新する。処理、イベント、リプレイ、永続化、トレーシング、シリアライゼーションである。1つでも面を見落とすと、微妙で追跡困難な不整合が発生する。 ストリーミング経路と非ストリーミング経路の挙動は一致させておく。コネクション、タスク、その他のリソースを所有するサブシステムについては、正常系・異常系の両方の経路でリソースの所有権を検証する。シリアライズされた実行状態の形式が変わる場合は、そのフォーマットについてのリリース境界・スキーマバージョン・後方互換読み込み・回帰テストに関するルールに従う。 ## ドキュメントを実際のコードに合わせ、機密データをログに残さない - ドキュメントは本番サイトに公開されることが多いため、挙動の変更とドキュメントの整合は慎重に取る。まだリリースされていない挙動をドキュメントが説明することになる場合は、そのリリースが利用可能になるまでドキュメントの変更を保留するか、フォローアップとして分離する。 - 実行可能なドキュメントのコード例は、API互換性のチェックとして扱う。コンストラクタやAPIの使用例を追加する前に、示されている引数や呼び出し形式が実際の実装と一致しているかを確認する。 - 信頼できないサンドボックスやマニフェストのデータが、ホストのファイルシステムやベースディレクトリの境界を自ら回避できるようにしてはならない。ローカルへの実体化（materialization）のための逃げ道は、呼び出し元の信頼できるアプリケーションコードが制御するものであり、シリアライズされたマニフェストデータが制御してはならない。 - セキュリティ上の権限付与や境界についてドキュメント化する際は、実際のコードパスがそれを強制しているかを確認する。ある実体化パス（ローカルディレクトリ、ローカルファイル、アーカイブ展開）が実際にその権限を参照していない限り、その権限が適用されると主張してはならない。 - 機密性の高いペイロードをマスキングする際は、トレースバックの表示、例外の連鎖、保持された例外コンテキスト、ログ、テレメトリまで考慮する。元の例外オブジェクトに機密性の高い入力がまだ含まれている場合、トレースバックを抑制するだけでは不十分である。 ## フォーマットとテストのチェックを通し、PRの引き継ぎ文を作る コードに手を加えるときは必ずテストを拡充し、提出前に該当するチェックがすべて通ることを確認する。 - テストスイート全体を実行する。反復作業中は、パターンを指定した絞り込みテストの実行を活用する。 - 静的型チェックを実行する。型ヒントは必ずパスさせる。 - スナップショットベースのテストについては、意図的にスナップショットを再生成し、その後スイートを再実行する。 - カバレッジはプロジェクトの基準値を下回らないようにする。 - フォーマッターとリンターを適用する。インポートは整列された状態を保つ。コメントはピリオドで終わる完全な文として書く。 - チェックはプロジェクトで定められた順序どおりに実行する — フォーマット、リント、型チェック、テストの順である。 プルリクエストとコミットについて: - プロジェクトのPRテンプレートを使用する。概要、テスト計画、該当する場合は関連するissueを含める。 - コミットメッセージは命令形で簡潔に書く。コミットは小さく、焦点を絞った単位に保つ。 - 新しい挙動にはテストを追加し、ユーザーに影響する変更についてはドキュメントを更新する。 - 対象となる変更については、最終回答の前にPRハンドオフブロック（概要、推奨ブランチ名、タイトル、ドラフトの説明文）を作成する。このハンドオフを作成すること自体は、ブランチの作成・コミット・プッシュ・プルリクエストのオープンを許可するものではない。些細なタスクや会話のみのタスク、挙動に影響しないメタ情報・ドキュメントのみのタスクの場合、またはユーザーが含めないよう指示した場合に限り、これを省略する。 レビュー担当者が確認するのは次の点である。チェックが通っていること、新しい挙動とエッジケースをカバーするテストがあること、読みやすく一貫性のあるコードであること、公開APIやユーザーに影響する変更がドキュメント化されていること、挙動が変わった場合にはサンプルも更新されていること、そして明快な説明を伴うクリーンな履歴であること。