# 共有ルールリポの「作り直し事故」を止める — AI に直させる前の3コマンド ## 誰向けか 複数台のPC・複数人で **AI エージェント用の共通ルール／ツール置き場**（`tools/*.mjs`、`skills/`、`docs/`、`CLAUDE.md` 等）を1つのリポジトリで共有していて、各PCにはその**コピー**が置いてあるチーム。 ## 何が起きるか（実害） 「この機能が既定で無効になっているから直して」と AI に頼むと、AI は**手元のコピーだけを読んで**「実装が無い／壊れている」と判断し、**ゼロから書き直す**。 しかし正本リポでは、**別のPCが数日前に同じ問題をすでに直してマージ済み**だった。結果: - 数十分ぶんの実装・テスト・ドキュメント修正が**まるごと無駄** - 自作版には正本にある付随改善（例: 確認ダイアログの事前抑止）が**入っておらず、正本より劣化** - そのまま PR を出していたら、**優れた既存実装を劣化版で上書き**するところだった 真因は「バグ」ではなく **ローカルのコピーが古かっただけ**。 ## 見分け方（このサインが出たら疑う） | サイン | 実際の意味 | | --- | --- | | 設定ファイルに書いた値が効かない | 読み取り側のコードが古い／その版には読む処理が無い | | ドキュメントにあるフラグが実装に無い | ドキュメントだけ新しい（未マージ PR 由来のことも） | | 「前に直したはずの挙動」が戻っている | 同期されていない | **「コードにその処理が1行も無い」は、壊れている証拠ではなく古い証拠。** ## 直す前に走らせる3コマンド `/` は正本リポ、`` は直そうとしている機能名。 ### 1. 同じ主題の PR が無いか（マージ済みも含めて全部見る） ```bash gh pr list --repo / --state all --limit 60 \ --json number,title,state,headRefName \ --jq '.[] | select(.title|test("";"i")) | "\(.number)\t\(.state)\t\(.headRefName)\t\(.title)"' ``` `--state all` が要点。`open` だけ見ると**マージ済みの解決策を見逃す**。 ### 2. 正本 main の実物と手元を突き合わせる ```bash gh api "repos///contents/?ref=main" --jq .content | base64 -d > /tmp/upstream.mjs diff /tmp/upstream.mjs <手元のパス> ``` **手元の git 履歴を見ても意味がない**（コピーは git 管理外のことが多い）。必ず**リモートの main を直接取得**して比べる。 ### 3. 正本が既に直っていたら、自作せず同期する ```bash <同期コマンド> # 例: node tools/onboarding-sync.mjs --force <フック再登録> # 例: node tools/register-hooks.mjs --hooks-only ``` 同期後に**正本のテストを走らせて**から「直った」と言う。自作コードは捨てる（正本の方が付随改善を含んでいることが多い）。 ## AI に恒久ルールとして持たせる文面 そのままルールファイルへ貼れる。 ```markdown ## 共有ルールリポを直す前に正本を確認する `<ローカルパス>` は git 管理外のコピーで、数日〜数週間古いことがある。 手元のコードだけを読んで「実装が無い／壊れている」と判断してはいけない。 共通ツール（tools/・skills/・docs/）を直す前に必ずこの順で確認する: 1. `gh pr list --state all` で同じ主題の PR（**マージ済みを含む**）を探す 2. `gh api .../contents/?ref=main` で main の実物と手元を diff する 3. 正本が既に直っていれば**自作せず同期**し、同期後に正本のテストで検証する 「設定に書いたのに効かない」「docs のフラグが実装に無い」は、 バグではなく**ローカルが古い**サインのことが多い。まず同期。 他のマシンが同じリポを先に直している前提で動くこと。 ``` ## 未マージ PR 由来のドキュメントに注意 同期しても、**未マージ PR のブランチで書いたドキュメントがローカルに残る**ことがある。そのドキュメントは正本に無いコマンドを案内するため、後日の自分や別の AI が実行して無駄に詰まる。 見つけたら、消すのではなく**冒頭に警告を足す**。 ```markdown > ⚠️ この文書は未マージの PR # 前提です。 > 正本 main に `<フラグ名>` は存在しません（走らせても何も起きない）。 > **この文書のコマンドをそのまま実行しないこと。** ``` ## 押さえどころ - `--state all`（`open` だけ見ない） - 手元の git ではなく**リモート main の実物**と比べる - 正本が直っていたら**自作しない**。同期して、正本のテストで検証する - ドキュメントと実装のズレは「未マージ PR の残骸」を疑う ---