😎

AIに手順書を書かせよう! 手順書作成で向き合うAIの不確実性

に公開
AI
idea

はじめに

AIに手順書を書かせてみよう! 手順書にはいくつか必要なポイントがあるね!

  • 明確な作業目的
  • 作業内容の確実性
  • 手順の網羅性
  • 影響範囲

AIはここに書かれていること、結構苦手だよね。特に作業内容の確実性を担保することは苦手なんだよね!
だから、AIに手順書を書かせるときは、AIが苦手なポイントを補うように工夫する必要があるよ!

今回は、AIに｢災害時検証: CloudSQLリージョン移行｣の手順書を書かせてみて、一緒に工夫してみよう!

手順作成

まずはそのまま

まずは、AIにそのまま手順書を書かせてみよう! 以下のプロンプトを使用してみたよ!

Cloud SQLのリージョン移行手順をmarkdownで作成してください。

## 背景

現在asia-northeast1(tokyo)リージョンで稼働しているCloud SQLがリージョン障害により利用できなくなった際、スムーズにasia-northeast2(osaka)リージョンに移行できるようにしたい。

## 前提条件

- 移行元リージョン: asia-northeast1(tokyo)
- 移行先リージョン: asia-northeast2(osaka)
- Cloud SQLの種類: Postgres 18
- データベース名: tokyo-test

AIが書いてくれた手順書は以下の通りだよ!

Gemini 3.0 Proが書いた手順書
Cloud SQL（PostgreSQL）を、リージョナル障害への備えとして東京（asia-northeast1）から大阪（asia-northeast2）へ移行・切り替えを行うための手順書です。

この手順では、**リードレプリカを利用した昇格（Promotion）方式**を前提としています。この方式は、ダウンタイムを最小限に抑え、データの整合性を保つのに最も適しています。

-----

## 1\. 事前準備（平時）

障害発生前に、あらかじめ大阪リージョンに待機系を作成しておく必要があります。

1.  **クロスリージョン・リードレプリカの作成**
      * 東京リージョンのマスターインスタンスに対し、大阪リージョンを指定してリードレプリカを作成します。
      * **スペックの同期:** 障害時に同等のパフォーマンスを維持できるよう、インスタンスタイプやディスク容量はマスターと同じ設定にすることを推奨します。

-----

## 2\. 移行・切り替え手順（障害発生時）

東京リージョンで障害が発生し、大阪リージョンへの切り替えを決定した際の手順です。

### STEP 1: アプリケーションの停止

データ不整合を防ぐため、可能であれば現在東京側のインスタンスを参照しているアプリケーションを一旦停止、または書き込みをブロックします。

### STEP 2: リードレプリカの昇格（Promotion）

大阪リージョンのリードレプリカを、独立した書き込み可能なスタンドアロンインスタンスに昇格させます。

**gcloudコマンド例:**

```bash
gcloud sql instances promote [OSAKA_REPLICA_NAME]
```

  * **注意:** 昇格処理には数分かかる場合があります。この間、インスタンスは再起動されます。

### STEP 3: 接続文字列の変更

アプリケーション側で保持しているデータベースの接続先（IPアドレス、またはCloud SQL Auth Proxyの接続名）を、新しい大阪のインスタンスのものに更新します。

  * **新接続名例:** `[PROJECT_ID]:asia-northeast2:[OSAKA_INSTANCE_NAME]`

### STEP 4: アプリケーションの再起動

設定変更後、アプリケーションを起動し、大阪リージョンのデータベースに対して正常に読み書きができることを確認します。

-----

## 3\. 移行後の管理タスク

昇格後の大阪インスタンスは「マスター」として動作するため、冗長性を再確保する必要があります。

| タスク | 内容 |
| :--- | :--- |
| **高可用性(HA)の有効化** | 昇格後のインスタンスでHA（Regional可用性）を有効にし、大阪リージョン内でのゾーン障害に備えます。 |
| **バックアップ設定** | 昇格したインスタンスで自動バックアップとバイナリログが有効になっているか確認します。 |
| **監視の再設定** | Cloud Monitoring等のアラート対象を新しいインスタンスに切り替えます。 |

