付録B：プレイブック集（タスク別運用手順）

バグ修正、依存更新、テスト追加、ドキュメント整備、セキュリティ対応、MCP / tool exposure、 rollout review など、商用運用で繰り返す作業の標準手順を整理します。

Companion repo

リポジトリ: itdojp/GitHub-AgentOps-companion
利用可能な資産と対応commit: 付録A：Companion資産カタログ

この付録の導線は、付録Aで shipped と確認した資産だけを使用します。専用assetが未提供の領域は、汎用templateとpolicyを組み合わせ、存在しない固定pathを前提にしません。

共通プレイブック

すべての作業は、次の順序で進めます。

Issue を実行仕様として固定する
- 目的、非目標、受入基準、制約、検証、ロールバックを記録する
- 不明点は推測で埋めず、質問または選択肢として返す
作業を1 PR = 1意図に分割する
- 命名変更、リファクタ、機能変更、生成物更新を不用意に混ぜない
- 反復が必要な場合は、PR 本文またはコメントに判断ログを残す
Policy に沿って承認を残す
- allow は自動化してよい
- prompt は承認者・理由・期限を残す
- forbidden は例外運用にせず、別設計に切り替える
ローカル検証と CI を両方確認する
- lint / test / build / link-check / security check のうち、対象差分に必要なものを選ぶ
- CI 失敗、lint 失敗、hook 失敗は evidence として扱い、無断で無視しない
review feedback を収束させる
- Copilot review と human review の本文・inline comment・suggestion を全件確認する
- 採用しない指摘は、PR に理由を返信する
merge 後の evidence を残す
- main branch CI、公開物、Issue checklist、次 Issue を確認する

共通停止条件：

受入基準が曖昧で、正解を判断できない
secret、外部課金、production side effect が絡むが承認経路がない
CI / ruleset / required workflow を迂回しないと進められない
review thread が未解決のまま残っている

バグ修正

Issue テンプレ: .github/ISSUE_TEMPLATE/bug-report.yml
関連 Skill: skills/add-tests/SKILL.md

推奨手順：

再現条件、期待結果、実結果、影響範囲を Issue に固定する
先に最小再現または回帰テストを追加する
修正範囲を原因箇所に限定し、周辺リファクタを混ぜない
ローカルで失敗→成功を確認し、CI の同等 gate を通す
PR 本文に、原因、修正、回帰防止、ロールバックを記録する

完了 evidence：

失敗を再現したテストまたはログ
修正後の test / CI 結果
post-merge 監視観点または再発検知方法

依存更新

Issue テンプレ: .github/ISSUE_TEMPLATE/dependency-update.yml
関連 Skill: skills/dependency-update/SKILL.md

推奨手順：

更新理由を一次情報で確認する
- security advisory、release notes、deprecation、compatibility のどれかを明記する
runtime dependency、dev dependency、lockfile の差分を分けて確認する
破壊的変更、Node / Ruby / Python など runtime version、CI image の影響を見る
required checks を通し、必要なら smoke test を追加する
rollback は「前 lockfile に戻す」だけで足りるかを確認する

停止条件：

advisory の深刻度や exploitability が不明
major update だが移行手順と互換性確認がない
transitive dependency の変更量が大きく、最小 smoke test がない

テスト追加

関連 Skill: skills/add-tests/SKILL.md
custom agent 例: custom-agents/test-agent/.agent.md

推奨手順：

受入基準を正常系、異常系、境界値、権限境界へ分解する
unit / integration / e2e のうち、最も安価に失敗を検出できる粒度を選ぶ
非決定要因を固定する
- 時刻、乱数、ネットワーク、外部 API、並列実行、キャッシュ
テスト名に仕様を表し、実装詳細に依存しすぎない
フレーク兆候がある場合は、PR 本文に切り分け結果を残す

完了 evidence：

追加テストの対象仕様
ローカルまたは CI の実行結果
実行時間と PR check への影響

ドキュメント整備

