#16 巨大な仕様書を"読ませたら"負けーーSSoTから生成する「読む人専用ビュー」

巨大な仕様書を全員に「読ませる」運用は、もう負けかもしれません。今回のテーマはSSoT（Single Source of Truth＝信頼できる唯一の情報源）。信頼できる唯一の仕様書を一つだけ管理し、そこからCS担当者向け・パートナー企業向けなど、読む人ごとに最適化された「専用ビュー」を自動生成するという仕様書運用の考え方を深掘りします。

スーパーエンジニアのkuniwakが、巨大なシーケンス図・状態遷移図から必要な部分だけを畳んで見せる仕組みや、GitHub Actionsで日本語の仕様書から英語版を自動翻訳するパイプラインなど、実際の現場で運用している実例を紹介。

「ドキュメントが腐る」あるあるを、コミットごとの自動生成と生成AIでどう解決するのかが具体的にわかります。後半は仕様記述の理論的バックグラウンドへ。

契約による設計（Design by Contract）の事前条件・事後条件、「アサートを書けばいいんでしょ」というよくある誤解、ホーア論理からBDDまで、へんてこの質問でゆるく噛み砕いていきます。

▼この回で話していること

・SSoT（信頼できる唯一の情報源）とは？仕様書運用への応用

・巨大なシーケンス図・状態遷移図から「読む人専用ビュー」を自動生成する仕組み

・ドキュメントが腐る問題を防ぐ、コミットごとの自動生成と自動英訳パイプライン

・C4モデルのコンテキスト図とシーケンス図の整合性をツールで検証する実例

・仕様記述の専門家「マニピュレーター」という役割と、AI・スキル化による代替

・契約による設計（Design by Contract / DbC）とは？事前条件・事後条件とアサートの正しい理解

・RESTful APIの404は事前条件違反ではない？契約による設計でAPI仕様を読み解く

・巨大ドキュメントをLLMにそのまま読ませる vs 読む人ごとにビューを分ける

▼こんな人におすすめ

・仕様書や社内ドキュメントが「腐る」問題に悩んでいるエンジニア・PM

・契約による設計（DbC）を名前だけ知っていて、正しい理解を手に入れたい人

・生成AI時代の仕様書・ドキュメント運用の実践例を知りたい人

▼関連リンク

・信頼できる唯一の情報源（Wikipedia）: https://ja.wikipedia.org/wiki/信頼できる唯一の情報源

・C4 model: https://c4model.com/

・PlantUML: https://plantuml.com/ja/

・契約プログラミング（Wikipedia）: https://ja.wikipedia.org/wiki/契約プログラミング

・ホーア論理（Wikipedia）: https://ja.wikipedia.org/wiki/ホーア論理

くわラジ（もっと詳しく教えてくださいラジオ）は、スーパーエンジニアのkuniwakに一般エンジニアのへんてこが「もっと詳しく教えてください」と質問しながら技術を深掘りする、ゆるくてディープな技術雑談番組です。

─────────────

YouTube: https://youtu.be/pLIjwXXqGW4

Web: https://kuwa-raji.henteko07.com/

X: https://x.com/kuwa_raji