仕様書作成をClaude Codeで効率化する方法｜コードから設計意図を整理する

仕様書が残っていない、または古くなっている既存システムでは、改修や保守の前に「コードが何をしているのか」を読み解く必要があります。処理の流れ、入力値、出力結果、例外処理を確認しながら仕様書へ落とし込む作業は、担当者の経験にも左右されやすい工程です。

Claude Codeは、コードベースの読み取り、ファイル編集、コマンド実行、開発ツールとの連携に対応したコーディング支援ツールです。
そのため、仕様書作成の前段階にあるコード理解や情報整理にも応用できます。
ただし、Claude Codeに任せれば正確な仕様書が自動で完成するわけではありません。コード上の事実と、設計意図として推測される内容を分けることが重要です。

この記事では、Claude Codeで仕様書作成を効率化し、コードから設計意図を整理するための手順を解説します。

Claude Codeで仕様書作成はどこまで効率化できるのか

Claude Codeを仕様書作成に使う目的は、文章作成を丸投げすることではありません。既存コードの構造を把握し、処理内容を整理し、仕様書に転用しやすい形へ整える作業を効率化することです。

仕様書作成そのものではなく、コード理解と整理を支援する

仕様書作成で時間がかかるのは、文章を書く作業だけではありません。対象機能がどのファイルに分かれ、どの関数がどの処理を担い、どの条件で分岐するのかを読み解く作業も必要です。

Claude Codeを使えば、対象ディレクトリの役割や入力・処理・出力の流れを整理し、仕様理解のたたき台を作れます。

既存コードから整理しやすい情報

既存コードから整理しやすいのは、コード上に明示されている情報です。関数やクラスの役割、入出力、バリデーション、分岐条件、エラーハンドリング、API連携、データベース操作などは、仕様書に落とし込みやすい要素です。画面処理であれば、フォーム項目、入力チェック、ボタン押下時の処理、表示条件なども整理できます。

コードだけでは判断しにくい情報

一方で、コードだけでは判断しにくい情報もあります。なぜその仕様になったのか、過去にどのような業務要件があったのか、例外処理がどの運用を想定しているのかといった背景は、コード上に明確に残っていないことがあります。
コードから分かるのは、あくまで現時点の実装仕様です。本来あるべき業務仕様や設計判断は、既存ドキュメントや担当者への確認を通して確定します。

仕様書作成の前に整理すべき前提

Claude Codeを使う前に、仕様書作成の目的と範囲を決めておく必要があります。前提が曖昧なまま依頼すると、出力内容が広がりすぎたり、確認観点が抜けたりしやすくなります。

対象範囲を決める

まず、どの機能を仕様書化するのかを明確にします。画面単位、API単位、バッチ処理単位、モジュール単位など、対象範囲を区切ることで、Claude Codeに依頼する内容も具体化できます。
「このシステムの仕様を整理して」ではなく、「注文登録画面の入力項目、登録処理、エラー時の挙動を整理してください」のように依頼します。

出力したい仕様書の種類を決める

仕様書といっても、目的によって必要な情報は異なります。画面仕様書であれば項目定義や表示条件、API仕様書であればエンドポイント、リクエスト、レスポンス、ステータスコードが中心になります。
最初に「機能概要」「処理フロー」「入力項目」「例外処理」「確認事項」などの見出しを指定すると、後から整えやすくなります。

CLAUDE.mdなどでプロジェクト前提を共有する

プロジェクト固有のルールがある場合は、CLAUDE.mdなどに整理しておくと、Claude Codeに前提を共有しやすくなります。
命名規則、ディレクトリ構成、出力フォーマット、禁止事項などを記載しておくことで、出力のぶれを抑えやすくなります。
ただし、CLAUDE.mdは前提を伝えるためのコンテキストであり、動作を強制する設定ではありません。重要なルールはプロンプトでも明示し、出力後に人が確認します。

Claude Codeでコードから仕様を整理する基本手順

仕様書作成を効率化するには、いきなり完成版を書かせるのではなく、段階的に整理することが重要です。
コード構造、処理フロー、仕様書のたたき台、レビュー項目の順に進めると、出力結果を確認しやすくなります。

まずコード構造を把握させる

最初の依頼では、対象ファイルやディレクトリの役割を整理させます。どのファイルが画面表示、業務ロジック、データベース連携を担うのかを把握する段階です。
細かい仕様に入る前に全体像を作ることで、依存関係や処理順序を確認しやすくなります。

処理フローを段階的に整理する

次に、処理フローを整理します。入力、前提条件、主処理、分岐、出力、例外処理を分けると、仕様書に転用しやすい形になります。
複雑な処理では、正常系、異常系、外部連携に分けると確認しやすくなります。特に分岐条件やエラー時の挙動は、仕様書で抜けやすい部分です。

仕様書のたたき台に変換する

コード構造と処理フローを整理したら、仕様書の形式に変換します。機能概要、入力項目、処理内容、出力内容、エラー時の挙動、確認事項といった見出しを指定すると扱いやすくなります。
最初から完成度の高い文章を求めるよりも、人が補足・修正しやすいたたき台にする方が実務では使いやすくなります。

不明点とレビュー項目を一覧化する

仕様書のたたき台を作った後は、不明点とレビュー項目を一覧化します。根拠が弱い記述や業務担当者に確認すべき点を分けて出力させます。
この工程により、推測をそのまま仕様として固定するリスクを抑えられます。

