分析アプリの出力をそのまま設計書にする「ゼロ追記設計」

設計書を「新規で書く」のが当たり前だと思っていました。AIで分析した結果が手元にある中で、「設計書を書き起こす必要がある」と言われた瞬間、何かがおかしいと感じました。

設計書、ゼロから書き起こしていませんか？

設計フェーズに入ると、こんな経験はないでしょうか。

• ジョブスケジューラーの実行定義はすでにある。でも「設計書として正式なものが必要」と言われ、Excelに転記する

• 分析ツールがジョブの処理フローを画面で見せてくれている。でも「設計書に落とさないと」とWordで書き直す

• 書き直した設計書が、1ヶ月後には現場の実態と乖離し始める

時間が足りないわけではありません。一件ずつ対応すれば、いつかは終わります。ただ、「すでに存在する情報を、別の形式で書き直す」という作業に何時間も費やしているのが実態でした。

"設計書"を作る日に気づいたこと

あるレガシー改修プロジェクトで、設計フェーズの開始とともにジョブ定義の設計書を用意することになりました。前段の分析フェーズの結果をアプリ化したジョブ分析画面には、ジョブの処理フローや依存関係、実行条件がすでに整理されていました。

この案件向けに「設計書フォーマットで書き起こす必要がある」という会話をしたとき、ふと思いました。「これ、書き直す必要があるのだろうか？」と。

「書く」から「生かす」へ

あのとき見えていなかったのは、 設計書の目的 でした。設計書は「決まっている仕様を記録するもの」であり、「新たに情報を生み出す作業」ではありません。分析アプリがすでに情報を整理してくれているなら、それを設計書として扱えばいい。

この発想の転換から生まれたのが、「ゼロ追記設計」というアプローチです。

ゼロ追記設計の3つのステップ

• ステップ1: 分析アプリの出力をマークダウン化する:

ジョブ分析画面の情報をマークダウン形式に変換します。手動でもよいですが、ジョブ分析画面のスクリーンショットや出力テキストをLLMに貼り付け「この画面情報をマークダウンにしてください」と依頼すると、一瞬で変換できます

• ステップ2: 不足項目は分析アプリ側に追加する:

マークダウンを見て「この情報が足りない」と気づいたら、設計書に追記するのではなく、分析アプリ側の項目を追加します。そうすると次回以降、同じ情報が自動で揃います

• ステップ3: 設計書はマークダウンで管理する:

Excelのような独自フォーマットではなく、マークダウンをそのまま設計書として運用します。GitやConfluenceと相性がよく、差分管理もできます

この流れを一度回してしまえば、次のプロジェクトでは「分析アプリを動かして、マークダウンを出力して完了」という状態になります。

「書き直し」が生む乖離のしくみ

設計書を手で書き直す方式には、構造的な問題があります。

• 書いた時点で正しい、でも翌月は不明:
  システムが変わるたびに設計書も更新しないといけませんが、現実には追いつきません

• ツールと設計書が二重管理になる:
  分析ツールが正、設計書が正、どちらが最新かわからない状態が生まれます

• 更新コストが高いから誰も更新しない:
  結果として、設計書は「参照しても信用できない資料」になっていきます

ゼロ追記設計なら、この問題を根本から回避できます。情報の一次ソースは分析アプリだけで、設計書はその出力を変換したものに過ぎません。分析アプリが更新されれば、設計書も更新できます。

自分が実践していること

実際のプロジェクトでの手順を共有します。

まず確認するのは、次の3点です。

• 分析アプリは何を持っているか:
  ジョブ定義、処理フロー、実行条件、依存関係など、設計書に必要な情報がどこまで揃っているかを確認します

• マークダウンで欠けているのは何か:
  出力したマークダウンを見て、補足が必要な箇所（特殊なシーケンスや運用上の注意点など）をリストアップします

• 不足を補う場所はどこか:
  マークダウンに直接追記するのではなく、分析アプリに項目を追加できるかどうかを優先して検討します

自分の状況に当てはめる問い

自分のプロジェクトを振り返るときに使える問いがあります。この問いは、自分がゼロ追記設計を実践する中で実際に詰まった箇所から生まれたものです。

• 今使っている分析ツールやLLMは、どんな情報を出力しているか？

• その出力を設計書として使えない理由は何か？ フォーマット？ 承認プロセス？

• 「不足を感じたとき、ツール側を改善する」という発想を試したことがあるか？

• 設計書とソースコード・ツールが二重管理になっている箇所は、どこにあるか？

設計書に「書く」という前提を疑ってみる

分析アプリのアウトプットをそのまま設計書にするという発想は、「設計書は新規で書くもの」という暗黙の前提への問いかけです。

すでに整理されている情報を、もう一度手で書き直す理由はどこにあるのか。そのコストは、誰かが正当化しているのか。

あなたのチームに、「これ、書き直さなくていいのでは」と思える作業はありますか。