技術選定の理由、即答できますか？AIとの対話で作る設計ドキュメント

この記事は「BEMA Lab Advent Calendar 2025」の9日目の記事です。
※本アドベントカレンダーの9日目の投稿となります。

「半年前に書いた自分のコードは、他人のコードに見える」

エンジニアなら誰しも経験があることではないでしょうか。コードそのもの（What）は残っています。しかし、なぜその実装にしたのか、なぜライブラリAではなくBを選んだのかという「意図（Why）」は、驚くほどきれいに記憶から抜け落ちてしまいます。

記憶喪失は、自分自身だけでなくチーム全体の問題です。
ドキュメントが残っていないシステムを引き継ぎ、「なぜこうなっているのか分からないから、怖くて触れない」という状況に陥ったことはありませんか？

今回は、こうした「意思決定のプロセス」を、AI（LLM）を使って速く、しかも質の高いドキュメントとして残す方法を紹介します。
実際にこの手法を使い、実質10時間程度で約9.5万字（設計書6本、ADR 5本など）のドキュメントを作成しました。
「ドキュメントを書く時間がない」「どう書けばいいか分からない」と悩んでいる方の参考になれば嬉しいです。

※この記事自体も、本稿で紹介するAI活用術（ClaudeとGeminiとの壁打ち）を用いて執筆されています。

現場で起きている「意図の消失」

設計レビューやコードレビューの場で、こんなやり取りをしたことはないでしょうか。

レビュアー：「なぜここでこのフレームワークを選んだのですか？」

担当者：「えっと…なんとなく流行りだからです…」

レビュアー：「他の選択肢と比較検討はしましたか？」

担当者：「……（してない）」

これは極端な例かもしれませんが、似たような冷や汗をかいた経験はないでしょうか。

言葉に詰まってしまうのは、必ずしも考えていなかったからではありません。
検討はしたものの、その思考の過程が言語化・記録されていないために、説得力を持てないのです。

意図が不明確な意思決定は、以下のような問題を引き起こします。

• 手戻りの発生：後から「こっちのほうが良かった」とひっくり返される。
• 属人化と恐怖：決めた本人しか理由を知らず、本人がいなくなると誰も変更できなくなる（塩漬け化）。
• 説明責任の不全：お客様やステークホルダーに対し、論理的な説明ができない。

「ドキュメントが大事」ということは全員が理解しています。
しかし、現実は日々の開発に追われ、丁寧に記録を残す時間はなかなか取れません。

解決策：IPOモデルで「思考」を記録する

ドキュメント作成の時間を短縮するためにAIを使いますが、その前にまず「何を記録すべきか」を整理しましょう。

結論から言うと、記録すべきはすべての意思決定です。
これには、アーキテクチャ決定レコード（ADR）のような技術的な決定だけでなく、開発プロセスのルール（Git運用やリリースフロー）や、機能のスコープ（何を作り、何を作らないか）といった決定も含まれます。
このとき、プログラミングの関数と同じIPOモデルで考えると整理しやすいです。

1.Input（入力）：

前提条件、制約事項、外部調査の結果、背景(文脈)。

2.Process（処理）：

• なぜA案ではなくB案なのか？
• どのような論理ステップで結論に至ったか？

3.Output（出力）：

• 最終的な決定事項。

多くの現場では「Output（結果）」しか残りません。しかし、本当に価値がある資産はProcess（思考過程）と、その前提となったInput（前提条件や調査結果）です。ここさえ残っていれば、前提が変わった時に再考することができます。

実践：AI活用は「丸投げ」と「指示の出しすぎ」の間を狙う

ここからが本題です。このIPOを記録するためにAI（LLM）を使いますが、使い方が重要です。

アンチパターン：丸投げ

「〇〇の設計書書いて」とプロンプト一発で指示するパターンです。

これだと、AIは当たり障りのない、ありきたりな一般論しか出力しません。プロジェクト固有の文脈が反映されず、実用性のないドキュメントになります。修正指示を出すのも大変です。

惜しいパターン：詳細すぎる指示