-----

## 留意事項

  * **データの遅延:** 昇格直前のレプリケーション遅延（Replication Lag）により、数秒程度のデータ損失が発生する可能性があります。
  * **料金:** リードレプリカを常時稼働させるため、待機中もインスタンス料金とリージョン間データ転送量が発生します。

-----

**次に、具体的なgcloudコマンド一式や、Terraformでの管理方法について詳しく作成しましょうか？**

うーん、この手順書は使えないね! AIは現場の内容をなーんにもわかってないよ!
でもこれはAIが悪いわけじゃないよね。AIは与えられた情報をもとに最善を尽くしているだけなんだよね。だから、AIに頑張って正しい情報を教えてあげないといけないよ!

ここで、コンテキストエンジニアリングの出番だよ! AIに正しい情報を与えてあげて、もう一度手順書を書かせてみよう!

コンテキストエンジニアリングで補足情報を与える

コンテキストエンジニアリングっていうのは、AIに対して｢こういうことを知っておいてね!｣って補足情報を与えることなんだよね。

コンテキストエンジニアリングは、AIが関わる世界をうまくステップごとに分離していくことが重要だよ! まずは自分ならどんな手順で手順書を書くかを考えてみよう!

例えば、以下のようなステップで考えてみたよ!

  • 作業目的の明確化
  • 必要な要件の整理
  • 現状の調査
  • 要件を満たす方法の調査、選定
  • 手順の具体化

大体このくらいかな? ｢AIが関わる世界をうまくステップごとに分離していく｣っていうのはどういうことなのか、もう少し詳しく説明するね!

作業目的の明確化 + 必要な要件の整理

例えば、最初の作業目的の明確化は、AIにどのようなコンテキストを与えれば良いかな? このとき考えるのは、どんな内容を伝えるかじゃなく、どんな情報源を使ってAIに理解させるかなんだよね!

今回の場合、作業目的の明確化には以下のような情報源が考えられるよ!

  • Slackのやり取り
  • MTGの議事録

だから、これらの情報源がうまくAIと繋がっていれば、あとはAIに｢Cloud SQLのリージョン移行の目的を整理して｣とお願いすれば作業目的が明確化されるよね!

必要な要件の整理でも同じことが言えるよね! 必要な要件の整理には以下のような情報源が考えられるよ!

  • システム設計書
  • Slackのやり取り
  • MTGの議事録
  • 社内ドキュメント
  • 既存の手順書

だから、これらの情報源がうまくAIと繋がっていれば、あとはAIに｢Cloud SQLのリージョン移行に必要な要件を整理して｣とお願いすれば必要な要件が整理されるよね!

上記で説明した2つのステップは、なかなかAIに渡せるような情報が整理されていない場合も多いと思うから、ここは自分で考えてAIに情報を渡してもいいとおもうよ!

現状の調査

現状の調査フェーズでは、AIにシェルという情報源を与えるよ! シェルは、実際に動いているシステムの状態を調査するための重要な情報源だよね!

シェルで現状を確認するのは簡単そうに見えて、AIからすると多くのコンテキストを理解しないといけないから、結構難しいんだよね。コマンドを実行して、その結果を解析して、時にはコマンドの実行に失敗して、修正して...っていうのを繰り返す必要があるからね。

だから現状の調査フェーズは難しいシェルの操作に集中させて、web検索などの他の調査は次のステップとは別にするのがいいよ!

要件を満たす方法の調査、選定

要件を満たす方法の調査、測定では、以下のような情報源が考えられるよ!

  • 公式ドキュメント
  • 技術ブログ
  • Q&Aサイト

これらは、多くのAIツールではweb検索ができるようになっているから、AIに必要な要件を渡して、｢Cloud SQLのリージョン移行を実現する方法を調査して｣とお願いすれば、要件を満たす方法が調査、選定されるよね!

