# 外部サービスの権限設定を人に頼む前の3確認 — AI の「手順を渡したのに画面にその選択肢が無い」を潰す AI エージェントが「この画面でこう操作してください」と人に手渡すとき、**その選択肢が実在するか・その依頼がまだ必要か**を確認しないまま渡すと、人の手を止めたうえで状態を悪化させる。本書はその3確認を定型化する。 ## 想定読者外部サービス（GitHub / クラウド / SaaS）の権限・設定変更を、AI が人に手渡す運用をしている人。 --- ## 確認1: その権限の「上限」を先に調べる — 画面に出ない選択肢を書かない権限の階層はリソースの**所有者の種別**で変わる。所有者が個人アカウントか組織かで、渡せる上限が違うサービスは多い。 ### GitHub の具体例個人(User)アカウントが所有するリポジトリは、collaborator が **write 固定**。Add people のダイアログに Role の選択肢自体が出ず、API で `permission=admin` を渡しても無視される。Read / Triage / Write / Maintain / Admin を選べるのは **Organization 所有のリポだけ**。 ```bash # 所有者の種別を先に確認する（User か Organization か） gh api users/ --jq .type # → "User" … collaborator は write 固定。Admin は存在しない # → "Organization" … Role 選択が可能 ``` 名前に `-org` や `-team` が付いていても個人アカウントのことがある。**名前で判断しない。** ### 一般化 - 権限を頼む前に、そのサービスで**その権限レベルが実在する条件**を調べる - 「admin で招待して」と言われたら、admin が選べる構成かを先に確認してから返事をする - 上限に達していたら、**上限であることと回避策**（組織化・リソース移管など）を伝える。存在しない手順を渡さない ## 確認2: その依頼がまだ必要かを「当ターンで」実測する調査結果には鮮度がある。**日をまたいだ調査結果を根拠に人へ作業を頼まない。** ```bash # 例: 「APIキーが未設定だから発行して」と頼む前に、今この瞬間の状態を見る gh secret list --repo / gh run list --repo / --limit 10 --json conclusion,createdAt,event ``` 過去の調査で「未設定・失敗している」と分かっていても、その後に誰かが直している可能性がある。**相手の報告と自分の記録が食い違ったら、自分の記録のほうを疑って再照会する**（相手はたいてい現在を見ている）。特に危険なのは、相手の報告を「事実誤りです」と否定する側に回るとき。否定は強い主張なので、根拠が古いと被害が大きい。実際に「キーを再発行してください」と誤指示を出し、稼働中の自動投稿を止めかける事故が起きている。 ## 確認3: 既存の権限を剥がす指示は「剥がした先」を確認してから出す「いったん取り消して、正しい設定で入れ直してください」は、**入れ直した先に本当に目的の選択肢がある**と確認できたときだけ出す。確認せずに出すと、取り消しただけで入れ直せず、**相手の権限がゼロになる**。 ```bash # 取り消しを頼む前に、現在の状態を記録しておく（復旧の基準になる） gh api repos///collaborators --jq '.[] | {login, permissions}' gh api repos///invitations --jq '.[] | {id, invitee: .invitee.login, permissions}' ``` ## 手渡し文のテンプレート 3確認を通したら、次の形で渡す。 ``` 【開くアカウント】<アカウント名>（<別アカウント> では 404 になります）【URL】<完全なURL> 【操作】 1. … 2. …（既定値が意図と違う箇所は「未選択だと X が入るので Y を選ぶ」と明記）【成功の見分け方】<画面上でどう見えれば成功か> 【確認】結果は <検証コマンド> で当方が読み戻します ``` - **URL には必ず「どのアカウントで開くか」を併記する。** ブラウザの既定アカウントは人ごとに違い、別アカウント所有のリソースは 404 になるか、気付かず別アカウントのまま操作してしまう - **既定値が意図と違う選択肢を明示する。** 「Admin にして」では足りず「未選択だと Write が既定で入る」まで書く - **結果は API で読み戻す。** 画面のスクリーンショットでは、保留中の招待に権限が表示されないなど、判別できない状態がある ## 失敗したときの書き方手順が誤っていたと分かったら、**原因・対策・機械化**の3点を書いて恒久ルールへ入れる。 ``` 原因: <なぜ確認せずに渡したか> 対策: <次回どの確認を挟むか> 機械化: <どのルールファイル・memory・hook に入れたか> ``` 「気をつけます」で終わらせると同じ事故が再発する。確認手順をコマンドの形で残すこと。 --- ## チェックリスト - [ ] 権限の上限を所有者種別から確認した（`gh api users/ --jq .type` 等） - [ ] 依頼がまだ必要かを**今このターンで**実測した - [ ] 既存権限を剥がす指示なら、剥がした先の選択肢の実在を確認した - [ ] URL に「どのアカウントで開くか」を書いた - [ ] 既定値が意図と違う選択肢を明示した - [ ] 結果を読み戻す検証コマンドを用意した ---