作業指示書は、最初に書かせない ― 設計AIとのやり取りを全部見せる
前回、設計も実装もレビューも AI が行う個人開発で、精度をどう出しているかの全体像を書きました。
そこで、作業指示書を書く AI を設計 AI、コードを書く AI を実装 AI、実装を審査する AI をレビュー AI と呼びました。
今回から 3 回に分けて、それぞれと実際にどうやり取りしているかを書きます。
1 回目は設計 AI です。
「指示書を書いて」からは始めない
機能を追加したい、挙動を変えたい、と思ったとき、私は設計 AI にやりたいことを伝えて「作業指示書を書いて」とは言いません。
いきなり書かせると、指示書は設計 AI の推測で埋まります。今のコードがどうなっているか、どこに何があるか、何が既に実装済みか。設計 AI はそれを調べずに書き始めることができてしまいます。そして、調べずに書いた指示書は、実装 AI に「既にあるものを作り直す」「境界の外を触る」という仕事を発注します。
前回の記事で「実装 AI は指示書に書いていないことを勝手にやり、書いてあることを黙って落とす」と書きました。指示書が推測で書かれていれば、その両方が起きます。
だから、指示書は最後です。そこに至るまでに、私は設計 AI と 4 段階のやり取りをします。
1. まず、調査・確認を依頼する
最初にやるのは、現状の調査・確認です。
「今、この機能はどう動いているか」「この挙動はどこで決まっているか」「関連するテストは何か」。こういうことを、設計 AI に調べさせます。
目的は 2 つあります。
一つは、設計 AI に状況を把握させること。この後の提案も指示書も、ここで把握した現状の上に積みます。
もう一つは、私自身が現状を把握することです。私はコードを書いていないので、AI が調べた結果を読んで状況を知ります。
これには段階があります。作り始めのコード規模が小さいうちは、私の把握は現状に追いついています。調査を頼まなくても、だいたい分かっている。
しかし、やがて追いつかなくなります。仕様が変わり、機能が拡張されていくと、「前はこうだった」という私の記憶と、今のコードは、少しずつずれていきます。ずれたまま指示を出すと、その指示は今のコードではなく、私の記憶の中のコードに対するものになります。
だから、規模が大きくなるほど、変更が重なるほど、この段階を飛ばせなくなります。
実際、この段階で「実は既に実装済みだった」と分かることがあります。前回書いた「外部評価の『未実装』を鵜呑みにした」失敗は、まさにこの調査を飛ばしたときに起きました。
2. 提案・アイデアを聞く
調査結果が出たら、次にこう聞きます。
XX する機能を追加する（XX を YY のように変更する）には、どうすれば良いか。提案・アイデアを聞かせて。
ここで「こう実装して」とは言いません。どうすればいいか、意見を求めます。
前回の記事で「指示によって AI の能力を縛らない」と書きました。その実体がここです。
私が方法を指定すると、設計 AI は私の想定の範囲でしか考えなくなります。私の想定より良い設計、私が気づいていない選択肢があるなら、それを出してほしい。だから、方法を決める前に、方法を聞きます。
出てくるのは、たいてい複数の案と、それぞれの利点・欠点です。
モデルによっては、案だけ出てきて利点・欠点が付いてこないこともあります。そのとき追加で聞くかどうかは、私が判断します。聞かなくても決められるなら聞かないし、決められないなら聞きます。
3. 追加の質問・調査を重ねる
提案を読んで、すぐに決めることもあれば、決められないこともあります。
決められないときは、設計 AI に追加の質問や調査を頼みます。
- その案だと、他のどこに影響が出るか
- 既存のテストで、この変更に引っかかるものはあるか
- その値は、誰が読んでいるか
最後の項目は、前回書いた失敗そのものです。指示書に「この挙動の差は意図的な修正」と書いてあったのに、その差が別の経路を伝わって、変更を適用してよいかどうかの判定を変えていました。その値を誰が読むかを追わなかったのが原因でした。
今は、この段階で追います。そして後述するように、追った結果は指示書に残ります。
この往復は、必要なだけやります。1 往復で済むこともあれば、何度も戻ることもあります。
4. 方針とスコープを伝えて、指示書を書かせる
ここまでで、私の中に方針ができます。
どの案で行くか。今回どこまでやるか。どこは触らないか。
これを決めるのは私です。 そして、決めた方針とスコープを設計 AI に伝えて、作業指示書を作成するように指示します。
書くのは設計 AI です。私は書きません。ここまでのやり取りで、設計 AI は現状も、案の得失も、私が選んだ方針も知っています。その AI が書く指示書は、推測ではなく確認済みの事実の上に立っています。
指示書に、対話の成果が全部残る
ここが、この 4 段階の要点です。
やり取りの結果は、私の頭の中に残るのではなく、指示書の中に残ります。
実際の指示書を 1 本、見てみます。ある不具合を直すために書かれたものです。節の構成はこうなっています。
0. 背景（確定済みの実測事実）
1. 変更内容（以下の 3 点のみ。これ以外はしない）
2. Decision / Contract
3. 着手前の波及調査（必ず grep し、結果を報告に含める）
4. 空虚化チェック（必須）
5. 受入条件
6. 明示的にしないこと（スコープ外）
0 節は、段階 1 の調査結果です。 実際のログから確認された事象の連鎖が、時刻つきで書いてあります。索引にはファイルが残っているのに実体は消えていた、AI はそのファイルを読もうとしたが黙ってスキップされた、空のまま次の段階に進んで失敗し、失敗が別の原因として記録された。そして最後に一文、「本件は Provider の問題ではない」。調査で分かった因果が、そのまま指示書の冒頭にあります。
1 節は、段階 4 で私が決めた方針です。 見出しに「以下の 3 点のみ。これ以外はしない」とあります。
3 節は、段階 3 の追加調査の続きです。 「その値を誰が読むか」を、実装 AI にも grep させて報告に含めさせます。設計 AI が追った波及を、実装 AI がもう一度追う。二重に見ます。
6 節が、段階 4 のスコープです。 この指示書では、1 行目にこう書いてあります。
stale index の検出・自動再構築（今回の根本原因だが別課題。本書は帰属の是正のみ）
根本原因が分かっていて、それでも今回は触らないと決めた。根本原因を直すことと、今回のスコープは別です。この判断は私がして、指示書に「スコープ外」として明記され、根本原因のほうは別の指示書になりました。
そして、段階 2 で出た案のうち採らなかったものは、指示書が実装 AI に「設計判断の記録に却下理由つきで全て残せ」と要求します。私が却下した案も、その理由も、後から辿れます。
なぜ、指示書を最初に書かせないのか
改めて整理します。
- 調査なしの指示書は、推測で埋まる。 だから先に調べさせる。
- 提案なしの指示書は、私の想定に縛られる。 だから先に意見を聞く。
- 対話なしの指示書は、波及を見落とす。 だから決める前に追加で問う。
指示書は、出発点ではなく、対話の結論です。
そして結論を文書にすることで、対話の中身を私が覚えている必要がなくなります。何を調べ、何を却下し、どこを触らないと決めたか。全部、指示書と設計判断の記録にあります。次に同じ場所を触るとき、私も設計 AI も、それを読めば済みます。
段階 1 で書いた「私の把握が現状に追いつかなくなる」ことと、これは同じ話です。追いつかなくなるのが分かっているから、追いつく必要のない形にしておく。覚えるのではなく、調べれば分かる状態を保つ。
次回は、この指示書を受け取った実装 AI と、どうやり取りしているかを書きます。
関連記事
このシリーズ（Zenn）:
- 設計も実装もレビューもAIがやる個人開発で、精度をどう出しているか — 全体像。設計 AI・実装 AI・レビュー AI の 4 層の仕組み
作っている製品（R2 Fugu Agent Runtime）の設計については、Qiita に別のシリーズを書いています:
Discussion