所属プロジェクトが変わったので、移動先のプロジェクトの概要や仕様を把握する必要がでてきたのですが、いくつかの壁がありました。
- このプロジェクトは複数のサービスで構成される。
- 各サービスが果たす役割や扱うデータなどの概要を説明したドキュメントは存在するが、詳細な仕様が書かれたドキュメントがない。
- 各サービスがローカル環境では実行できない（ローカル環境を使用した開発が行われていない）
- 各サービスは主にJavaで書かれているが、私はJavaに触れたことがない。
そこでプロジェクトの各サービスの仕様を把握するために、ドキュメント作成とローカル開発環境の構築がプロジェクト移動後の最初のタスクとなりました。
これらのタスクは全てAIを使って進めているのですが、LLMの癖なのかプロンプトが良くないのか、気をつけておくべきポイントがあることに気づいたので書き出してみました。
LLMの各モデルをうまく使い分けたり、日々プロンプトを試行錯誤されている方には当たり前のことかもしれませんが、私のようなLLM初心者の方の参考になれば幸いです。
AIが生成したSQLやテーブル定義の品質問題と対策
AIが書き出したSQLやテーブル定義には、存在しないテーブルやカラムが存在することが多いです。
ドキュメント作成だけではなく、ローカル環境（Docker）でシステムを動かしている際にも同じ現象が発生します。AIに「〇〇のデータが登録されたか確認して」等の命令を行うとSQLを発行してくれるのですが、大体存在しないテーブルやカラムを指定します。
実際のところはわかりませんが、SQLを発行する際に都度テーブル定義を確認せず、他のテーブル構造などを参照した上で、「こんなテーブルやカラムが存在するはず」と予想して（適当な）SQLを発行しているように見えます。
対策
ドキュメントを作成したら最後にドキュメントに記載したDDLやSQLが正しいかAIに検証させています。
AIが生成したエンドポイントの品質問題と対策
OpenAPIのようなAPI仕様書が存在しなかったため、AIにエンドポイント一覧をドキュメントにまとめてもらったのですが、存在しないエンドポイントが紛れ込んでいたり、リクエストパラメータが誤っている場合が多々ありました。
関連するコードを読んでエンドポイントをリストアップしているのは間違いないのですが、コードから読み取ったエンドポイントを参照したうえで「こんなエンドポイントやパラメータが存在するはず」とAIが予想したエンドポイントも紛れ込んでいました。コードの量が多いのが問題なのかもしれません。
対策
ドキュメントを作成したら最後にドキュメントに記載したエンドポイントとパラメータが存在するかAIに検証させています。
AIが生成した定義・定数の品質問題と対策
参照先のマスタテーブルや定義ファイルを指定して固定値をドキュメントに記載させる場合は正確ですが、そうでない場合はどこからその値を持ってきたんだというくらい適当な値が記載されていたりします。
対策
AIが書き出した固有値に対して、この値は何を参照したかAIに確認を入れます。
AIが生成したフロー図の品質問題と対策
サービスの仕様を理解するために処理の流れをマーメイド記法でフロー図化させているのですが、これも結構間違っていることが多いです。後続処理があるはずなのに矢印が繋がっていなかったり、存在しない処理が紛れ込んでいる場合があります。
SQLやエンドポイントの間違いとは違い、参画したばかりのプロジェクトの仕様を把握するために書き出しているフロー図なので、自分では誤りに気づきにくいところが大きな問題点です。
対策
プロジェクト歴の長いメンバーにフロー図を見てもらい、内容が正しいか確認してもらっています。
ドキュメント作成ガイドラインの例
ドキュメントを作成するたびにSQLやエンドポイントの存在チェックを指示しなくていいように、ドキュメント作成ガイドラインを作成し、ドキュメントの品質チェックリストを入れています。
以下はその一例です。
## 🔍 品質チェックリスト
### 内容の品質
- [ ] 目的が明確に記載されている
- [ ] 手順が段階的に説明されている
- [ ] コマンド例が具体的に記載されている
- [ ] 期待結果が明示されている
- [ ] エラー時の対処法が記載されている
### リンクの品質
- [ ] 内部リンクが正しく設定されている
- [ ] 相対パスが正しく使用されている
- [ ] リンク切れがない
- [ ] 相互リンクが設定されている
### 開発者向けドキュメントの品質
- [ ] 文書の長さが適切（技術仕様書：250行程度、運用ガイド：300行程度）
- [ ] 開発者の作業範囲外の情報が削除されている
- [ ] 冗長な説明が削除されている
- [ ] セクション数が7-10程度に収まっている
- [ ] 実装に必要な情報が確実に含まれている
### SQLの品質
- [ ] 記載されているテーブル名が実際のデータベース構造と一致している
- [ ] 記載されているカラム名が実際のデータベース構造と一致している
- [ ] SELECT文の構文が正しい
- [ ] データ型の参照が正確
- [ ] 主キー・外部キーの参照が正確
ちなみに、ドキュメントの対象読者を開発者と明記しておくと開発者が必要としそうな内容にまとめ上げてくれます。
**📋 開発者向けドキュメント構成の推奨事項**:
- 文書情報に「対象読者: 開発者」を明記
- 各文書は7-10セクション程度に収める
- 技術仕様書は250行程度、運用ガイドは300行程度を目安
- 実装に直接関係しない情報（運用チェックリスト、詳細な権限設定等）は削除
おまけ：AIの助けを借りてローカル開発環境を構築するときに気をつけるポイント
このプロジェクトでは各サービスがDockerで動くようになっていたので、Dockerコンテナ上でサービスの動作検証が行えるように、AIの助けを借りて開発環境を構築しました。作業にあたり、作業記録を.mdに残す、基本的に1セッション1タスク、作業後は.mdを更新するなどの他に以下のことに気をつけています。
1. コマンドは自動実行させない
開発環境構築時や動作検証中にエラーが発生すると、AIはエラー解決を優先する場合と当初の目的（環境構築や動作検証）を達成するために別の方法を取ろうとする場合があります。AIが取ろうとしているアクションと、自分ならこうするというアクションが違う場合はAIのアクションをストップさせたいので、コマンドは自動実行させないようにしています。
2. 検証する場合は目的を明記する
1の理由と近いですが、開発環境構築時や動作検証中にエラーが発生した場合に横道に逸れてしまうのを防ぐために目的を明記するようにしています。最終的に環境構築や動作検証に失敗したとしても、目的が達成できたか・何に失敗したか・次とるべきアクションは何かをAIがまとめてくれるので、次のステップに繋げやすくなります。
3. サービスの動作検証でエラーが発生した場合は、エラーの内容と次にとるべきアクションを作業ログに残し、新しいセッションでエラーの解決にあたる
原則1セッション1タスクを気をつけていますが、エラーが発生すると原因調査や解決などで1セッションが長くなりがちです。こういうときはエラーの発生箇所、次にとるべきアクションを作業ログに記録させ、新しいセッションでエラー解決を図るほうが早く解決できるような気がしています（なんとなくの肌感です）。
まとめ
ここ1ヶ月ほど、Cursorの助けを借りて新規参画プロジェクトのサービス仕様の把握やローカル開発環境の構築を行ってきましたが、AIが作成するドキュメントの傾向がなんとなくわかってきました。最終的にはプロジェクト歴の長いメンバーにドキュメントをレビューしてもらう必要がありますが、自力でコードを読んだりメンバーにヒアリングするよりも、はるかに省力でドキュメント化を進められた気がします。
今後はより精度をあげるためにプロンプト設計を試行錯誤していきたいと思います。
Discussion