AIに渡す仕様は、コードの隣に置く

最近、仕様駆動開発やコンテキストエンジニアリングという言葉をよく見かけます。AIに書かせるなら仕様を正にせよ、AIが常に参照する文書群を設計せよ、という話です。この連載でずっと「モデルを育てる」と言ってきましたが、育てたモデルは結局どこに残るのか。今回はその置き場所の原則を書きます。

設計書には「特売企画」、コードには「T_TOKUBAI2」

架空の小売チェーンの、十年前の話から始めます。当時のプロジェクトは教科書どおりでした。分析チームが業務部門に聞き取りを重ね、業務フロー図と機能一覧からなる立派な設計書を作る。実装は協力会社に委託され、設計書一式が「上流の成果物」として引き渡される。

十年後、その結果がどうなったか。設計書で「特売企画」と呼ばれていたものは、データベースでは「T_TOKUBAI」と「T_TOKUBAI2」の二つに分かれています。設計書で五種類と定義された企画の状態は、コードでは設計書に存在しない8番と9番を持っています。設計書そのものは初回リリースの日付のまま、ファイルサーバの奥で眠っている。

強調したいのは、誰かの怠慢ではないということです。全員がまじめに働いて、こうなった。実装側が納期やテーブルの都合で設計書を「翻訳」した時点で、モデルとコードは別物になる。そして実装中の発見や運用後の改修が設計書に戻る経路がない。真実はコードだけに溜まり、設計書は静かに嘘になっていく。

モデルは、一つ

処方はまっすぐです。業務を理解するためのモデルと、コードの設計図を、分けない。 業務の言葉に「販売期間」があるなら、コードにも同じ名前の型がある。「期間が重なる」という言い方があるなら、そのまま「重なる」という名前のメソッドになる。言葉がそのままコードの名前になる、という状態です。

これは妥協を要求します。業務の理解としては美しいが実装しにくいモデルも、実装は楽だが業務を語れないモデルも捨て、両方に仕える一つを探す。窮屈ですが、この制約がモデルを鍛えます。実装可能性は、思考の曖昧さを許してくれないからです。

四つの姿と、正の序列

では実務として何と何を一致させるのか。私は、モデルは四つの姿で存在すると考えています。会話のための図。具体的な値を入れた日本語の実例シナリオ。名詞がクラスに、ルールが不変条件になったコード。そしてシナリオと一対一で名前をつないだテスト。どれが本体でどれがコピーではなく、同じ一つのモデルの四つの投影です。

食い違ったとき、どれを信じるか。人が読む正は、日本語のシナリオと設計メモ。テストはその鏡。コードは常に最新だが「なぜ」を語らない。図は使い捨ての会話道具。

「テストがあれば仕様書は要らない」という意見には賛成しません。テストは振る舞いの厳密な鏡ですが、なぜそうなのかを語らない。なぜ端の日の重なりも重複とみなすのか。数年後に改修する人が本当に必要とするのは、この「なぜ」です。

置き場所は、コードの隣

四つの姿の置き場所は、一つに決まっています。すべてコードと同じリポジトリに、平文で置く。 用語集、概念別に束ねたシナリオ集、なぜそう決めたかの設計メモ。

理由は原理的です。乖離は、変更の経路が分かれることから生まれます。シナリオがWordでファイルサーバに、コードがリポジトリに、と分かれた瞬間、二つは別々の人に別々のタイミングで変更され、十年前への道が始まる。同じ場所に置けば、シナリオの修正とコードの修正を同じ変更に入れられ、レビューで「対応するシナリオは直しましたか」と機械的に問える。置き場所の統一は、同期の規律を意志の力から仕組みに変えます。 Wordを避けるのは好みではなく、差分が読めない文書はレビューされず、レビューされない文書は腐るからです。

世界は、同じ結論に向かっている

ここでAI時代の話に戻ります。この数年、AIによる開発の現場で一つの反省が共有されました。雰囲気で指示を出し、出てきたコードを雰囲気で受け入れる作り方は、規模が育つと決まって崩れる。指示が曖昧なのでAIが「ありがちな既定値」で穴を埋め、数か月後には機能を足すたびに何かが壊れる。

業界が向かった先は、示し合わせたように同じでした。自然言語の仕様を正とし、コードをそれに追従させる。その場の指示文を工夫するのではなく、AIが常に参照する文書群を設計する。標語まで生まれました。仕様がコードに仕えるのではない、コードが仕様に仕える。

既視感しかありません。自然言語の仕様が正でコードは追従、とは「四つの姿」と「人が読む正は日本語のシナリオ」のことです。AIに渡す文書群とは、用語集とシナリオと設計メモのことです。そして平文でコードの隣に置いてあるものは、人だけでなくAIもそのまま読めます。以前、動く画面を十数分で作らせた実録で「渡したのは指示文ではなく、業務の言葉で書かれたルール」と書きました。あれは、この置き場所の話でした。

世界が再発見しているのは、翻訳をなくしてモデルを正とするという、二十年前の賭けそのものです。実装コストという重石が外れて、ようやく設計思想どおりの速度で回り始めた。ボトルネックはモデルにある。そしてモデルの住所は、コードの隣の平文です。

次回は最終回です。本を出してからの実売と読まれ方を数字で振り返り、AIと一冊書いてnoteで連載を回したこの試みが何を残したのかを書きます。

この連載の元になった書籍『モデルを育てる ― 要件を探り、MVPで確かめ、境界で分ける実践ドメイン駆動設計』(有原悠)では、この「四つの姿」と置き場所を、架空の小売チェーン「アオバ堂」の特売企画を題材に、実際のシナリオとコードで示しています。

※Kindle Unlimited読み放題対象です。

▼ 前の話

▼ 次の話