はじめに
OneNoteで要求仕様書や設計書を書いているプロジェクトがある、という話を聞きました。
「それ、設計書として成立するの？」と思いながらも、ふと気づきました。
そもそも設計書って、何の情報があればいいんだろう、と。
フォーマットや記法の話になりがちですが、突き詰めると「開発者が必要な情報を受け取れるか」に尽きるはずです。
OneNoteで成立している以上、必要な情報が揃っているなら問題ないはず。
そういう経緯で今回、自分が設計部門にいたときの経験をもとに、設計アウトプットに本当に必要なものを整理したうえで、
OneNoteで成立させるにはどう考えればいいかを考えてみました。
OneNoteの特性
まずOneNoteってどういうツールか、という話から。
印象としては、とにかく自由に記載できるってところだと思います。
ページ内のどこでも書けるし、ファイルも添付できるし、すぐに共有できる。
ページをまたぐ検索もできるので、独自用語が出てきてもすぐに内容を探せます。
探索的な思考ツールとしてはとても優秀です。
OneNoteの強み：
- 自由なレイアウト
- リアルタイム共同編集
- 検索性の高さ
- ファイル添付が容易
アイデアを練る段階ではかなり便利です。
一方で、弱点もあります。
OneNoteの弱いところ：
- 同期ズレが起きる（複数人で編集すると、更新がすぐに反映されず、誰かの更新の上に別の人が更新をかけてしまうことがある）
- バージョン管理が弱い
- ベースラインを自然に固定できない
- 変更履歴が構造化されにくい
- 差分管理が難しい
特に同期ズレは、複数人で作業するときに結構デカい問題だと思います。
設計アウトプットに必要な要素
次に、そもそも設計のアウトプットとして何が必要なのかを整理してみます。
自分が経験したことを基に考えたとき、設計者側と開発者側で少し視点が違うと感じています。
設計者側として必要なもの
設計者としては、以下のあたりが必要になります。
（いくつかは内部フロー的に必要になるものかもしれませんが）
- トレーサビリティ：どの機能がどの要件・要求に基づいているものか
- バージョン情報：いつ開発側にインプットした内容か（試験するときの対応付け）
-
責任範囲：各処理ごとの入出力や条件分岐などを誰がどこでやるのか
- 自分のいた部署だと、ユーザーやIoT機器、クラウド由来のデータと多岐にわたったので、誰がエラーを出しうるのかを整理する必要がありました
開発者側が欲しい情報
一方、開発者側が欲しい情報としては以下になるかなと考えました。
- バージョン情報：いつインプットされた内容か（試験との対応づけ）
- 変更履歴：前回のインプットから何が変更されているか（差分対応）
-
責任範囲：各処理ごとの入出力や条件分岐などを誰がどこでやるのか
- どういう入力でどういう出力になっている必要があるか、単体・結合試験するためにも必要
- 検討と確定の分離：検討中の内容と確定仕様がはっきりしていること
私が設計部門にいたときに開発者サイドの人から「責任範囲の箇所を中心に書いてほしい。フォーマットなら正直シーケンス図をベースにノートで入出力や制約を詳細に書いてくれれば文章じゃなくてもいい」と言われました。
開発者が重視しているのは「フォーマット」ではなく「必要な情報が受け取れるかどうか」です。つまり、設計書は必ずしも文章である必要はなく、必要な情報が伝わればいいということです。
整理すると
以下の表は、開発者が特に優先する情報（バージョン情報・変更履歴）を先頭に、設計者側・開発者側それぞれの必要度と合わせて整理しています（○：必要、△：間接的に必要）。
| 要素 | 設計の性質 | 設計者側 | 開発者側 | なぜ必要か | 具体的には |
|---|---|---|---|---|---|
| バージョン情報 | 状態 | ○ | ○ | 「どの仕様で実装するのか」が曖昧だと開発者の負荷が高く、試験の基準も揺れる | 版数管理（v1.0, v1.1...）、確定仕様を固定する仕組み |
| 変更履歴 | 履歴 | △ | ○ | 設計の経緯が分からず、影響範囲も読めない。「言った/言わない」問題が起きる | 変更日時・変更者・変更理由、差分の把握 |
| トレーサビリティ | 関係性 | ○ | △ | 要求が実装されたか説明できず、試験項目の根拠も不明確になる | 要求ID、設計項目との紐づけ、試験項目との紐づけ |
| 責任範囲 | 境界 | ○ | ○ | 境界が曖昧だと機能が肥大化し、変更影響範囲が読めなくなる | インターフェース定義、事前条件・事後条件、「やること／やらないこと」の明示 |
| 検討と確定の分離 | 状態 | △ | ○ | 混在すると実装者が迷い、「これ最新版？」問題が発生する | 検討ログと確定仕様の分離、ステータス管理 |
つまり、開発者が「何をいつの仕様で実装・試験するか」を把握できる情報が整っているなら、フォーマットを問わず設計アウトプットとして成立します。
実際、GitHubのプルリクエストやIssuesで管理している現場もあります。PRのdescriptionに要求ID、レビューコメントで設計議論、commitで変更履歴。これらが揃えば、設計アウトプットとして成立します。
（ただし製品開発であればリリースのためのドキュメントが必要なので、正式なものは当然必要です）
上の表の「設計の性質」列にあるように、設計書とは「状態・履歴・関係性・境界」という4つの性質を持った構造化された情報だと考えています。
OneNoteで設計するなら考えておきたいこと
ここまでを踏まえて、もしOneNoteでこれらの要素を実現するとしたら、自分だったら何が気になるかを考えてみます。
懸念点を整理すると、大きく2つのカテゴリに分けられます。
二度手間について：
- リリース前に正式文書化するなら、結局二度手間にならないか？
版管理・ベースラインについて：
- いつのバージョンをもとにリリースしているのか分からなくならないか？
- 試験仕様書は何をベースに作るのか曖昧にならないか？
- バージョン管理は本当に正確にできるのか？
以降でそれぞれを深掘りします。
二度手間のリスク
OneNoteは時系列や議論ベースで書きやすいので、検討フェーズで「この要件からこの機能が必要」みたいな整理はやりやすそうです。
要求・要件のファイルを張り付けて「この要件から来てます」とかも共有しやすい。
ただ、設計のアウトプットとして考えると、やはり正式な設計書は「論理構造」で書く必要があります。
もしOneNoteでの検討ログ（時系列・議論ベース）と、正式設計書に必要な論理構造を意識せずに書き続けると、
リリース前に「論理構造への変換作業」が発生する可能性が高いです。
版管理・運用で気になるところ
OneNoteは更新しやすいツールです。
それ自体は便利なんですが、ルールが曖昧だと、こんなことが起きそうです。
- ページが更新され続けて、どれが確定版か分からなくなる
- 「これ最新版？」問題が発生する
- チャットや口頭の補足が反映されない
- 誰も全体像を説明できなくなる
更新しやすいということは、責務や境界も静かに変わり得るということ。
その変化が見えにくいのが、一番のリスクだと思います。
OneNoteで設計を成立させるには
前節で挙げた懸念に対して、どう対処するかを整理します。
検討と確定を分離するには
- 最初から「論理構造」を意識して書く
- ラフな議論は別セクションに分け、確定仕様は都度整理する運用にする
- ここまでやるなら個人的には最初からConfluenceやMarkdown + Git、要求管理ツールを選ぶかもしれない
バージョン情報を管理するには
- 確定時にPDF化して別管理する
- ページタイトルに版数を付与する（例：「認証機能設計 v1.0」）
- 確定版セクションを作り、編集ルールを決める
変更履歴を記録するには
- 変更管理表を別途持つ
- 変更日時・変更者・変更理由を記録する運用を定める
- 変更前後の差分（何が変わったか）を明記する
トレーサビリティを確保するには
- 要求IDを必須項目にする
- タグ機能を活用する
- Excelなどの要求管理表と連携する
- 試験項目表に設計項目IDを記載する
境界・責任範囲を守るには（テンプレート化）
- 最初から構造化テンプレートで書く（自由度が高いからこそ）
- 必須項目を定義する：要求ID、設計ID、責務、責務外、インターフェース、制約条件
- 「やること／やらないこと」を必ず明示する
まとめ
OneNoteは設計アウトプットとして使えはします。
ただし、誰でも更新しやすいツールなので構造を維持する仕組みが必要だと思います。
重要なのは、前節の各工夫がそれぞれ機能することで、以下が担保できているかどうかだと考えます。
- ベースラインが固定できるか（バージョン情報：版数管理・確定仕様の固定）
- 変更履歴が追えるか（変更履歴：変更管理表の運用）
- トレーサビリティが確保できるか（トレーサビリティ：要求ID管理）
- 責任範囲の境界が守られているか（責任範囲：テンプレートによる必須項目の定義）
- 検討と確定が分離できているか（検討と確定の分離：確定版セクション・ステータス管理）
これらが揃っていれば、OneNoteでも成立します。
小規模でアジャイルな開発なら選択肢の一つ。
大規模や長期保守が必要なら、より構造化されたツールを自分は選択するかなと思います。
補足：OneNoteが向いているケース・向いていないケース
せっかくなので補足として、どういう場合ならOneNoteが設計アウトプットとして使いやすいのかを考えてみました。
設計者と開発者が同じ方向を向いてプロジェクトを進めるような体制、たとえばスクラムやアジャイルのチームであれば、OneNoteの共有しやすさや更新のしやすさはかなり活きると思います。
内部の情報共有ツールとしてはかなり優秀なので、チーム内で認識を揃えながら進める用途には向いている。
一方で、外注先やベンダーなど外部が入ってくると、OneNote上の暗黙的な文脈が共有しづらくなるので、そこは注意が必要かなと感じます。
| 観点 | 向いている | 向いていない |
|---|---|---|
| プロジェクト規模 | 小規模（数人規模） | 大規模プロジェクト |
| 開発フェーズ | 探索的な設計フェーズ、プロトタイピング段階 | 長期保守が必要なシステム |
| 品質保証 | 厳格な品質保証が不要な場合 | 厳格なバージョン管理が必要、契約ベースの開発 |
| 組織体制 | チーム内での迅速な情報共有 | 複数ベンダー間での仕様共有 |
| 技術基盤 | CI/CDや自動テストが充実している環境 | CI/CDや自動テストが十分でない環境 |
補足：品質保証の観点から
まとめの「向いていないケース」で技術基盤に触れましたが、ここではその背景にある品質保証の考え方を補足します。
少し抽象的な話になりますが、品質を支える手段は大きく3つあると考えています。
- コードで担保（テスト文化、CI、静的解析）
- プロセスで担保（ベースライン管理、変更管理）
- ドキュメントで担保（明確な仕様、トレーサビリティ）
CI/CDが強い組織は①が強く、ウォーターフォール寄りは②③が強い傾向があります。
もし①が弱く、②も曖昧で、③もドキュメント基盤が弱い状態だと、
リスクが高いかなと思います。
つまり、技術基盤がしっかりしている環境なら、OneNoteの弱点を他でカバーできる可能性がありますが、そうでない環境では慎重になるべきだと思います。
余談：実際の現場の声
最後に、本記事の議論をきっかけに、実際にOneNoteを使っているプロジェクトの関係者に聞いてみた話を紹介します。
実務者（設計・試験担当者）の視点では、試験書や試験環境、条件の調整方法など、普段分散しがちな情報を一箇所に集約できるのが便利とのこと。情報共有ツールとしての評価は高いようです。
一方で、管理者の視点では変更履歴が管理しきれないので、できれば別のツールに移行したいという声もありました。
やはり、内部の情報共有には向いているけれど、設計アウトプットとしては積極的に選びたいツールではない、というのが現場の温度感のようです。
ちなみに、MarkdownなどテキストベースのフォーマットのほうがLLM的には読みやすいという話もしたのですが、最近は生成AIの発展でバイナリ形式のファイルも読み取れるようになってきているので、AIに設計内容を読み取らせるという観点ではOneNoteでも問題にならないかもしれない、とのことでした。
また、Microsoft 365 CopilotがOneNoteに対応しており、ノートの要約やコンテンツ生成、質問応答などができるようになっています。設計内容の整理や確認にCopilotを活用できるなら、OneNoteの弱点をAIで補うという選択肢も今後はありかもしれません。