ここが一番難しいね! AIは確率的に最適な回答を出すから、間違った情報を出してしまうことがあるんだよね。これを軽減するためには、複数の方法で調査させるといいよ!

  • Deep Researchを使う
  • モデルを変えて調査させる
  • 情報源を公式ドキュメントに絞る
  • 情報源を最新の情報に絞る
  • 情報源を個人や企業のブログに絞る
  • 複数回調査させて、回答を比較する

このような方法を使って、最終的にどの方法が最適化を自分で判断したり、AIに判断させたりするとハルシネーションが減るよ!

手順の具体化

ここまでで、作業目的の明確化、必要な要件の整理、要件を満たす方法の調査、選定ができたよね! ここまでの情報をもとに、AIに手順の具体化をお願いすれば、手順書ができあがるよね!

でもAIの書いた手順書って信じられないよね? だから、ここではあとのフェーズで検証がしやすいように手順書を書くのがポイントなんだ!

具体的には

  • 最初に各手順の前提となる設定を確認、準備する
  • 各手順はシンプルなコマンドや操作に分解する
  • 各手順に対して、事前確認の手順を必要とする
  • 各手順に対して、事後確認の手順を必要とする

ということだね! 今回はCloud SQLのリージョン移行手順書を書かせるから、例えば以下のような感じかな!

前提の設定

  • gcloud CLIがインストールされていること
    • gcloud --versionで確認
  • gcloud CLIが正しいプロジェクトに設定されていること
    • gcloud config get-value projectで確認
  • gcloud CLIが正しい認証情報で認証されていること
    • gcloud auth listで確認

各手順の分解

  • cloud sqlにリードレプリカを作成する
    • 事前確認: gcloud sql instances listで現在のインスタンスを確認する
    • 手順: gcloud sql instances createコマンドを実行する
    • 事後確認: gcloud sql instances listでリードレプリカが作成されたことを確認する
  • リードレプリカを昇格させる
    • 事前確認: gcloud sql instances listでリードレプリカの状態を確認する
    • 手順: gcloud sql instances promoteコマンドを実行する
    • 事後確認: gcloud sql instances listでリードレプリカが昇格されたことを確認する

といった感じだね!

ただ、AIはgcloudコマンドのような専門的なコマンドは、オプションなどを間違えてしまうことが多いんだよ! だから、AIに手順書を書かせたあとは、必ず検証を行おう!

手順書には非破壊的なコマンドだと思われる事前手順が含まれているから、まずはこれを実行させて、オプションなどが間違っていないかを確認させよう!
余裕があれば、使用するコマンドのhelpコマンドも実行させて、出力結果と照らし合わせて確認させるといいよ!

検証環境がある場合は、最後に実際に手順書を実行させて、手順書通りに作業が完了するかを確認させながら、手順書を修正させよう!

まとめ

AIに手順書を書かせるときは、AIが苦手なポイントを補うように工夫する必要があるよ!

AIの不確実性を制御するには、AIが一度に関わる世界を可能な限り少なくコントロールすることが重要だよ! これがコンテキストエンジニアリングなんだよね!

主に分離できる領域は以下のように分離できるよ!

  • 社内情報
    • Slackのやり取り
    • MTGの議事録
  • シェル
  • インターネット上の情報
    • 公式ドキュメント
    • 技術ブログ
    • Q&Aサイト

特に手順書を作成する際は、以下の手順がおすすめだよ!

  • 作業目的の明確化
  • 必要な要件の整理
    • 社内情報を参照
  • 現状の調査
    • シェルを参照
  • 要件を満たす方法の調査、選定
    • インターネット上の情報を参照
  • 手順の具体化
    • 事前手順、事後手順を含めて具体化
    • シェルで手順を可能な限り検証

AIの得意なこと、苦手なこと、活用方法を理解して、うまく活用していこう!

GitHubで編集を提案

Discussion