AI に書かせた仕様書は、書いた本人に検証させない
目次
AI エージェントと設計を進めていると、仕様書がいつの間にか実装と合わなくなっていきます。読み返しても自然に読めるので、どこがずれているのか分かりません。前の記事では、AI が存在しないトランシーバを前提にして、正しい資料のほうを誤りと判断した話を書きました。そのとき誤りを止めたのは、AI とは別に一次資料を調べていた人でした。この記事では同じ考え方を仕様書に当てはめ、50本をソースと突き合わせて見つかった10件の食い違いと、書く役と検証する役を分ける仕組みを紹介します。
仕様書50本をソースと突き合わせたら、10件ずれていた#
書きためた仕様書を、ソースから照合し直す#
AI エージェントと進めている FPGA の案件で、仕様書をソースと突き合わせ直しました。最初にドラフトを作り、その後は設計しながら不足を埋めてきた仕様書です。ソースとは、回路の記述（RTL）と、ピンやタイミングの制約ファイルです。
作業には、サブエージェントを使いました。メインのエージェントから呼び出して、別の作業を任せられる AI のことです。8体を並列に走らせ、それぞれに別の文書を担当させました。もとの36本のうち4本を削除・26本を更新し、18本を新規に書いて、最終的に50本になりました。その過程で、はっきり食い違っていた記述が10件見つかりました。
食い違いの3つの種類#
10件を分けると、3種類になりました。
| 種類 | 例 |
|---|---|
| 状態が古いまま | 暫定対応がもう戻っているのに「暫定中」のまま。候補の数や既定値が変わっている。カウンタの単位が、別のクロックのサイクル数になっている |
| 理由が誤っている | 「デバイスの仕様上の制約」と書かれていたが、実際は自分たちの配線の問題で、すでに解消していた |
| 名前に引きずられている | コード上のクロックの名前が実際の配線と1段ずれていて、文書の周波数の記述まで誤っていた |
このほかにも、「使っていない」とされていたディレクトリが現役で、本当に使われていないのは別のディレクトリだった、という発見もありました。どれも、文章としては自然に読めるものばかりです。
1つの誤りは、前提の手がかりになる#
別の担当が見つけた、手順書の誤り#
同じ案件で、社外向けの手順書に PC 側のツールの使い方を書いたときのことです。FPGA 側を受け持つエージェントが、「終了コマンドを単独で実行すれば、有効化が解除される」と書きました。ところが、ソフト側を受け持つ別のエージェントがソースを読んで指摘してきました。このツールの「有効化されている」という状態は、プロセス内のメモリに持っているだけで、ハードウェアには問い合わせていません。1コマンド1プロセスで使うと、終了コマンドは何もせずに終わり、ハードウェアは有効のまま残ります。
この指摘を受けて見直すと、同じ前提から来た誤りがもう1か所見つかりました。手順書の別の注意書きでも、ツールの状態とハードウェアの状態を同じものとして書いていたのです。この関係を図にすると、次のようになります。
誤りを直して終わりにしない#
誤りを1つ見つけると、そこを直して終わりにしたくなります。逆に考えると、1つの誤りは「誤った前提がある」ことを示す手がかりです。その前提に沿って書いた箇所は、ほかにもあるかもしれません。今回の2件目は、まさにそうやって見つかりました。
ただ、その前提は書いた本人には見えにくいと考えられます。前提に沿って書いたのですから、読み返しても前提に沿って読んでしまうからです。今回も、2件の誤りの元になった前提を崩したのは、書いた側ではなく、ソースを持つ別の担当でした。
書く役と、検証する役を分ける#
誤りを外に出さない5つの仕組み#
この案件で効いたのは、書く役と検証する役を分けることでした。流れは次の図のとおりです。
- 既存の文書ではなく、ソースから書く。 新しい概要書をソースから直接書いたことで、既存の文書が古いことに気づけました
- 担当範囲の外は、そこを持つ担当に事実確認を出す。 手順書の誤りは、ソフト側の担当に確認を出していたから、社外に出る前に止まりました
- 記述ごとに確度を書き分ける。 「推測」「ソース確認済み」を明記しておくと、検証すべき場所が分かります
- 照合は並列に、別のエージェントに任せる。 8体のサブエージェントが、それぞれ自分の文書だけをソースと照合しました。途中の細かい経過がメインのエージェントの記憶（コンテキスト）を埋めないのも利点です
- 同じ情報を2か所に書かない。 レジスタ表を1か所だけに置き、ほかの文書からは参照する形にしました。2か所あれば、いずれ片方が古くなります
照明の仕事でも同じ#
調光の設定表と実装がいつの間にかずれていくのも、多くは「状態が古いまま」の型だと思います。表を1か所に置き、実装と照合する役を別に持つ、という考え方はそのまま使えます。
まとめ#
冒頭の「仕様書がいつの間にか実装と合わなくなる」への答えは、「書いた本人ではなく、ソースを持つ別の役に照合させる」です。誤りは文章として自然に読めるので、書いた側が読み返しても見つかりにくいと考えられます。
誤りの種類と検出法#
| 誤りの種類 | 書いた側が見落とす理由 | 検出法 |
|---|---|---|
| 状態が古いまま | 書いた時点では正しかった | ソースと定期的に照合する |
| 理由が誤っている | 前提に沿って筋が通っている | 前提を疑う検証役を別に立てる |
| 名前に引きずられている | 名前を信じて読んでいる | 実際の配線・設定まで遡る |
持ち帰り#
- 文書は書いた本人ではなく、ソースを持つ別の担当（別のエージェント）に照合させる
- 既存の文書を引き写さず、ソースから書く
- 記述ごとに「推測」か「ソース確認済み」かを書き分ける
- 同じ情報を2か所に書かない
- 誤りが1つ見つかったら、同じ前提から来た誤りが他にもないかを探す
次の記事では、同じ考え方をテストに当てはめた話を書く予定です。テストを書いた側が、自分で置いた仕様を自分で確かめていた、という話です。