Issue テンプレ: .github/ISSUE_TEMPLATE/documentation.yml
関連 Skill: skills/docs-update/SKILL.md
custom agent 例: custom-agents/doc-agent/.agent.md

推奨手順：

読者、前提知識、到達点を先に固定する
章間リンク、Companion 資産、外部一次情報を確認する
変化しやすい仕様、料金、preview 状態は日付または確認先を添える
生成 docs がある場合は source を編集し、生成物を build で更新する
link-check と公開 smoke test を行う

停止条件：

存在しない Companion ファイルへのリンクを貼る必要がある
公式仕様と本文の用語が一致しないが、どちらが現行か分からない
旧章との整合が崩れ、読者の導線が壊れる

外部リンク棚卸し / 公式情報鮮度確認

GitHub AgentOps では、Copilot、GitHub Actions、MCP、OpenAI Codex などの公式情報が短期間で変わります。リンク切れの有無だけでなく、本文が参照している plan、preview 状態、quota、課金、権限、API 名称が現在の公式情報と矛盾していないかを確認します。

推奨手順：

対象範囲を決める
- 全文棚卸し、特定章、リリース前確認、四半期レビューのどれかを Issue に明記する
- 料金、preview、quota、Actions minutes、security boundary など、変化しやすい項目を優先する
外部リンク検査を実行する
- 基本コマンドは npm run check-external-links
- DNS や社内 proxy の制限で到達できない host は、恒久対応ではなく一時的な検査除外として記録する
一次情報と本文の対応を確認する
- GitHub Docs、OpenAI Developers、公式 repository など、一次情報を優先する
- blog、community 記事、個人記事を根拠にする場合は、本文の主根拠にしない
source と生成物を同期する
- 原稿は src/ を編集し、npm run build で docs/ を更新する
- top page や README の導線を変更した場合は、公開 smoke の確認対象に含める
PR evidence を残す
- 実行日、検査コマンド、確認した代表リンク、未対応リンク、再確認が必要な項目を PR 本文に記録する

停止条件：

公式情報の現行名称や提供状態が確認できない
料金、quota、preview 状態など、誤ると読者の意思決定に影響する情報の根拠が取れない
一時的なネットワーク障害と恒久的なリンク切れを切り分けられない

完了 evidence：

npm run check-external-links の結果
参照元章と代表リンクの確認日
npm test と公開 Pages smoke の結果
次回棚卸しで再確認すべき変化しやすい項目

安全なリファクタ

関連 Skill: skills/refactor-safe/SKILL.md

推奨手順：

目的を「構造改善」「命名整理」「重複排除」など1つに限定する
先に既存テストを実行し、必要なら安全柵を追加する
振る舞い不変を受入基準として明記する
大きい移動・改名は、機能変更 PR と分離する
レビューしやすい単位で commit または PR を分ける

完了 evidence：

before / after の責務対応
テスト結果
既知の互換性影響がないこと、または移行手順

Copilot review 対応

Review prompt: .github/codex/prompts/pr-review.md

推奨手順：

Copilot review を request し、review 本文、inline comment、suggestion を全件確認する
suggestion は内容を理解してから採用する
- security、compatibility、style のいずれの指摘かを分類する
- 提案が誤っている場合は、根拠を PR に返信する
修正した comment には返信し、thread を resolve する
Copilot suggestion を採用して commit が追加された場合、または agent が branch に commit した場合は、差分を必ず読む
完了前に review completeness を確認する

停止条件：

generated comment 数と実 comment 数が一致しない
unresolved thread が残っている
Copilot 由来 commit の意図が PR 本文に反映されていない

Security fix / review assist

Issue テンプレ: .github/ISSUE_TEMPLATE/agent-task.yml
Policy: rules/command-policy.md

security専用Issue form / SkillはCompanionでは未提供です。汎用templateへthreat、secret、permission、rollbackの受入基準を追加し、専用assetが必要ならCompanion側の独立Issueで設計します。

推奨手順：

