DotMDAIが書いた仕様のレビュー方法：エージェントが作る前のチェックリスト。
AIエージェントは、自信に満ちた整った仕様を1分で書きます。そこが危ないところです。間違っていても、読みやすいのです。このチェックリストで、実装を始めさせる前に何を見ればよいかを確認します。
macOS 14以降。閲覧は無料で、編集とレビューは1回のお支払いです。
要点
AIが書いた仕様は、プルリクエストをレビューするのと同じようにレビューします。まず正しい課題を解いているかを確認し、次に足りないものを探します。範囲と非目標、エッジケース、データと移行、テストとロールバックを順に見て、エージェントがコードを書く前に、変更したい箇所すべてにコメントを残します。
- [ ] Scope matches what I asked for
- [ ] Non-goals are listed
- [ ] Edge cases and errors are covered
- [ ] Data and migrations are explicit
- [ ] Tests prove each requirement
- [ ] There is a rollback·
AIの仕様に別のレビューが必要な理由
人が仕様を書くと、自信のない部分に空白が残りがちです。モデルは、推測した部分も含めて、すべてを流暢な文章で書きます。そのため、あいまいな表現や明らかな抜けといった、弱い仕様の通常の兆候がなく、問題は自信に満ちた文の中に隠れます。よい書き手なら尋ねていたはずのことを探して、レビューしてください。
チェックリスト
-
範囲：頼んだことを解決しているか
最初の段落を、自分の依頼と見比べます。別の課題を解いていないか、誰も頼んでいない機能がないかを探します。
-
非目標：何をしないのか
非目標のない仕様には輪郭がありません。不要なおまけを書き足します。
-
前提：何を推測したか
「おそらく」「たぶん」や、読んでいないかもしれないコードやデータについて事実のように書かれていることを探します。根拠のファイルを示すよう求めます。
-
エッジケース：うまくいかないとどうなるか
空の入力、非常に大きな入力、権限がない、ネットワークがない、2人が同時に操作する、同じ操作を2回行う。
-
データ：何を保存、変更、削除するか
項目、形式、誰が読めるか、既存のレコードがどうなるか。
-
移行：古いデータはどう移るか
スキーマの変更には、手順の順序、途中で失敗したときの計画、安全に2回実行できる方法が必要です。
-
インターフェース：ほかに何に触れるか
API、画面、ジョブ、他チームのコード。仕様が変更するのに書かれていないものは、あとで驚きの種になります。
-
セキュリティとプライバシー：誰が何をできるか
新しい権限、システムの外に出る新しいデータ、ログに残る秘密情報。
-
テスト：動くことをどう確かめるか
それぞれの要件に確認方法が対応しているべきです。テストできない要件は書き直します。
-
リリースとロールバック：どう元に戻すか
フラグ、段階的なリリース、戻す手段。「あとで修正して進める」は計画ではありません。
-
未解決の質問：誰が決めるか
正直な仕様は、分かっていないことを挙げます。1つもなければ、疑ってください。
効くコメントの書き方
あいまいなフィードバックは、あいまいな書き直しを招きます。よいレビューコメントは、1つの箇所を指し、何が問題で、代わりにどうしてほしいかを述べます。
> The export runs when the user taps Export.
Missing: what happens with a 2 GB file? Add a limit (R4) and an
error message, and say whether the export can be cancelled.仕様のファイルがきれいなままになるよう、コメントは仕様のテキストとは別に保ち、まとめて出しましょう。仕様全体を一度読んでからコメントすれば、エージェントの書き直しが10回ではなく1回で済みます。
レビューの流れ
-
最初に最後まで読む
コメントする前に、計画全体を理解しておきます。
-
正確な箇所にコメントする
1つのコメントには1つの問題。
-
エージェントに修正させる
エージェントが各コメントに対応し、新しい版を作ります。
-
ドキュメント全体ではなく変更点を確認する
差分を読みます。修正が、問題なかった部分を壊すことがあります。
-
チェックリストがすべてクリアになってから承認する
そのうえで、番号付きの要件に沿って作らせます。
あるエージェントが別のエージェントの仕様をレビューするときも、同じチェックリストが使えます。レビュアーに、各項目に仕様からの引用で答えるよう頼みます。
よくある間違い
- 中身ではなくスタイルをレビューする。整った仕様でも、間違っていることはあります。
- 長いから承認する。長さは網羅性ではありません。
- 非目標とロールバックを飛ばす。モデルがいちばん薄く書きがちな2つのセクションです。
- 仕様ではなくコードを直す。計画が間違っているなら、先にそれを直します。
- 見直さない。エージェントが修正したら、差分を確認します。
AIが書いた仕様のレビューに関するよくある質問
AIが書いた仕様をレビューするには？
正しい課題を解いているかを確認し、次に足りないものを探します：非目標、エッジケース、データと移行、テストとロールバック。各箇所にコメントし、コードを書く前にエージェントに修正させます。
仕様レビューのチェックリストには何を入れますか？
範囲、非目標、前提、エッジケース、データ、移行、インターフェース、セキュリティ、テスト、リリースとロールバック、未解決の質問です。
あるAIエージェントが別のエージェントの仕様をレビューできますか？
はい。レビュアーにチェックリストを渡し、各項目に仕様からの引用で答えるよう頼みます。何を受け入れるかは、あなたが決めます。
仕様ではなくコードを読めばよいのでは？
その時点では、決定はすでに下され、変更には費用がかかります。間違った前提は、仕様の段階で直すのがいちばん安上がりです。