「AIが読める仕様書」の書き方：上流工程でAIを活かすための3つの設計原則

# 「AIが読める仕様書」の書き方：上流工程でAIを活かすための3つの設計原則

「ChatGPTに仕様書を渡してみたけど、的外れな実装が返ってきた」

この経験をした開発者は多い。AIへの期待が高まる一方、上流工程でのAI活用がうまくいかない現場も少なくない。

前回の記事（コードは読めるのに仕様は読めない）で、その構造的な理由を解説した。コードには構文ルールという「形式」があり、ASTで解析できる。しかし仕様書は自然言語で書かれ、文脈依存が多く、AIが確定的に処理しにくい——という話だ。

では、どうすればいいのか。今回は「書き方」に踏み込む。

仕様書の「内容」を変えるのではなく、「構造」と「表現」を変えることで、AIが理解しやすいドキュメントに変えることができる。現場で試してきた3つの原則を紹介する。

なぜ仕様書はAIに読まれにくいのか（おさらい）

まず前提を整理する。

従来の仕様書は、人間のPM・SEが読むことを前提に書かれている。

• 背景や文脈は「読んでいる人が知っているはず」という前提で省略される
• 「このシステムでは〜のように扱う」といった暗黙の慣習が書かれない
• 「例外はない」と書かずに、例外がないことを示す

人間は行間を読む。でもAIは読まない。

AIが仕様書から実装や設計を導き出すためには、「なぜ」「誰が」「何を」「どの条件で」「例外は何か」が明示されていなければならない。それが書かれていないと、AIは補完しようとして、ハルシネーションが起きる。

原則1：「入力・処理・出力」を分離して書く

最も基本的で、効果が大きい原則がこれだ。

悪い例：

ユーザーが申請フォームに入力した内容をシステムが受け取り、処理して、結果を表示する。

良い例：

■ 入力
- ユーザーID（必須）
- 申請種別（選択肢：休暇申請 / 経費申請 / 備品申請）
- 申請日時（自動付与）
- 添付ファイル（任意、最大5MB、PDF/PNG/JPG）

■ 処理
1. 入力値のバリデーション（全必須項目が入力済みか確認）
2. ユーザーの承認ルートを組織マスタから取得
3. 申請データをDBに保存（ステータス: 申請中）
4. 直属上長にメール通知を送信

■ 出力
- 申請完了画面（申請番号を表示）
- 申請者へのメール（件名: 「申請を受け付けました」、本文: 申請番号・申請種別）

AIはこの「入力→処理→出力」の構造を見ると、それぞれを独立した単位として処理できる。関数シグネチャやAPIインターフェースとの対応関係が明確になるため、実装コードへの変換精度が格段に上がる。

現場で試した結果、この形式に変えただけで、AIが生成する実装コードの「ズレ」が大幅に減った。特に、「処理」の部分を番号付きステップで書くと、AIがそのまま関数の実装順序として解釈してくれることが多い。

原則2：「コンテキスト」を冒頭に明示する

仕様書の多くは、「何を作るか」から書き始める。でも AIにとって重要なのは、「なぜこれが必要か」と「どこに位置づけられるか」だ。

悪い例：

# 承認フロー機能の仕様

申請された内容を上長が確認し、承認または却下できる機能を実装する。

良い例：

# 承認フロー機能の仕様

## コンテキスト
- **このシステムは何か**: 社内の経費・休暇申請を電子化するワークフローシステム
- **なぜこの機能が必要か**: 現在の紙申請では承認状況が不透明で、処理遅延が発生している
- **誰が使うか**: 申請者（全社員）、承認者（部長以上）、管理者（人事・経理）
- **既存システムとの関係**: 人事マスタ（組織構造・承認ルートの参照元）、会計システム（経費データの連携先）
- **スコープ外**: 電子署名機能、モバイルアプリ対応（次フェーズ）

## 機能仕様
（ここから機能の詳細...）

