外部サービスの権限設定を人に頼む前の3確認 — AI の「手順を渡したのに画面にその選択肢が無い」を潰す

AI エージェントが「この画面でこう操作してください」と人に手渡すとき、その選択肢が実在するか・その依頼がまだ必要かを確認しないまま渡すと、人の手を止めたうえで状態を悪化させる。本書はその3確認を定型化する。

想定読者

外部サービス（GitHub / クラウド / SaaS）の権限・設定変更を、AI が人に手渡す運用をしている人。

---

確認1: その権限の「上限」を先に調べる — 画面に出ない選択肢を書かない

権限の階層はリソースの所有者の種別で変わる。所有者が個人アカウントか組織かで、渡せる上限が違うサービスは多い。

GitHub の具体例

個人(User)アカウントが所有するリポジトリは、collaborator が write 固定。Add people のダイアログに Role の選択肢自体が出ず、API で permission=admin を渡しても無視される。Read / Triage / Write / Maintain / Admin を選べるのは Organization 所有のリポだけ。

# 所有者の種別を先に確認する（User か Organization か）
gh api users/<owner> --jq .type
# → "User"         … collaborator は write 固定。Admin は存在しない
# → "Organization" … Role 選択が可能

名前に -org や -team が付いていても個人アカウントのことがある。名前で判断しない。

一般化

• 権限を頼む前に、そのサービスでその権限レベルが実在する条件を調べる
• 「admin で招待して」と言われたら、admin が選べる構成かを先に確認してから返事をする
• 上限に達していたら、上限であることと回避策（組織化・リソース移管など）を伝える。存在しない手順を渡さない

確認2: その依頼がまだ必要かを「当ターンで」実測する

調査結果には鮮度がある。日をまたいだ調査結果を根拠に人へ作業を頼まない。

# 例: 「APIキーが未設定だから発行して」と頼む前に、今この瞬間の状態を見る
gh secret list --repo <owner>/<repo>
gh run list --repo <owner>/<repo> --limit 10 --json conclusion,createdAt,event

過去の調査で「未設定・失敗している」と分かっていても、その後に誰かが直している可能性がある。相手の報告と自分の記録が食い違ったら、自分の記録のほうを疑って再照会する（相手はたいてい現在を見ている）。

特に危険なのは、相手の報告を「事実誤りです」と否定する側に回るとき。否定は強い主張なので、根拠が古いと被害が大きい。実際に「キーを再発行してください」と誤指示を出し、稼働中の自動投稿を止めかける事故が起きている。

確認3: 既存の権限を剥がす指示は「剥がした先」を確認してから出す

「いったん取り消して、正しい設定で入れ直してください」は、入れ直した先に本当に目的の選択肢があると確認できたときだけ出す。確認せずに出すと、取り消しただけで入れ直せず、相手の権限がゼロになる。

# 取り消しを頼む前に、現在の状態を記録しておく（復旧の基準になる）
gh api repos/<owner>/<repo>/collaborators --jq '.[] | {login, permissions}'
gh api repos/<owner>/<repo>/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/<owner> --jq .type 等）
• 依頼がまだ必要かを今このターンで実測した
• 既存権限を剥がす指示なら、剥がした先の選択肢の実在を確認した
• URL に「どのアカウントで開くか」を書いた
• 既定値が意図と違う選択肢を明示した
• 結果を読み戻す検証コマンドを用意した