逆に、人間が最初から「構成はこうで、中身はこうで…」と細かく指示しすぎるパターンです。
これは間違いではありませんが、AIを単なる「清書ツール」として使ってしまっています。
これでは、自分が既に持っている知識や先入観の範囲内でしか出力されません。AIが本来持っている広い知識や、自分が気づいていない視点（スコープ）を活かせず、思考を広げるチャンスを逃してしまいます。

推奨アプローチ：AIに「自分に質問させる」

自分が実践しているのは、広い状態で対話を始め、徐々にスコープを狭めていくアプローチです。
そのための具体的なテクニックが逆質問です。

Step 1： 情報を渡さず、質問させる

いきなり書かせず、以下のように投げかけます。

「バックエンドの言語について決めたい。質問して」

実際はこれくらい雑な指示でも構いません。

こうすると、AIはまず選択肢（Go, Python, TypeScriptなど）を提示しつつ、「将来的なスケーラビリティは？」「パフォーマンス要件は？」「開発後の保守容易性は？」といった観点（スコープの幅）を質問してくれます。

※CLIツールのClaude Codeを使用している場合、CLAUDE.mdやAgent Skillsの設定に「AskUserQuestionツールを使って質問すること」と明記しておくと、対話的に情報を引き出してくれます（デフォルトでは自発的に質問してこないことがあります）。

参考：Agent Skills - Claude Docs

Step 2： 人間が答える・壁打ちする

AIからの質問に対し、人間が答えます。ここで思考の深さを人間が加えます。
自分の中に答えがあるものはそれを伝え、迷っているものはAIに各案のメリット・デメリットを整理させたり、判断の軸となる観点を洗い出させたりします。

Step 3： 飽和するまで繰り返す

質問と回答のキャッチボールを繰り返します。
AIから「これ以上の質問はありません。情報は揃いました」という反応が出たら、Process（論理）とInput（材料）が固まったということです。

Step 4： 出力とセルフレビュー

ここで初めて「今の内容をまとめて」と指示し、ドキュメントを出力させます。
出力されたものは、そのまま完成品ではありません。GitHub等でPull Request（PR）を作成し、プレビュー画面で読み返してセルフレビューを行います。具体的には、以下の点に注目してチェックします。

• 意図の確認： 自分の意図と言語化された内容が合致しているか。
• AIのクセの除去： 「体言止め」の多用や、過剰な強調など、AI特有の書き味を修正し、読みやすく整えます。

違和感があれば、手動で直すか、AIに指示して修正させます。

成果：実質10時間で9.5万字のドキュメント

この手法の最大のメリットは、壁打ちのログがそのままドキュメントの核になることです。思考の整理が終わった時点で、ドキュメントの骨子はすでに完成しています。

実際に、CLIツールのClaude Codeなどを活用し、以下のドキュメントを実質10時間程度の作業で作成しました。

これだけの量を人間だけでゼロから書こうとすれば、数倍の時間はかかっていたでしょう。しかも、内容はAIとの対話によってブラッシュアップされており、論理構成もしっかりしたものになっています。

対話の過程も含めるため文章量は多くなりますが、論理の飛躍が少ないため、読み手にとってはむしろ理解しやすい内容になります。

チームメンバーにレビューしてもらう際も、「なぜ」が明確に書かれているため、レビューの質も速度も大きく向上します。
もしレビュアーから「判断の軸がわからない」といった指摘があれば、それはProcessの記述不足です。その指摘を元に再びAIと壁打ちし、ドキュメントを補強すればよいのです。

まとめ：AIは思考の「幅」を広げるツール

「AIにドキュメントを書かせると、エンジニアが思考停止するのではないか？」という懸念を聞くことがありますが、実際は使い方次第です。

AIに「丸投げ」すると思考停止になります。しかし、上記のように対話的に使うなら、AIは思考の幅を強制的に広げてくれる良いパートナーになります。自分一人では見落としていたリスクや選択肢を提示してくれるからです。

その広がった選択肢の中から、最終的にプロジェクトの文脈に合わせて決断する（深さを決める）のは、人間の役割です。

「なぜこの設計にしたの？」と聞かれたとき、自信を持って答えられるように。
次の技術選定では、ぜひAIに「何を決めるべきか、自分に質問して」と話しかけてみてください。