影響範囲、攻撃経路、secret exposure、外部 side effect を分類する
secret が関係する場合は、値を Issue / PR に貼らず、先に rotate と失効を行う
fork PR、pull_request_target、GITHUB_TOKEN、OIDC、artifact の扱いを確認する
修正は最小権限と監査ログを優先し、単純な権限拡大で済ませない
post-merge の再発防止を ruleset、hook、workflow、review checklist のいずれかへ反映する

停止条件：

値の漏えいが疑われるが、ローテーション権限や owner が不明
production secret や cloud credential の影響範囲を把握できない
emergency fix と恒久対策を同じ PR に混ぜるとレビューできない

MCP / tool exposure 変更

Issue テンプレ: .github/ISSUE_TEMPLATE/agent-task.yml
Scope例: custom-agents/MCP_SCOPE_EXAMPLE.md

MCP専用Issue form / review noteはCompanionでは未提供です。上記scope例を完成済みreview templateと誤認せず、導入先のtool、権限、side effect、失効条件をIssueへ具体化します。

推奨手順：

tool を read-only、mutating、external side effect に分類する
利用者、対象 repo / org、secret、rate limit、audit log を確認する
既定は deny とし、必要な tool だけ allow する
mutating tool は prompt / approval / environment gate のいずれかを設計する
導入後の失効条件、棚卸し日、owner を記録する

停止条件：

tool の副作用が分からない
secret を渡す必要があるが、保管・ローテーション・監査設計がない
organization / enterprise policy と repository 設定の優先関係が不明

GitHub Actions workflow / permission 変更

共通Policy: rules/command-policy.md

Actions permission専用noteはCompanionでは未提供です。共通command policyに加え、GitHub公式仕様と対象workflow差分を正本にします。

推奨手順：

trigger、permissions、secrets、artifact、cache、concurrency を確認する
permissions: read-all または job-level minimum から始める
pull_request_target は base branch context と PR head code の扱いを明記する
外部 API、deployment、comment write は job 単位で理由を残す
PR で workflow diff を強調し、CODEOWNERS または security reviewer を入れる

停止条件：

fork PR に write token または secret を渡す前提になっている
workflow 変更で required check / merge queue が壊れる可能性を評価していない
artifact や job summary に secret が混ざる可能性を除外できていない

Continuous AI / release prep

ワークフロー例: .github/workflows/codex-pr-review.yml（既存固定パス）
ワークフロー例: .github/workflows/codex-release-prep.yml（既存固定パス）

推奨手順：

既存 Companion では .github/workflows/codex-pr-review.yml / .github/workflows/codex-release-prep.yml を採用しています。 agentops-* などへ改名する場合は、互換期間、README の案内、本文・CHECKLIST の同期を先に決めます。

comment-only、advisory check、required check のどの段階かを決める
base / head、対象パス、実行頻度、課金 owner を固定する
出力が PR comment、job summary、artifact のどこに残るかを確認する
誤検知・過検知を測り、required check 化は段階導入する
release prep は手動実行を基本にし、未完了項目を Issue 化する

完了 evidence：

実行した workflow run
生成コメントまたは artifact の確認結果
false positive / false negative の扱い

Rollout review / metrics review

Issue テンプレ: .github/ISSUE_TEMPLATE/improvement.yml

rollout専用Issue formとscorecardはCompanionでは未提供です。指標定義を汎用改善Issueへ記録し、個人評価へ転用しません。

推奨手順：

対象チーム、対象 repo、maturity level、期間を決める
flow、quality、security、cost、adoption の minimum scorecard を選ぶ
個人評価ではなく、システム改善の観点で集計する
週次は詰まりの除去、月次は方針調整、四半期は maturity 更新に使う
次の改善は1つの Issue に落とし、owner と期限を決める

停止条件：

metric の定義がチーム間で違い、比較できない
Copilot usage dashboard と API/export の差異を説明できない
cost exception や security exception が backlog に変換されていない

プレイブック更新チェックリスト

本文の参照章と用語が一致している
Companion の固定パス候補と矛盾していない
security / cost / adoption の観点が抜けていない
Copilot review と human review の扱いが分離されている
検証結果、残リスク、次 Issue を残す欄がある