はじめに
レビューに出した設計書が、一発で通ることはほとんどありません。
自分ではきちんと書いたつもりなんですが、いざレビューに回すと「異常系の挙動は？」「この画面の権限はどうなるの？」といった指摘が毎回5〜6件は返ってきます。しかもその半分くらいは、言われてみれば当たり前の抜けで、自分でも気づけたはずのものなんですよね。
厄介なのは、指摘のたびにレビュアーとの往復が発生することです。1件直して、また見てもらって、別の抜けを指摘されて。これを繰り返していると、1本の設計書がレビューを通るまでに2〜3日かかることもざらでした。
この記事では、その「自分では気づけない抜け」を、人に見せる前に洗い出すやり方を紹介します。使うのは、ONES.comの次の2つです。
- ONES Wiki：仕様書や設計書などのドキュメントを書いて貯めておける、ナレッジベース管理のツールです。今回は、ここに設計書を書いている前提で話を進めます。
- ONES Assistant：ONESの画面に組み込まれたAIアシスタントです。今開いているページの内容を読み取って、質問に答えたり、気になる点を指摘したりしてくれます。
✍️ コツは「観点」を渡すこと
やり方はシンプルです。設計書をONES Wikiのページに書いたら、そのページを開いた状態でONES Assistantを呼び出します。
ただ、ここで一つだけコツがあります。「レビューして」とだけ頼まないことです。漠然と頼むと、返ってくる指摘も「全体的に問題なさそうです」くらいの漠然としたものになりがちなんですよね。
代わりに、チェックしてほしい観点を具体的に渡します。わたしがいつも使っているのは、こんな依頼文です。
この設計書を、次の観点でレビューして、抜けや曖昧な点を指摘してください。
- 異常系・エラー時の挙動が書かれているか
- 用語や略語の定義が本文にあるか
- 権限やロールごとの扱いが明記されているか
- 上限・境界値（件数、文字数、期間など）が決まっているか
- 他の機能やデータとの依存関係が書かれているか
こう頼むと、観点ごとに「異常系の記述が見当たりません」「"リマインド" の定義が本文にありません」といった形で、具体的に返ってきます。ONES Assistantは今どのページを開いているかを自分で判断してくれるので、文章を貼り付け直す必要もありません。
📋 観点リストは、育てると効く
この観点リスト、一度作っておけば毎回使い回せます。
おすすめは、レビューで実際に指摘された内容を、少しずつこのリストに足していくことです。「今回は非機能要件が抜けてた」「ログの仕様を聞かれた」といった指摘を項目として蓄積していくと、レビュアーの指摘傾向が、そのまま自分専用のセルフチェックリストになっていきます。
チームで設計書のテンプレートが決まっているなら、その見出しを観点として渡すのもいい方法です。書いた設計書がテンプレートの項目をちゃんと埋められているか、出す前に自分で確認できます。
返ってきた指摘を見て、明らかな抜けはその場で埋めておく。それから人のレビューに回す。この流れに変えてから、レビューの景色がずいぶん変わりました。
⏱ 指摘の往復が、ぐっと減った
効果はけっこうはっきり出ました。
いちばん大きいのは、レビューでの指摘件数が減ったことです。以前は毎回5〜6件返ってきていたのが、事前に自分で半分ほど潰せるようになったので、人からの指摘は2〜3件くらいに落ち着きました。
指摘が減れば、往復も減ります。前は2〜3日かかっていたレビューが、1往復で終わることも増えてきました。レビュアーにとっても、細かい抜けの指摘に時間を取られず、設計の中身そのものを見てもらえるようになったのは大きいと思います。
⚠️ AIに任せきりにできないところ
とはいえ、これでレビューがいらなくなるわけではありません。
ONES Assistantが読めるのは、あくまでページに書いてある内容だけです。頭の中にあるだけでまだ書いていない前提や、他のページにある背景までは拾ってくれません。「なぜこの設計にしたのか」という判断の妥当性も、AIが評価できる範囲を超えています。
なので、あくまで「形式的な抜けや曖昧さの一次チェック」と割り切るのがちょうどいいです。細かい抜けはAIに拾ってもらって、設計そのものの良し悪しは人のレビューでじっくり見てもらう。この役割分担を意識しています。
おわりに
書いた本人が気づけない抜けを、人に指摘される前に自分で拾えるようになったのは、想像以上に気が楽です。レビューが「粗探し」ではなく「中身の議論」に変わっていく感覚があります。
まずは観点を3つか4つ書き出して、次の設計書で試してみてください。それだけでも、返ってくる指摘の具体さがだいぶ変わるはずです。
もし手元にドキュメントを貯める場所から用意したいという方は、ONES.com を覗いてみてください。