一人＋AI時代のドキュメント構造を考えていたら必然的にUXを書くことになった
はじめに
一人で開発しているとき，「頭の中に全部入っているから」とドキュメントをサボりがちである．ただ，そこに AI が相棒として入ってくると状況が一気に変わる．一人ではなくなるためだ．
- AI に仕様を書かせる
- AI に既存コードを読ませて変更案を出させる
- AI にテストやレビューのたたきを作らせる
こういうことをやろうとした瞬間，人間と AI の両方が読める・書けるドキュメントの設計が重要になる．AI にドキュメントを読ませることは非常に重要で，開発者の意図を正確に伝える助けとなる．
この記事では，一人＋ AI で開発するときのドキュメント設計について，
- どのような構造にするか
- 何を書くか，書かないか
- エンジニアも UX を考える必要性
を整理しておく．自分の考えを固めるメモも兼ねる．
構造の重要なポイント 3 つ
一人＋ AI 開発でドキュメントに求めるものをまとめると，次の 3 つに落ち着いた．
- 抜け漏れがない（網羅性）
- SSOT（信頼できる唯一の情報源）
- 粒度を揃えたレイヤー構成
抜け漏れがない（網羅性）
まず大事なのは，ユーザー体験から画面・挙動までがちゃんとつながっていることである．この点を踏まえてドキュメントを 3 つのレイヤに分けた．
- UX … ユーザーの目的・行動・成功条件
- Feature … システムの振る舞い・ビジネスルール
- Screen … UI 要素・操作・画面遷移
この 3 つに分けたうえで，UX → Feature → Screen が辿れる状態になっていると，
- この UX に対応する Feature がちゃんとあるか
- この Feature を実現する Screen が存在しているか
を機械的にチェックできる．テスト観点やレビュー観点が定まる．
AI にとってもこれは重要で，たとえば「この UX を満たす Feature 案を出して」や「この Feature に対応する Screen のたたきを作って」といったお願いがしやすくなる． レイヤ間がリンクされていることが，そのまま網羅性のチェックラインにもなります．
SSOT（信頼できる唯一の情報源）
次に重要なのが，同じ種類の情報が複数の場所にバラバラに書かれていないことである．
- ビジネスルール → Feature にだけ書く
- 画面構成や要素 → Screen にだけ書く
- ユーザーの目的や成功条件 → UX にだけ書く
といった形で，「何をどこに書くか」をあらかじめ決めておく．
これをやっておかないと，
- 似たような説明が複数ファイルに存在する
- 片方だけが更新されてもう片方が古いまま残る
という状態になり，どれが正しいのか人間も AI も判断できなくなります．AI にとっても SSOT は重要で，重複する情報源があるほど回答がブレやすくなる．
「ビジネスルールが知りたければ Feature だけを見ればいい」という状態にしておくと，参照先をシンプルにできる．
粒度を揃えたレイヤー構成
最後のポイントは，レイヤーごとの書く粒度を揃えることである．
- UX … 1 つのユーザーの目的とそれを達成するフロー
- Feature … 1 つ〜数個のまとまった振る舞い・ビジネスルール
- Screen … 1 画面の構成要素・操作・遷移
のように，1 ファイルがどれくらいの「大きさ／まとまり」を持つかを決めておく．
粒度がバラバラだと，
- 謎のクソデカ UX ドキュメント
- 数行しか書かれていない Feature
- 中途半端に重複している Screen
のような状態になりがち．
逆に粒度が揃っていると，AI にとっても「UX を 1 つ読めばこの体験は大体わかる」「Feature を 1 つ読めばこの機能のルールは押さえられる」といった 予測可能な単位になる．
その他に「開発ルール」「アーキテクチャ」「環境構築」などのドキュメントも必要だが，これらは特に構造に迷うことはないだろう．
テンプレを作れ
上の 3 つをうまく守るために有効なのがテンプレートを用意しておくことである．運用で頑張るとほぼ死なので，テンプレで縛る．
項目を定めて構造化する
まず，各レイヤごとに 見出しと項目を固定する．
- UX … 目的 / 対象ユーザー / フロー / 完了状態 / 関連画面 …
- Feature … 概要 / 前提条件 / ユースケース / 仕様 / 関連 UX …
- Screen … 画面の目的 / 前提条件 / 主な要素 / 主な操作 / 遷移元・遷移先 / 関連 Feature …
このように形を決めておくことで，作成時には「template.md に沿って書いて」と指示すれば一撃である．人間相手でも一撃である．
また，関連データも含めたといったテンプレにしておくと，AI に「この Feature と紐づいている Screen を列挙して」といった依頼がしやすくなって便利．
書かないことを書く
テンプレには「書くべきこと」だけでなく「書かないこと」も明示しておく．内容の重複を防ぐためである．
例：
- UX / 目的
→ 「※システム内部の仕様やビジネスルールはここには書かない」 - Feature / 仕様
→ 「※画面構成やレイアウトの詳細はここには書かない」 - Screen / 主な要素
→ 「※ビジネスルールの詳細はここには書かず，対応する Feature を参照する」
これを説明文としてテンプレに埋め込んでおくと，結果的に，抜け漏れや SSOT 違反を防ぐことに繋がる．
AI に書かせすぎない
AI に任せるときにありがちなのが，「オタク特有の早口で書きすぎる」問題がある．これを防ぐために，テンプレ側で分量の上限を決めておく．細かく定めなくても，テンプレを箇条書き形式にしておくだけでも十分効果がある．
- UX の目的 … 1〜2 文
- UX の完了状態 … 1〜3 項目
- Feature のユースケース … 最大 5 項目
- Screen の主な要素 … 5〜10 項目 など
テンプレにこういった制約を書き込んでおき，AI には
各セクションの分量制限を厳守してください．
テンプレートにない項目は追加・削除しないでください．
と伝えることで出力が安定する．開発ルールのドキュメントにドキュメント作成ルールとして書いておいても良い．
エンジニアも UX を書こう
テンプレを整えていくと，結果的にエンジニアも UX を書く必要が出てくる構造になる．これは個人的にかなり良い流れだと感じている．
筆者はエンジニアの技能として「UX 設計」が今後必須となっていくと考えている．
なぜエンジニアも UX に触れるべきか
UX / Feature / Screen をリンクさせる前提にすると，
- 新しい Feature を書くときに「対応する UX はどれか」を考えざるを得ない
- Screen を設計するときに「どの UX のどのフローの一部か」を意識する
という状態になる．
つまり，エンジニアがコードを書く前に，
この実装はどのユーザー体験のためのものか？
ユーザーはどんなゴールを達成しようとしているのか？
を自然と考えるようになる．これらはアプリケーションの価値として非常に重要な視点であり，特に少人数の開発ではエンジニア自身が UX を理解し設計することが必要となる．
一人＋ AI 開発での UX ドキュメントの役割
AI に Feature や Screen のたたきを書かせるとき，UX ドキュメントは上位仕様として有効に活用できる．
- ユーザーの目的
- 行動フロー
- 成功条件（完了状態）
がシンプルに書かれているだけで，AI は
- どういう分岐やエラーがありそうか
- どんな画面遷移が必要か
を推論しやすくなる．
一人＋ AI の開発では，UX をエンジニア側である程度書いておくこと自体が AI への良いプロンプトになる感覚がある．逆にエンジニアが UX を想定できていないと「謎のよくわからない機能」や「なんか使いにくい画面」が出てきても対処のしようがなくて困る．UX が定まっていなければ判断ができないからだ．
実務での小さなコツ
実務でできそうな小さな工夫としては，例えば以下である．
- 新しい機能を考えるときは，まず UX テンプレから書き始める（いきなり画面や API を考えない）
- Feature を新規追加するときは，必ずどの UX に紐づくかを明示する
- PR レビューで，「この変更はどの UX / Feature に対応しているか」を一行で書く
こういった小さなルールを決めておくと，自然と「エンジニアも UX を見る / 書く」文化になる．
まとめ
一人＋ AI で開発していくとき，ドキュメントに求めるものは大きく次の 3 つ．
- 抜け漏れがない（網羅性）
UX → Feature → Screen がつながっていること． - SSOT（信頼できる唯一の情報源）
どのレイヤに何を書くかを決めて，重複を避けること． - 粒度を揃えたレイヤー構成
UX / Feature / Screen それぞれの役割と「どこまで書くか」を揃えること．
これらを運用で頑張るのではなくテンプレートという形で先に決めてしまうことで，
- AI に安心して書かせられる
- 読む側も迷わない
- エンジニアも自然と UX から考えるようになる
という状態に近づけることができる．
「自分＋ AI」というチームで開発していると考えると，UX → Feature → Screen の 3 レイヤと，そのためのテンプレ設計はかなりコスパの良い構成だと感じている．エンジニアの今後も含めて．
以上だ( `･ω･)b
Discussion