はじめに
TVer Advent Calendar 2025の19日目を担当するyabukuです。 TVerではフロントエンドのQAを担当しております。
昨日は@tsang-tverさんの『JSConf JP 2025のスポンサーとして登壇しました！』でした。
今回は、最近取り組んでいる生成AI（Claude CodeやCursor）を活用した仕様書作成の自動化について書いていきます。
ドキュメントが「共通言語」になるまで、そして直面した壁
私が入社した当時、プロダクトにはドキュメントがほとんど存在せず、テスト設計に非常に苦労しました。「無いのなら作ってしまおう」とQAチーム主導でテスト設計用の資料を作成し始めました。
時が経ち、その資料はQAだけでなく、PdMやディレクター陣も参照するようになり、いつしか開発プロダクトの共通資料としての地位を確立していました。
しかし、組織の拡大と開発スピードの加速に伴い、ある深刻な問題に直面することになります。それはドキュメント更新コストの増大です。
開発スピードが上がるにつれ、QAチームは目の前の検証タスクで手一杯になり、ドキュメントをメンテする余裕が完全に失われてしまいました。「少し余裕ができたから更新しよう」と思っても、以下のような高い認知的負荷（インプットコスト）が壁となり、作業が進まない状況に陥っていました。
- 情報の点在: 仕様がSlack、Figma、Miroなどに散らばっている
- Fix仕様の不明瞭さ: 議論のスレッドを見つけても、結局どれが最終決定事項なのかが読み取れない
- まとめ方の迷い: 複数のプラットフォーム（PF）をどう統合して記載すべきか悩む
そこで思いついたのが、「Claude CodeやCursorに実装コードを読ませて、ドキュメントを自動生成させる」というアプローチです。
ドキュメント自動生成のスコープ
今回の自動生成プロジェクトのスコープは以下の通りです。
やること
- ドキュメント専用リポジトリの用意: アプリケーションコードとは切り離し、仕様書管理専用のリポジトリを用意して、そこに成果物（Markdownファイル）を作成・蓄積していく運用にしました
- QAチーム品質の仕様書作成: QAチームで運用していた「画面仕様書」と同等の粒度での記載を目指す
- 画面遷移のテキスト化: これまでMiroで図示していた画面遷移情報を、ドキュメント内に記述する
- マルチプラットフォームの統合: 従来はAndroid/iOSで1つ、Web、CTV(コネクテッドTV)とバラバラだったものを、「画面ごと」に全PFの仕様をまとめる形式に変更
イメージ
⏺ Home(Android/iOS/Web/CTV)
⏺ VOD(Android/iOS/Web/CTV)
...etc
やらないこと
- 画面イメージ（スクショ等）の追加（※初期スコープ外)
アプローチ
-
リポジトリの準備
各プラットフォーム（Android, iOS, Web, CTV, Backend）のブランチをクローンし、ドキュメント作成実行時にすべて最新の状態になるよう対応しました。 -
Markdown構成とルールの整備
Claude Codeが迷わないよう、明確な指示書を用意しました。
- テンプレートmd: QAチーム既存の仕様書をベースにしたフォーマット
- 非機能インプットmd: コードからは読み取れない仕様の補足
- rule.md: ドキュメント更新用のルール定義
-
ルールの同期: .cursorrules等の同期ツール（rulesync想定）を導入し、Claude CodeやCursorでも同じルールセットで動けるように整備
- マスターのmd作成後、以下コマンド叩くとClaudeやCursorのルールファイルを生成してくれる
npx rulesync generate --targets cursor,claudecode --features rules,ignore
※rulesyncの詳細はこちら
いざ、自動生成！
成功体験
まずはお試しとして、どのPFにも存在する「Home画面」を作成させてみました。
結果は……かなり良い感じ！ 数回のプロンプト指示だけで、期待通りのドキュメントが出力されました。作業コストはほぼゼロ。「これは神だ、全画面作成も余裕でいける！」と確信しました。
……そう思っていたのは、ここまででした。
ぶつかった壁
調子に乗って他の画面も生成してみたところ、私が想定していたものとは似ても似つかない仕様書が爆誕しました。
問題点
- 認知のズレ: 私（QAチーム）が認知している「画面名」と、Claude Code（コード上のクラス名）の認知が一致していない
- マルチPFの複雑さ: 1つの画面仕様書に全PFの情報を載せる構成にしたため、各PFごとの修正指示が必要となり、修正コストが激増
- 指示の限界: 自然言語でいくら修正を指示しても、思ったような構成にならない
- 再現性のなさ: 1つ修正できて「よし、これだ」と同じようなプロンプトを投げても、別画面では全く異なるアプローチで出力されてしまう
結果として、手動で書くよりも遥かに時間がかかってしまいました。
解決策：認識の同期（Sync）
「とにかく作って」という指示では進まないため、アプローチを変えました。
まず、いきなり仕様書を書かせるのではなく、実装クラス単位で「画面一覧」を作成させるようにしました。これにより、Claude Codeがどのクラスをどう認識しているかを可視化しました。
その上で、「Claude Codeが認識している画面名（クラス名）」と「QAチームが使っている画面名」のマッピング（Sync）を行いました。この工程を経ることで、ようやく対話が成立するようになりました。
今回の反省と学び
Claude Codeを用いたドキュメント自動生成における、現時点での教訓です。
-
まずは「画面一覧」で認識合わせをする
- いきなり詳細を書かせず、コード上のクラスと人間が呼ぶ画面名のマッピング表を最初に作らせることで、その後のハルシネーションや認識齟齬を防げます
-
プロンプトで粘らず rule.md を直す
- 生成結果のアプローチが大きく異なる場合、チャット欄で指示を重ねるのではなく、rule.md（指示書）自体を修正する方が結果的に早くて確実です
-
「まとめて生成」より「それぞれ生成」
- 最初から全PFまとめて1つのmdにするのではなく、各PFごとに仕様書を生成させ、最後にマージするフローの方が高精度に作成できた印象です
イメージ
⏺ Android
⎿ Home
⎿ VOD
⏺ iOS
⎿ Home
⎿ VOD
⏺ common(Android/iOS/Web/CTV)
⎿ Home
⎿ VOD
...etc
-
依存関係の更新ルールも明記する
- ある画面仕様書を更新・作成したら、READMEやリンクされている他画面の仕様書も修正が必要です。これらも人間がやるのではなく、rule.md に更新フローとして組み込むべきでした
今後の展望
「ドキュメント更新コストゼロ」を本気で目指すなら、まだ乗り越えるべき壁があります。
1. 画面イメージの自動生成
現状、スクショの取得・貼り付けは完全に手作業です。E2Eテストで使っているPlaywrightを流用して、画面キャプチャを自動取得→仕様書に埋め込む仕組みを作れないか検討しています。
2. 差分検知による自動更新
今の仕組みでは「いつ更新すべきか」は人間が判断しています。理想は、コードの変更をトリガーに関連する仕様書が自動で更新される（少なくとも更新が必要なことを通知してくれる）状態。CI/CDに組み込めれば、「ドキュメントが腐る」という概念自体をなくせるかもしれません。
どちらも一筋縄ではいかなそうですが、うまくいったらまた記事にしたいと思います。
まとめ
「銀の弾丸」のように思えたAIドキュメント生成ですが、既存の巨大なプロダクトに適用するには、AIと人間のコンテキストの共有が不可欠でした。
しかし、一度型（ルールと辞書）が決まれば強力な武器になることは間違いありません。引き続き、ドキュメント更新コストゼロを目指して改善を続けていきます。
最後に
今回は生成AIでの仕様書自動生成について記載しました。
明日のTVer Advent Calendar 2025の20日目は@tench_ooさんです。