レビューでは、既存ドキュメント、テストコード、画面挙動、担当者の知識を照合します。

設計意図を整理するためのプロンプト設計

設計意図を整理する場合は、プロンプトの設計が特に重要です。Claude Codeに「なぜこうなっているのか」を断定させるのではなく、事実、推測、確認事項を分けて整理させます。

事実と推測を分けて出力させる

設計意図は、コードだけから完全に復元できるとは限りません。そのため、出力条件として「コードから確認できる事実」「設計意図として推測されること」「人による確認が必要なこと」を分けるように指定します。

プロンプト例：

「対象ファイルを確認し、処理内容を仕様書向けに整理してください。コード上で確認できる事実、設計意図として推測される内容、確認が必要な不明点を分けて出力してください。推測は断定せず、根拠となるコード箇所も示してください。」

処理の理由を観点別に整理させる

設計意図を整理する際は、「何をしているか」だけでなく、「なぜその処理が必要なのか」を観点別に分けます。分岐条件、例外処理、責務分担、依存関係、命名など、観点を指定すると出力の粒度が安定します。

ただし、理由の説明には推測が含まれる場合があります。設計者の判断や過去の業務要件は、既存資料や関係者への確認と組み合わせて確定します。

仕様書向けの出力形式を指定する

Claude Codeに依頼する際は、出力形式も明確にします。機能概要、処理フロー、入力、出力、例外処理、設計意図、確認事項という見出しを指定すると、仕様書に転用しやすくなります。
また、「曖昧な表現を避ける」「推測には推測と明記する」「レビュー対象の項目を最後にまとめる」といった条件を入れると、後工程の確認がしやすくなります。

仕様書作成で使えるプロンプト例

実際にClaude Codeを使う際は、目的別にプロンプトを分けると扱いやすくなります。コード構造、処理フロー、設計意図、レビュー観点を分けることで、出力の目的が明確になります。

コード構造を把握するプロンプト

「この機能に関係する主要ファイルを確認し、それぞれの役割を整理してください。画面表示、業務ロジック、データアクセス、外部連携、共通処理に分けて、仕様書作成の前提として使える形でまとめてください。」

処理フローを整理するプロンプト

「対象処理について、入力、前提条件、主処理、分岐条件、出力、エラー時の挙動に分けて整理してください。コード上で確認できる内容を優先し、不明点は確認事項として分けてください。」

設計意図を整理するプロンプト

「このコードから読み取れる設計意図を整理してください。ただし、コード上の事実、設計意図として推測される内容、確認が必要な点を必ず分けてください。推測は断定せず、根拠となる処理や構造をあわせて示してください。」

レビュー観点を抽出するプロンプト

「作成した仕様書のたたき台について、コードとの不整合が起こりやすい箇所、業務仕様として確認が必要な箇所、表現が曖昧な箇所を一覧化してください。確認方法も、コード確認、テスト、既存資料、担当者確認に分けて提案してください。」

Claude Codeで仕様書作成を効率化する際の注意点

Claude Codeは仕様書作成の負担を減らせますが、使い方を誤ると、誤った仕様が文書として残るリスクもあります。効率化と正確性を両立するには、出力結果を必ず検証する前提で運用する必要があります。

出力結果を完成版として扱わない

Claude Codeの出力は、完成版ではなくたたき台です。
コードの読み違い、前提不足、推測の混入が起こり得ます。共有前に、対象コードとの整合性、画面やAPIの実際の挙動、テスト結果、既存ドキュメントとの違いを確認します。
特に、設計意図や業務仕様に関する記述は慎重に扱う必要があります。

実装仕様と業務仕様を混同しない

コードに書かれている内容は、現在の実装仕様です。しかし、それが本来の業務仕様と一致しているとは限りません。
過去の暫定対応、例外的な運用、未整理の改修がコードに残っている場合もあります。そのため、Claude Codeで整理した内容は、業務担当者や設計者の確認を通して確定する必要があります。

セキュリティと機密情報の扱いに注意する

仕様書作成では、ソースコード、API情報、データ項目、認証処理など、機密性の高い情報を扱う可能性があります。
Claude Codeを利用する際は、社内ルール、利用環境、権限範囲、取り扱ってよい情報を事前に確認する必要があります。効率化だけを優先せず、情報管理のルールに沿って運用します。

検証フローを用意してから活用する

Claude Codeを仕様書作成に組み込むなら、出力後の検証フローを先に決めておくべきです。確認担当者、確認根拠、修正履歴の残し方を決めておくと、誤った仕様がチーム内に広がるリスクを抑えられます。重要なのは、Claude Codeの出力を起点にしながら、最終判断は人が行う流れを作ることです。

まとめ：Claude Codeは仕様書作成の負担を減らすが、設計判断の代替にはならない

Claude Codeを活用すれば、既存コードの構造把握、処理フローの整理、仕様書のたたき台作成、レビュー項目の抽出を効率化できます。仕様書がない、または古くなっているシステムでも、コードから読み取れる情報を、保守開発や引き継ぎに使いやすいドキュメントへ整えやすくなります。

一方で、Claude Codeは設計判断や業務仕様の確認を代替するものではありません。コードから分かる事実と、設計意図として推測される内容を分け、人によるレビューと検証を組み込む必要があります。Claude Codeは、仕様書作成を丸ごと任せるための道具ではなく、コード理解と文書化の負担を減らすための支援ツールとして活用することが重要です。