最近、開発ドキュメントの陳腐化を防ぐ方法を必死に考えているエンジニアです。今回はなぜドキュメントが陳腐化してしまうのか、その原因を考え、それに対する部分的な解決策として、生成AIを活用した解消法を紹介したいと思います。
なぜドキュメントは陳腐化するのか（更新されないのか）
システムが問題なく稼働しているため、ドキュメントの更新が後回しになる。
ドキュメントを書くことの重要性がチーム全体に認識されていない。
緊急対応時にコードの修正は行うが、ドキュメントの更新が漏れてしまう。
どうしたら解決できるのか
ドキュメントとコードの距離を縮め、バージョン管理をする
普段GitHubでソースコードを管理しているため、ドキュメントも同様に管理することで、設計ドキュメントを更新した際にテスト仕様書も一緒に更新される仕組みを作れば、更新漏れが減少するのではないかと考えました。
ドキュメントを更新することのメリットを大きくする
ドキュメントが更新されないのは、そのメリットが享受されていないためだと思います。ドキュメントを更新することのメリットを増やせば、自然と更新が進み、ドキュメントが現行のシステムに即したものとなります。
テスト仕様書自動生成フロー
開発者が設計ドキュメントを記載し、プルリクエストを作成
GitHub Actionsがプルリクエストをトリガーに変更された設計ファイルを基に、Vertex AIでGeminiにテスト仕様書を自動生成
生成されたテスト仕様書はCSV形式に整形され、プルリクエスト内でコミット
レビュワーは設計内容と一緒にテスト仕様書をレビュー
メリット
テスト仕様書の作成作業が不要になる（多少の修正はあるものの、ゼロからの作成は不要）
設計書の更新が動機づけになり、テスト仕様書も一緒に更新される
設計に対するテストの状態を保てる
実際の出力結果
設計書（Markdown形式）とGeminiで生成されたテスト仕様書の一例です。
設計書の例
ログイン
概要: TODOアプリの認証機能
項目設計:
項目名 I/O データ型 制約
メールアドレス I String 必須、最大255文字、メールアドレス形式
パスワード I String 必須、8〜12文字、半角英数字記号
生成されたテスト仕様書
テスト仕様書は設計書を基に自動生成され、CSV形式で保存されます。
実践の手順
Workload Identityの設定
GitHub ActionsでGoogle Cloudのサービスにアクセスするための設定を行います。OIDCを使ってGoogle Cloudにアクセスするための設定を行います。
サービスアカウントの設定
必要な権限（Vertex AIユーザー、サービスアカウントトークン作成者）を付与し、設定を完了します。
GitHub Actionsの設定
プルリクエストが発行された際に、自動でテスト仕様書を生成するようGitHub Actionsを設定します。
まとめ
今回の仕組みでは、テスト仕様書を自動生成し、GitHubのプルリクエスト内でレビューできる体制を整えました。テスト仕様書の管理をCSVからGoogleスプレッドシートに移行することで、さらに効率的な運用が可能になると考えています。
生成AIを活用したこの仕組みは、開発の効率化に貢献し、ビジネスのコア部分に集中できる環境を作り出します。今後もより良い仕組み作りを目指して改善を続けていきたいと思います。
Explore this: https://ceo.skysolution.com/category/ai/