AI に技術要件を伝えるときの3要素 — スコープ・ロジック・データソース

投稿日 2026/05/08

投稿者 rengotaku

8 分で読めます

まとめ

AI への技術指示が誤解されるのは「出力例」だけ提示しているケースが多い
出力例に加えて スコープ（実行範囲） ロジック（生成ルール） データソース（入力源） を併記すると一発で伝わる
出力例単独だと AI 側が前提を勝手に補完してしまい、間違った方向に作り込みが走る

きっかけ

AI コーディングエージェントに「フェールオーバー検証スクリプトの出力で 1a → 1c → 1a のような遷移チェーンを表示してほしい」と指示したところ、複数回のスクリプト実行をまたいで履歴を追うために /tmp に状態ファイルを生成する実装が返ってきた。

実際に欲しかったのは「1回の実行内でイベントログから再起動回数を数えて、その回数だけ AZ を交互に並べる」ことだったのに、まったく別の解釈で実装が走ってしまった。

なぜ伝わらなかったか

要望として渡したのは「1a → 1c → 1a という出力例」だけだった。

AI 側はこの例だけを見て、自然な解釈として「複数回の操作を跨いだ履歴の蓄積」と推測した。確かに3つの AZ がチェーンで並ぶ表示を出すには、過去の状態をどこかに保持する必要がある。AI の判断としては妥当だが、私の頭の中にあった前提（「再起動回数 = AZ フリップ回数」）はどこにも書いていなかった。

その後「履歴は不要」「ファイルは要らない」「1回目・2回目とか考慮しなくていい」と修正指示を重ねたが、AI 側は元の解釈を引きずって「では state ファイルを消して before → after だけ表示する」という案に倒してしまった。私が欲しかった3ホップのチェーン表示は実現されないまま、何度も往復することになった。

何が足りなかったか

後から振り返ると、出力例とセットで以下3点を最初に伝えるべきだった。

1. スコープ — どの範囲で完結するのか

「1回のスクリプト実行内で完結する」と明示する。これだけで「複数回実行を跨いで履歴を持つ必要があるか？」という根本的な分岐がなくなる。

スコープが曖昧だと、AI は「念のため広めに対応しておこう」と判断して、実行をまたぐ仕組み（ファイル・DB・state 管理）を作り込み始める。

2. ロジック — どういうルールで生成するのか

「DB instance restarted の件数 = AZ フリップ回数」のように、入力と出力を結ぶルールを書く。

出力例だけだと、AI は逆算で生成ルールを推測することになる。今回の例は3つの値が並んでいるだけだが、生成ルールとしては複数解釈できる:

過去の state を蓄積した結果（複数回実行を跨ぐ）
何らかのカウンタに応じた交互配置（1回の実行内）
固定パターンの表示（最大 N 回まで）

ルールを明示すれば、この曖昧性が消える。

3. データソース — 何を入力にするのか

「describe_events の戻り値から restart イベントを数える」「describe_db_instances の AvailabilityZone と SecondaryAvailabilityZone を交互に並べる」のように、入力に使う値を具体的に書く。

データソースが書かれていないと、AI は「前回の実行結果を覚えておく必要がある」と判断する余地が生まれる。逆に「この API レスポンスのこのフィールドを使う」と書けば、それ以外の状態管理は不要だと自然に伝わる。

テンプレート化

技術的な出力指示を AI に渡すときは、以下の枠で書くと事故が減る。

【スコープ】1回の実行内で完結する
【ロジック】X の件数だけ A と B を交互に並べる
【データソース】API レスポンスの field_x と field_y
【出力例】
  0 → A
  1 → A → B
  2 → A → B → A
  3 → A → B → A → B

特に重要なのは出力例を 複数パターン 並べること。1パターンだけだと汎化できないが、3パターン並べればルールが浮き彫りになる。

自分側の落とし穴

「察してくれるはず」「文脈で分かるはず」と省略してしまうのが一番の事故要因だった。AI は会話履歴を読むが、人間が頭の中で持っている前提までは読めない。

具体例 + ルール + スコープを毎回明示するのは冗長に感じるが、往復回数が減るので結果的にトータルの時間は短くなる。「出力例だけ」では AI は推測に倒れる、というのを忘れないでおきたい。

まとめ