# 別環境で作られた未マージPRを、現行コードへ安全に移植させる（AI向け指示書） ## これは何 「別のPC／別のメンバー／別のAIが作った未マージPR」を取り込むときの手順書。 AI にこの MD を読ませると、`cherry-pick` して競合を潰すのではなく、**移植すべき設計だけを取り出して現行コードの語彙へ統合し直す**という順序で動く。 対象は、複数の環境（PC・アカウント・エージェント）が同じリポジトリへ交互にコミットする運用。 PR が2〜3日放置されるだけで、同じファイルが本流で大きく書き換わり、**PR本文に書かれた前提が嘘になる**。 ## AI がまず理解すること（ここを飛ばすと必ず事故る） 未マージPRの危険は3層あり、**危険の小さい順に目につく**。1 だけ直して終わらせるな。 | 層 | 症状 | 本当の危険度 | | --- | --- | --- | | 1. コードが当たらない | `cherry-pick` が競合する | 低（気付ける） | | 2. **軸（語彙）が二重になる** | PR が独自の設定軸を足しており、本流にも同じ目的の軸が既にある | **最高（気付けない）** | | 3. 文書の前提が古い | PR の README/手順書が、本流で反転した既定値を古い値で説明している | 高（そのまま配ると嘘を配る） | 層2 は competing な設定軸が2本並ぶので、`axisA=旧値` かつ `axisB=新値` という**意味のない状態を作れてしまう**。 競合もテスト失敗も起こさないため、レビューを通り抜けて後から必ず壊れる。 ## 手順 ### 1. 本流側の後発変更を数える（`cherry-pick` の前に必ず） ```bash git fetch origin main git log --oneline ..origin/main -- git diff --stat origin/main -- ``` - 後発コミットが**数個以上／数百行**なら `cherry-pick` は使わない。**設計だけ採って手で移植**へ切り替える。 - 判断材料として一度だけ `cherry-pick` を試し、競合ファイル数を見て**すぐ `--abort` する**のは有効。 ### 2. 本流に既にある「軸」を先に探す PR が足そうとしている設定の**同義の軸**が本流に無いか、名前空間ごとに grep する。 ```bash git grep -n "<機能名>\|MODE\|TARGET\|--set-" -- <対象ディレクトリ> ``` - 環境変数名 / CLI フラグ / 永続化 JSON のキー名 / ログに出る語 の**4か所すべて**を見る。 - 見つかったら、**新しい選択肢は既存の軸の「3つ目の値」として入れる**。新しい軸を作らない。 - PR 側の旧表記は捨てず、**読むだけ受ける別名**にして後方互換を保つ（旧フラグを新フラグのエイリアスにする）。 すでに旧表記を書き込んでしまった環境が存在しうるため。 ### 3. 旧値の読み替えは「意味」ではなく「実害」で決める PR の旧値を新しい軸のどこへ寄せるかは、辞書的な意味ではなく**その値が引き起こした実害の記録**で決める。 - 例: 旧値 `window`（= 別ウィンドウを開く）は、文字通りには「別プロセス経路」に対応する。 だが本流は「別ウィンドウが既存の作業と衝突する」という**実害を理由に既定を反転**していた。 → 文字通りの対応先へ復活させると、記録済みの実害へ戻る。**反転後の既定側へ寄せるのが正しい。** - 判断根拠はコード内コメントや PR 本文に**日付付きで残す**（次に読む人が同じ判断を再現できるように）。 ### 4. ゲート・前提条件の適用範囲を見直す 本流には、PR が知らない**ガード**が増えていることが多い（多重起動防止、未処理状態の検出、クールダウン等）。 新しい経路に対して、そのガードが**そもそも意味を持つか**を1つずつ判定する。 - 意味を持つガード（有効/無効フラグ、無人実行の抑止、クールダウン）は**そのまま効かせる**。 - 新経路と無関係なガード（別経路の未処理状態など）は**その経路でだけ無効化**し、理由をコメントに書く。 - 併せて、新経路も**状態の記録（最終実行の経路名など）を必ず書く**。書かないと次回そのガードが誤診する。 ### 5. 文書を「現在の事実」で書き直す - PR の文書は**構成と語り口だけ活かし、事実は全部取り直す**。既定値・残る手作業・コマンド名を実物で確認する。 - 配布URLは**ブランチ参照（`/main/` 等）のままにし、コミットハッシュで固定しない**。 固定すると改修のたびに受け手へ「URLを貼り替えて」と手作業を強いる。 - 文書を配る前に、**受け手が実際に踏むURLを取得して新機能の目印を grep する**。 ```bash curl -s "<配布URL>" | grep -c "<新フラグ名>" ``` ### 6. 実装をAIに委譲するなら、受け入れ前に diff を1ハンクずつ読む **「このテストを通せ」を合格条件として渡すと、テストを通すために既存の設計判断を壊すことがある。** 実例: 「dry-run が計画を返すこと」を条件に渡したところ、実装AIは 「依存CLIが見つからない場合の早期スキップ」を dry-run の**後ろへ移動**させて条件を満たした。 その早期スキップは、本流が「依存解決の失敗に気付くための診断ログ」として意図的に置いていたもので、 テストは緑のまま**診断能力だけが消えた**。 - 受け入れレビューでは「**依頼していない挙動変更が混ざっていないか**」を専用に1周見る。 - 混ざっていたら戻す。テストが落ちるなら、テストの合格条件のほうを直す。 ### 7. 検証（ここまでやって「移植できた」と言える） - 全テストを流す（PRのテストではなく**現行リポの全体**）。 - **実プロセス・実入力での確認**を1本は必ずやる。フックなら実際の stdin を流し込む: ```bash echo '{"<イベントのJSON>"}' | node