共有ルールリポの「作り直し事故」を止める — AI に直させる前の3コマンド

誰向けか

複数台のPC・複数人で AI エージェント用の共通ルール／ツール置き場（tools/*.mjs、skills/、docs/、CLAUDE.md 等）を1つのリポジトリで共有していて、各PCにはそのコピーが置いてあるチーム。

何が起きるか（実害）

「この機能が既定で無効になっているから直して」と AI に頼むと、AI は手元のコピーだけを読んで「実装が無い／壊れている」と判断し、ゼロから書き直す。

しかし正本リポでは、別のPCが数日前に同じ問題をすでに直してマージ済みだった。結果:

• 数十分ぶんの実装・テスト・ドキュメント修正がまるごと無駄
• 自作版には正本にある付随改善（例: 確認ダイアログの事前抑止）が入っておらず、正本より劣化
• そのまま PR を出していたら、優れた既存実装を劣化版で上書きするところだった

真因は「バグ」ではなく ローカルのコピーが古かっただけ。

見分け方（このサインが出たら疑う）

サイン	実際の意味
設定ファイルに書いた値が効かない	読み取り側のコードが古い／その版には読む処理が無い
ドキュメントにあるフラグが実装に無い	ドキュメントだけ新しい（未マージ PR 由来のことも）
「前に直したはずの挙動」が戻っている	同期されていない

「コードにその処理が1行も無い」は、壊れている証拠ではなく古い証拠。

直す前に走らせる3コマンド

<OWNER>/<REPO> は正本リポ、<KEYWORD> は直そうとしている機能名。

1. 同じ主題の PR が無いか（マージ済みも含めて全部見る）

gh pr list --repo <OWNER>/<REPO> --state all --limit 60 \
  --json number,title,state,headRefName \
  --jq '.[] | select(.title|test("<KEYWORD>";"i")) | "\(.number)\t\(.state)\t\(.headRefName)\t\(.title)"'

--state all が要点。open だけ見るとマージ済みの解決策を見逃す。

2. 正本 main の実物と手元を突き合わせる

gh api "repos/<OWNER>/<REPO>/contents/<PATH>?ref=main" --jq .content | base64 -d > /tmp/upstream.mjs
diff /tmp/upstream.mjs <手元のパス>

手元の git 履歴を見ても意味がない（コピーは git 管理外のことが多い）。必ずリモートの main を直接取得して比べる。

3. 正本が既に直っていたら、自作せず同期する

<同期コマンド>   # 例: node tools/onboarding-sync.mjs --force
<フック再登録>   # 例: node tools/register-hooks.mjs --hooks-only

同期後に正本のテストを走らせてから「直った」と言う。自作コードは捨てる（正本の方が付随改善を含んでいることが多い）。

AI に恒久ルールとして持たせる文面

そのままルールファイルへ貼れる。

## 共有ルールリポを直す前に正本を確認する

`<ローカルパス>` は git 管理外のコピーで、数日〜数週間古いことがある。
手元のコードだけを読んで「実装が無い／壊れている」と判断してはいけない。

共通ツール（tools/・skills/・docs/）を直す前に必ずこの順で確認する:

1. `gh pr list --state all` で同じ主題の PR（**マージ済みを含む**）を探す
2. `gh api .../contents/<path>?ref=main` で main の実物と手元を diff する
3. 正本が既に直っていれば**自作せず同期**し、同期後に正本のテストで検証する

「設定に書いたのに効かない」「docs のフラグが実装に無い」は、
バグではなく**ローカルが古い**サインのことが多い。まず同期。
他のマシンが同じリポを先に直している前提で動くこと。

未マージ PR 由来のドキュメントに注意

同期しても、未マージ PR のブランチで書いたドキュメントがローカルに残ることがある。そのドキュメントは正本に無いコマンドを案内するため、後日の自分や別の AI が実行して無駄に詰まる。

見つけたら、消すのではなく冒頭に警告を足す。

> ⚠️ この文書は未マージの PR #<N> 前提です。
> 正本 main に `<フラグ名>` は存在しません（走らせても何も起きない）。
> **この文書のコマンドをそのまま実行しないこと。**

押さえどころ

• --state all（open だけ見ない）
• 手元の git ではなくリモート main の実物と比べる
• 正本が直っていたら自作しない。同期して、正本のテストで検証する
• ドキュメントと実装のズレは「未マージ PR の残骸」を疑う