はじめに
既存のJavaコードから設計書を起こしたくて、AIに「このメソッドの仕様をまとめて」と投げてみたことがあります。帰ってくる出力は正確ではあるのですが、なんとなく物足りない。具体的なコード値が出てこない、例外スローはあるのにメッセージコードが書かれていない、条件分岐が別セクションに分離されていて処理の流れが追いにくい。
結局、人間が読んで補完して、また聞き直して……という往復が発生します。原因はAIではなく、プロンプトの設計でした。Javaの多層アーキテクチャを解析させるには、デフォルトの「仕様まとめて」には含まれていない4つの指示が必要です。この記事はその記録です。
先にまとめ
設計書生成プロンプトに入れると出力が変わる4点：
- 再帰追跡の明示: Resource→Service→Repositoryまで追わせる
- 定数の具体値参照: 変数名だけでなく実値（コード値・キー名）を参照させる
- 例外コードの明記: 例外スロー時に必ずメッセージコードを出させる
- フロー一本化: 条件分岐・エラー・画面遷移を独立セクションにせずフローに埋め込む
以降で1つずつ解説します。
① 再帰的な追跡を明示する
Javaのエントリポイント（Resource/Controllerクラス）は入口に過ぎません。本体のロジックはServiceに、データアクセスはRepositoryに分散しています。
何も指示しないとAIはエントリポイントのメソッドしか読みません。「このメソッドを解析して」は「このファイルの中だけ見て」と解釈されることがあります。
指示の書き方:
起点メソッドから呼び出されるService・Repositoryまで再帰的に追跡する
各処理はクラス名・メソッド名を明記する（例: `UserService#findById`）
この一文を入れると、AIはファイルを横断して関連クラスを読みに行き、呼び出しツリー全体を処理フローとして出力します。
解析対象が巨大な場合は、起点を絞るのも有効です。
起点クラス: `OrderResource`
起点メソッド: `initGet`
「どこから読めばいいか」が明確なほど、余計な推測が減ります。
② 定数はクラス名でなく実値で
AIはデフォルトで変数名・クラス名どまりの出力を返します。
たとえば、コード内で商品コードを定数で管理している場合：
private static final String PRODUCT_CODE = "P0001234";
指示なしの出力:
商品コード定数が設定されている場合、○○処理を実行する
指示ありの出力:
対象商品コード（
P0001234）が契約中の場合、○○処理を実行する
設計書として使うには後者でないと意味がありません。「定数名を調べてその先の値を参照する」という一手間を、明示的に指示しないとAIはやりません。
指示の書き方:
定数・コード値は実装から具体値を確認して記載する
例）商品コード `P0001234`、パラメータKEY `PROMO_AGENCY_001`
プロパティファイルから値を引くパラメータキーや属性コードでも同じ問題が起きます。「実装から具体値を確認して」という一文が、定数・プロパティ・enumすべてに効きます。
③ 例外コードを省略させない
例外スローの記載はしてくれても、メッセージコードが抜けることがよくあります。
throw new ServiceSystemException("W_SAMPLE_001");
指示なしの出力:
条件を満たさない場合、ServiceSystemExceptionをスロー
指示ありの出力:
条件を満たさない場合、ServiceSystemExceptionをスロー（
W_SAMPLE_001）
設計書としてはメッセージコードがないと、エラーハンドリングの確認ができません。AIはコードを「読んでいる」のではなく「解釈している」ため、明示的に気にしないと省略される傾向があります。
指示の書き方:
例外スロー時はメッセージコードを必ず記載する
例）ServiceSystemExceptionをスロー（`W_SAMPLE_001`）
必ず という強調が効きます。「記載する」だけでは抜けることがありました。
④ 条件分岐はフローに埋め込む
AIに設計書を生成させると、デフォルトでは複数の独立セクションに分割して出力することがあります。
- 処理フロー
- 条件分岐一覧
- 画面遷移定義
- エラー表示定義
- 外部依存・注意事項
出力の網羅性は上がりますが、実際に読むと処理の流れが分断されて追いにくいという問題が出ます。ステップ3の処理を読みながら「この条件分岐はセクション2の[分岐4]を参照」という構造になると、行き来が必要になります。
改善の指示は一文です。
指示の書き方:
条件分岐・エラー・画面遷移・外部依存の注記は独立したセクションには設けず、
該当ステップの補足として埋め込む
これで出力が処理フロー一本に集約され、該当ステップに関連情報がインラインで付きます。
[ステップ5] OrderService#validateOrder — 注文バリデーション
処理内容: 入力値の業務ルールチェックを実行する
入力: OrderForm（画面入力値）
出力: バリデーション結果
補足:
- 在庫なし → ServiceSystemExceptionをスロー（`W_SAMPLE_002`）
- 上限超過 → バリデーションエラーを返却し入力画面へ戻る（`E_LIMIT_001`）
「この処理でなにが起きるか」が一か所で完結します。
まとめ：コピーして使えるプロンプトテンプレート
4つの指示をまとめたテンプレートです。{クラス名} {メソッド名} を差し替えて使ってください。
以下のJavaコードを解析し、画面処理定義を生成してください。
## 解析対象
- 起点クラス: `{クラス名}`
- 起点メソッド: `{メソッド名}`
## 解析方針
1. 起点メソッドから呼び出されるService・Repositoryまで再帰的に追跡する
2. 各処理はクラス名・メソッド名を明記する（例: `UserService#findById`）
3. 定数・コード値は実装から具体値を確認して記載する
- 例）商品コード `P0001234`、パラメータKEY `PROMO_AGENCY_001`
4. 例外スロー時はメッセージコードを必ず記載する
- 例）ServiceSystemExceptionをスロー（`W_SAMPLE_001`）
## 出力形式
### 1. 処理概要
- 画面名・機能名
- 処理の目的を1〜2文で要約
### 2. 処理フロー
各ステップを以下の形式で記述する。条件分岐・エラー・画面遷移・外部依存の注記は
独立したセクションには設けず、該当ステップの補足として埋め込む。
**[ステップN] クラス名#メソッド名 — 処理の見出し**
処理内容: （何をしているか）
入力: （パラメータ）
出力: （返却値・モデルへのセット内容）
補足:
- （条件分岐・エラー・画面遷移・外部依存がある場合のみ記載）
最後に、GMOコネクトではサービス開発支援や技術支援をはじめ、幅広い支援を行っておりますので、何かありましたらお気軽にお問合せください。