はじめに
こんにちは、SREチームのTakahashiです。この記事はコインチェック株式会社（以下、コインチェック）のアドベントカレンダー15日目の記事です。 コインチェック - Qiita Advent Calendar 2025 - Qiita
SREチームでは、インフラの定期メンテナンスや構成変更の検証など、手順が定型化されているものの手間のかかる運用業務が多く存在します。これらの業務は、正確性と証跡の記録が求められる一方で、繰り返し実行されるため自動化の候補となります。
しかし、完全な自動化は環境の複雑性やリスクの観点から難しい場合があります。そこで私たちは、AI Agentを活用した「半自動化」というアプローチを採用しました。Agentが実行可能なコマンドを含む詳細な手順書を用意し、Agentに作業を任せながら、人間がレビューと承認を行う仕組みです。
本記事では、SREチームで実践している「Agent駆動の運用業務」の設計思想と工夫、そして得られた効果について紹介します。
前提：本記事で扱う「AI Agent」とは
本記事では、大規模言語モデル（LLM）をベースとした開発支援ツールを「Agent」と呼んでいます。具体的には：
- Cursor Agent: Claude等のLLMを統合したエディタですが、Agent 機能を使うと自律的に作業をおこなってくれる
- Claude Code: Anthropic社が提供する Terminal 上で自律的に動く、AIコーディング支援ツール
これらのツールは、Markdown形式で記述された手順書（AGENTS.md）を読み込み、以下のフローで作業を進めます：
- 手順書の理解: Agentが手順書の内容を解析
- コマンドの提案: 実行すべきコマンドを生成・提案
- 人間による承認: エンジニアが提案内容を確認・承認
- 実行と記録: 承認されたコマンドを実行し、結果を記録
現時点では「完全自動」ではなく、人間が最終判断を行う「半自動」のアプローチです。将来的には、安全性を担保しながらPR作成まで完全自動化することを目指しています。
なぜAgent向け手順書が必要なのか
従来の手順書の課題
これまでの手順書は、主に「人間が読むこと」を前提に書かれていました：
- 手順の概要や背景説明が中心
- コマンド例はあるものの、環境に応じた調整が必要
- 暗黙の前提知識（環境変数、認証情報など）が多い
- トラブルシューティング情報が散在している
これらの手順書は経験豊富なエンジニアにとっては有用ですが、以下の問題がありました：
- 実行までの準備に時間がかかる：コマンドのカスタマイズ、環境設定の確認など
- エラー時の対応に時間がかかる：どこに情報があるか探す必要がある
- 属人化のリスク：特定の人だけが効率よく実行できる
Agentを活用した半自動化のメリット
AI Agentに作業を任せることで、以下のメリットが得られます： - 実行速度の向上：コマンドをそのまま実行できるため、準備時間が短縮される - ミスの削減：手順書通りに正確に実行される - 証跡の自動記録：実行したコマンドと結果が自動的に記録される - 知識の民主化：ベテランの知見がAgentを通じて共有される
一方で、以下は人間が担保します：
- 最終判断：変更の承認、PRのマージ
- 例外対応：想定外の状況への対応
- レビュー：Agentが作成したPRの内容確認
Agent向け手順書の設計思想
1. すぐに実行可能なコマンドを記載する
ポイント：Agentがコピー&ペーストで実行できるコマンドを提供します。
工夫：
- 環境変数のプレースホルダーを明示（{ENV}, {INSTANCE_ID}など）
- 必要なオプション（--no-cli-pagerなど）を事前に含める
- コマンドの実行結果の確認方法も合わせて記載
例：
### よく使うコマンド ```bash # パッケージのバージョン確認 rpm -qa | grep <package-name> # サービスの状態確認 systemctl status <service-name> # ログの確認（最新50行） tail -50 /var/log/<service>/<logfile> ```
このように、具体的で実行可能なコマンドを豊富に用意することで、Agentは適切なコマンドを提案しやすくなります。
2. つまづきポイントを事前に記載する
ポイント：よくあるエラーとその対処法を、発生する前に手順書に記載します。
工夫： - 「よくあるエラーと対処法」セクションを設ける - エラーメッセージと原因・対処法を対応付ける - OS/環境ごとの違いを明示する
例：
### トラブルシューティング #### エラー: "Failed build dependencies: <package> is needed" **原因**: 必要な依存パッケージがインストールされていない **対処**: 1. パッケージが利用可能か確認 2. 利用不可能な場合は、設定ファイルから削除するか、先にインストール #### エラー: "CommandIdが取得できない" **原因**: サービスエージェントが起動していない、または権限がない **対処**: ```bash # 接続状態を確認 aws ssm describe-instance-information \ --filters "Key=InstanceIds,Values={INSTANCE_ID}" ```
これにより、Agentはエラーに遭遇した際も、手順書から適切な対処法を見つけて提案できます。
3. OSや環境ごとの違いを明確にする
ポイント：環境依存の差分を明示的に文書化します。
工夫： - テーブル形式で比較を提示 - 環境ごとに異なるコマンドを並記 - テンプレートファイルを環境別に用意
例：
### Amazon Linux 2 vs 2023 の主な違い | 項目 | Amazon Linux 2 | Amazon Linux 2023 | |------|---------------|-------------------| | パッケージマネージャー | `yum` | `dnf` | | テンプレートファイル | `template-al2.md` | `template-al2023.md` |
このように環境の違いを明示することで、Agentは適切なコマンドを提案できます。
4. 検証結果を証跡として記録する
ポイント：実行したコマンドと結果を構造化して記録します。
工夫： - テスト結果のテンプレートを提供 - CommandIDやタイムスタンプの記録を必須化 - サマリテーブルで全体を俯瞰できる形式
例：
### テスト結果サマリ | Test # | テスト項目 | CommandId | Status | 結果 | 備考 | |--------|-----------|-----------|--------|------|------| | 1 | サービス状態確認 | cmd-xxxxx | Success | ✅ OK | 正常稼働中 | | 2 | バージョン確認 | cmd-yyyyy | Success | ✅ OK | 更新済み | ### 詳細ログ #### Test 1: サービス状態確認 実行日時: YYYY-MM-DD HH:MM:SS CommandId: cmd-xxxxx 実行結果: [実際のコマンド出力をそのまま記載] 備考: [特記事項]
この記録は、PRのdescriptionやドキュメントシステムに添付され、レビュアーが容易に確認できます。
5. ゴールをPR作成に設定する
ポイント：Agentの作業のゴールを「PRの作成」と明確に定義します。
工夫： - 手順書の最終ステップに「PR作成」を記載 - PRのタイトル・本文のテンプレートを提供 - 必要な検証項目のチェックリストを含める
例：
## Pull Request の作成 ### PRタイトル ``` feat: update <component> to version <version> ``` ### PRの本文テンプレート ```markdown ## 概要 - <変更内容の概要> ## 変更内容 - <詳細な変更リスト> ## 検証結果 - [x] ローカルビルド成功 - [x] テスト環境での動作確認完了 - [x] 検証結果をドキュメントに記録 ## 参考資料 - 検証結果ドキュメント: <URL> ```
PRには検証結果の証跡が含まれるため、レビュアーは変更内容と動作確認の両方を確認できます。
実践例：3つのユースケース
私たちのチームでは、以下のような運用業務でAgent駆動のアプローチを実践しています。
ユースケース1: EC2 instance の Base image の定期更新
私たちのチームでは、AWS EC2インスタンスのベースとなるAMI（Amazon Machine Image）を四半期ごとに最新版へ更新しています。Amazon Linuxの新しいバージョンがリリースされると、セキュリティパッチや機能改善を取り込むためにベースイメージを更新する必要があります。
この作業は定型的ですが、最新AMI IDの確認、複数の設定ファイルの更新、ビルドテストの実施、PR作成と一連の流れがあり、手作業だと30分〜1時間程度かかっていました。
Agent向け手順書の構成： 1. 最新バージョンの確認方法 2. 設定ファイルの更新手順（具体的なファイルパスとコマンド） 3. ビルドによる検証 4. PR作成とレビュー依頼
効果： Agentに作業を任せることで、エンジニアは最新AMI IDを調べてAgentに伝えるだけで、残りの作業はAgentが自律的に進めてくれます。作業時間は大幅に短縮され、手順の属人性も解消されました。
ユースケース2: ミドルウェア設定変更の動作検証
Chef Cookbookのバージョン更新や設定変更のPRを出した際、その変更が実際のEC2環境で意図通りに動作するかを検証する必要があります。検証では、AWS Systems Manager Run Commandを使ってリモートでコマンドを実行し、パッケージのバージョン確認やサービスの稼働状態をチェックします。
Agent活用ポイント： Run Commandの実行から結果取得までは、「CommandIDの管理」や「完了待ち（ポーリング）」が必要で、人間が手動でやると煩雑です。 Agentに以下のフローを任せることで、スムーズな検証を実現しています：
aws ssm send-commandで検証コマンドを発行- 発行された
CommandIdを保持 aws ssm get-command-invocationで結果が返るまで待機- 取得したログ（StandardOutputContent）を整形して記録
Agent向け手順書の構成： 1. PR内容の確認（差分の読み取り） 2. 対象環境の選択（OS別のテンプレート利用） 3. 検証コマンドのテンプレート集（約30項目） 4. OS/環境別のトラブルシューティング 5. 検証結果の記録テンプレート 6. ドキュメントシステムへの記録手順
工夫： PRでCookbookが更新されている場合、そのCookbookが管理するパッケージやサービスのバージョンが実際に更新されているかを必ず確認する必要があります。そこで「検証の十分性チェックリスト」を手順書に組み込み、Agentに「PRの変更内容を網羅しているか？」「影響範囲を考慮しているか？」「リグレッションが発生していないか？」を確認させています。不足項目があればエンジニアに確認を促すようにしています。
効果： 検証の抜け漏れが大幅に減少し、検証結果の記録品質も向上しました。レビュアーは証跡が明確なため、PRのレビューに集中できるようになりました。
ユースケース3: RPM パッケージのビルドと管理
私たちの環境では、Fedoraベースのパッケージを取得してAmazon Linux向けに修正・ビルドすることがあります。例えば、SuricataやClamAVといったセキュリティツールは、Amazon Linuxの標準リポジトリに存在しないため、自前でビルドする必要があります。
この作業は、依存関係の解決が特に厄介です。例えばSuricataはhiredis-develを必要としますが、Amazon Linux 2の標準リポジトリには存在しません。そのため、まずhiredisをビルドしてからSuricataをビルドする「2段階ビルド」が必要になります。
Agent向け手順書の構成： 1. パッケージの検索と取得方法 2. 環境別の設定ファイル調整パターン 3. 依存関係の確認と解決手順 4. Docker環境でのビルドテストコマンド 5. よくあるビルドエラーと対処法（10パターン以上）
工夫： 手順書には、依存関係の解決手順を具体的に明記しています。「どのパッケージを先にビルドすべきか」「Amazon Linuxに存在しないBuildRequiresはどう処理すべきか」といったノウハウを事前に記載することで、Agentはビルドエラーに遭遇しても適切に対処できます。また、プラットフォーム警告など「無視してよいエラー」も明記し、不要な中断を防いでいます。
効果： 初めてのパッケージ追加でも、Agentが自律的に作業を完了できるようになりました。ベテランしか知らなかった「暗黙のビルドノウハウ」が手順書に明文化され、チーム全体で共有されています。
効果測定と学び
得られた効果
定量的効果： - 作業時間が約3倍高速化 - 手順ミスによるエラーが大幅に減少 - 証跡の記録率がほぼ100%に向上
定性的効果： - ベテランの暗黙知が手順書に明文化され、新メンバーでも高品質な作業が可能に - レビュアーは「手順の正しさ」ではなく「変更の妥当性」に集中できる - 繰り返し作業の精神的負担が減少し、クリエイティブな業務に集中できる
学んだこと
1. 手順書の保守コストは高いが、投資対効果は十分
初期作成コストは従来の2〜3倍かかりますが、繰り返し実行される業務では投資価値が高いです。Agentのエラーログをフィードバックする仕組みを作り、使えば使うほど改善されるサイクルを回しています。
2. 完璧を目指さず、使いながら改善する
基本的な流れを記載し、実際にAgentに実行させながら改善していくアプローチが有効です。
3. Agentに任せる範囲を見極める
セキュリティ影響のある変更や顧客影響の大きい作業は人間が判断し、定型的な確認作業や証跡記録はAgentに任せます。
4. 失敗から学ぶ
Agentの失敗を手順書にフィードバックすることで、同じ失敗を繰り返さない仕組みを作っています。
セキュリティとコンプライアンスの考慮事項
金融系企業のSREとして、Agent活用においても厳格なセキュリティ対策が必要です。
認証情報の管理
原則: 手順書には認証情報を一切含めない
- AWS認証:
aws-vaultを使用し、手順書にはプロファイル名のみ記載 - 環境変数: プレースホルダー（
{ENV},{INSTANCE_ID}など）を使用 - APIキー: 環境変数またはシークレット管理サービスから取得
# ❌ 悪い例：認証情報を直接記載
aws s3 ls --profile AKIAIOSFODNN7EXAMPLE
# ✅ 良い例：プロファイル名のみ
aws-vault exec {ENV}-readonly -- aws s3 ls
環境別のアクセス制御
基本方針： - Staging環境: Agentによる実行を許可（書き込み可） - 本番環境: 必要最小限、読み取り専用のみ
# 本番環境へのアクセスは読み取り専用プロファイルを使用 aws-vault exec prod-readonly -- aws ec2 describe-instances --no-cli-pager
破壊的操作の防止
多層防御： 1. 手順書レベル: 破壊的コマンドは明示的に「人間が実行すべき」と記載 2. 権限レベル: Agentが使用するプロファイルには削除権限を付与しない 3. レビュープロセス: PR作成→人間がレビュー→承認後にマージ
監査証跡の確保
Agentが実行したすべての操作は記録され、監査可能な状態を維持します：CommandID、タイムスタンプ、実行結果を記録し、PRのdescriptionやドキュメントシステムに添付します。
Agent活用が向いていない業務
すべての業務がAgent駆動に適しているわけではありません。以下のような業務は人間が直接実行した方が効率的です：
- 複数リポジトリ・環境を横断する業務: 複数の環境を行き来する作業は煩雑になる
- 大幅な待ち時間が発生する業務: AMIビルドなど、待ち時間が長い作業はセッションがタイムアウトする可能性
- 高度な判断が必要な業務: インシデント対応やトラブルシューティングなど、臨機応変な判断が必要な作業
- 顧客影響の大きい業務: 本番環境への変更など、リスクの高い操作は人間が慎重に実行すべき
Agent活用の判断基準: 手順が明確、実行結果が予測可能、失敗時のリカバリーが容易、顧客影響が限定的
Agent駆動のSRE運用の未来
次のステップ
現在、私たちは以下の取り組みを進めています：
- 手順書の標準化: テンプレート整備とチーム全体での記述ルール統一（各業務の担当者が分散管理）
- 検証の自動化: Agent実行結果の自動チェックと異常検知
- ナレッジベース化: 過去の事例やトラブルシューティングを検索可能に
Agent駆動のアプローチは、開発環境のセットアップ、インシデント対応の初動、コンプライアンスチェックなど、他の領域にも応用可能です。
まとめ
SREの運用業務にAI Agentを活用することで、以下を実現できました：
- 実行可能なコマンドを豊富に記載することで、Agentが効率的に作業を提案できる
- つまづきポイントを事前に記載することで、エラー時の対処時間を短縮できる
- ゴールをPR作成とすることで、証跡の記録とレビュープロセスが自然に組み込まれる
Agent駆動の運用は、完全な自動化とは異なります。Agentが「作業者」として動き、人間が「レビュアー・承認者」として最終判断を行う半自動化のアプローチです。
効果と課題
定型業務の実行速度が大幅に向上し、手順の属人化が解消されました。一方で、手順書の保守コストはかかり、定期的にアップデートが必要です。しかし、繰り返し実行される業務においては、投資対効果は十分に高いと実感しています。
始めるためのアドバイス
- 最も定型的で影響範囲の小さい業務から始める
- コマンド、期待結果、トラブルシューティングを手順書に明記
- Agentの失敗を手順書にフィードバック
- 成功体験を積み重ねながら段階的に拡大
完璧を目指す必要はありません。使いながら改善していくアプローチが最適です。