このコンテキストブロックが冒頭にあると、AIは機能仕様を読むときに「この機能が何のためにあるか」を理解した状態で処理できる。

特に重要なのはスコープ外の明示だ。「電子署名は対象外」と書かれていれば、AIは電子署名の実装を提案しない。書かれていなければ、「こういうシステムには電子署名が必要では？」と余計な提案をしてくることがある。

原則3：「例外と制約」を網羅的に書く

人間は「普通はこうなる」という暗黙の了解で仕様書を読む。でも AIには暗黙の了解がない。

そのため、仕様書で最も重要なのに最もよく省略されるのが「例外と制約」の記述だ。

悪い例：

申請者は申請内容を編集できる。

良い例：

■ 申請内容の編集

- 申請者は「申請中」ステータスの場合のみ、申請内容を編集できる
- 「承認待ち」以降のステータスでは編集不可（理由: 承認者が確認中のため）
- 編集後は、承認ルートが最初からやり直しになる（再申請扱い）

■ 例外ケース
- 申請者が退職した場合: 申請は自動で「取消」に変更される
- 承認者が不在・退職した場合: 代理承認者（上位上長）に自動エスカレーション
- システムエラー時: DB保存失敗の場合は申請を受け付けず、申請者にエラーメッセージを表示。再申請を促す

この粒度で書かれた仕様書をAIに渡すと、エッジケースの実装漏れが大幅に減る。「退職者の扱いはどうするか」「タイムアウト時の処理は？」といった質問をAIから返されることがなくなり、実装の一回目の精度が上がる。

3つの原則の背景にある考え方

これら3つの原則に共通しているのは、「読む人が知っているはず」という前提を取り除くことだ。

人間が書く仕様書は、多くの場合「読む側も同じ組織にいて、背景を知っている人」を想定している。だから省略が起きる。

AIはその省略を補完しようとするが、そのとき使うのは「訓練データから学んだ一般的な知識」だ。あなたの組織固有の慣習や、このシステム特有の制約は、AIには見えない。だからズレが起きる。

仕様書を「背景を知らない人に渡しても実装できるドキュメント」として書く——これがAI活用時代の上流工程の基本姿勢になる。

移行のハードル：「書くのに時間がかかる」問題

この原則を聞いて「そんな丁寧に書いていたら、仕様書作成が2倍3倍の時間になる」と感じた人もいるかもしれない。

正直、書き始めの段階は確かに時間がかかる。

ただ、実際に現場で試してみると、仕様書作成の時間増加よりも、実装・レビュー・手戻りの削減効果の方が大きいことがわかってきた。

特に効果が出やすいのは:

• AIを使ったコード生成フェーズ: 仕様書の質が上がると、AIの生成コードの質が上がり、レビュー指摘が減る
• ドキュメントのメンテナンス: 入力/処理/出力が明確に書かれていると、変更時にどこを更新すべきかが一目瞭然
• 引き継ぎ・オンボーディング: 新メンバーに「この仕様書を読んで実装してみて」と渡せるレベルになる

また最近では、AIを使って仕様書自体のドラフトを作るアプローチも広まっている。ヒアリング内容をもとにAIが仕様書の骨格を生成し、人間が確認・補完する、というフローだ。入力/処理/出力の構造があれば、AIが生成した仕様書を人間がレビューするコストも下がる。

まとめ：仕様書はAIへの「指示書」でもある

2026年現在、開発プロセスにAIエージェントが入り込むのは当たり前になりつつある。

このとき、仕様書は「人間のエンジニアへの説明書」であると同時に、「AIへの指示書」でもある。

コードが「AIが書いてくれるもの」になりつつある今、仕様書の質が開発全体の品質を左右する時代が来ている。コードを書く前段階、つまり「何を作るか」を決める工程に、より多くの投資をする理由がそこにある。

上流工程のAI活用や、仕様書の構造化に興味がある方は、ぜひお問い合わせください。現場での実践経験をもとに、具体的なご支援が可能です。