Gitリポジトリの中身を丸っとGeminiに投げてドキュメントを自動生成・更新してみる
READMEや技術文書の作成・更新は欠かせない作業です。しかし、プロジェクトが大規模化・複雑化するにつれ、これらのドキュメントを最新の状態に保つことは容易ではありません。開発者が手動でドキュメントを更新する時間を確保するのは難しく、結果的に情報が古くなったり、不正確になったりするリスクがあります。
そこで、Gitリポジトリから自動的にドキュメントを生成し、常に最新の情報を提供できるツールを開発しました。本記事では、このツールの特徴や設計思想、そして実際の使い方について紹介します。
自動生成ドキュメントの正確性への懸念
LLMが生成した文章を全面的に信用することはできないため、あくまでレポジトリの概要を軽くつかむための情報程度となります。とはいえ、下のスクショのように、Geminiによって書き換えられた差分をチェックして必要に応じて修正すれば、変更差分を毎回ドキュメント化するより圧倒的に楽だと感じています。
生成したドキュメント例
- このツールのREADMEはほとんどこの自動生成ツールで作成しています。
-
私の個人サイトのREADMEも初版は100%この自動生成ツールで作成しています。
ツール自体はnpm install -g git-repo-summarizerによりグローバルインストールすることでコマンドとして使うことができます。
ツールの概要
目的
このツールは、Gitリポジトリ内の情報を解析し、LLM（大規模言語モデル）であるGoogle Gemini APIを活用して、プロジェクトのドキュメントを自動生成するものです。これにより、ドキュメント作成にかかる時間を大幅に削減することを目指します。
主な機能
- Gitレポジトリ全体を１つのマークダウンに書き出し：Gitで管理されているファイル群を1つのファイルにまとめることでLLMに投入しやすくします。
- ドキュメント自動生成：リポジトリ全体のファイル構成やコード内容をもとに、プロジェクトのREADMEや技術文書を自動生成します。
- READMEの自動更新：既存のREADMEを最新のリポジトリ内容に基づいて更新し、情報の一貫性を保ちます。
設計思想
自動化による効率化
ドキュメント作成・更新のプロセスを自動化することで、人的ミスを減らし、効率的な開発環境を実現します。特に、繰り返し発生する更新作業を自動化することで、開発者の負担を軽減します。
LLMの活用
Google Gemini APIを利用することで、高品質で読みやすいドキュメントを生成します。
拡張性と統合性
コマンドラインツールとして設計されているため、既存のCI/CDパイプラインや開発フローに容易に組み込むことができます。また、オープンソースとして公開しているため、必要に応じて機能拡張やカスタマイズが可能です。プラグイン機構を導入することで、ユーザーが独自の機能を追加できるようにしてもいいかもしれません。
インストール方法
前提条件
- Node.js
- npm
- Google Cloud Platformアカウント
- Google Cloud Platform APIキー
グローバルインストール
以下のコマンドでツールをグローバルにインストールします。
npm install -g git-repo-summarizer
インストールが完了したら、バージョン情報を確認して正しくインストールされていることを確認します。
git-repo-summarizer --version
環境変数の設定
Google Cloud Platform APIキーを環境変数GOOGLE_API_KEYに設定します。
Unix系システム
export GOOGLE_API_KEY="YOUR_API_KEY"
Windows（PowerShell）
$env:GOOGLE_API_KEY = "YOUR_API_KEY"
使い方
1. ドキュメントの自動生成
リポジトリの情報をもとにドキュメントを生成します。
git-repo-summarizer mkdoc -- -t /path/to/your/repo -o document.md
オプション
-
-t,--target：対象のリポジトリのパス（デフォルトは現在のディレクトリ） -
-o,--output：出力ファイル名（デフォルトはgemini-output-YYYYMMDD-HHMMSS.md）
実行例
git-repo-summarizer mkdoc -- -t ./my-project -o my-project-doc.md
2. リポジトリ情報のMarkdown出力
リポジトリのファイル構成をMarkdown形式で出力します。
git-repo-summarizer summarize -- -t /path/to/your/repo -o output.md
実行例
git-repo-summarizer summarize -- -t ./my-project -o my-project-structure.md
3. READMEの自動更新
既存のREADMEを最新の情報に基づいて更新します。
git-repo-summarizer readme -- -i /path/to/your/README.md -o updated-README.md
オプション
-
-i,--input：更新対象のREADMEファイルのパス -
-o,--output：出力ファイル名（デフォルトはupdated-readme-YYYYMMDD-HHMMSS.md） -
-t,--target：対象のリポジトリのパス
実行例
git-repo-summarizer readme -- -i ./README.md -o ./README.md
実践：プロジェクトへの組み込み
npmスクリプトの設定
プロジェクト内で手軽にドキュメントを更新できるよう、package.jsonにスクリプトを追加します。
{
"scripts": {
"update-docs": "git-repo-summarizer readme -- -i ./README.md -o ./README.md"
}
}
これで、以下のコマンドでREADMEを更新できます。
npm run update-docs
仕組みの詳細
リポジトリの解析
- ファイル収集：Gitコマンドを利用して、リポジトリ内の全てのファイルとディレクトリ情報を取得します。
- コンテンツ解析：取得したファイルの中から、テキストファイル（.md, .txt, .js, .pyなど）の内容を読み込みます。バイナリファイルはスキップします。
-
無視ファイルの除外：
.gitignoreファイルに記載されているファイルやディレクトリ、node_modulesやdistなどの不要なディレクトリやファイルは除外されます。
LLMへのデータ送信
- データ整形：取得したファイルの内容とメタデータをMarkdown形式に整形し、LLMへの入力として適切な形式に変換します。
- プロンプト設計：LLMに期待する出力結果を得るために、適切なプロンプトを設計します。例えば、「このリポジトリのREADMEを作成してください」といった指示や、出力形式の指定などを含めます。
- APIリクエスト：整形したデータとプロンプトをGoogle Gemini APIに送信します。
ドキュメントの生成
- LLMからの応答取得：Google Gemini APIから生成されたドキュメント（テキストデータ）を受け取ります。
- 出力：指定したファイル名と形式でドキュメントを保存します。
注意点とベストプラクティス
APIキーの管理
- 料金：Google Gemini APIの利用には料金が発生します。無料枠や課金体系を事前に確認してください。必要に応じて、APIリクエストの回数やデータ量を制限する機能を実装することも検討しています。APIキーはここから作成できます。
機密情報の取り扱い
-
除外設定：
.gitignoreを活用し、特定のファイルやディレクトリを解析対象から除外します。ツール側でも、生成AIに投げるファイルから除外するリストを別途設定できるようにしてもいいかもしれないと考えています。
LLMの出力結果の検証
- 限界: LLMはあくまで確率的なモデルであり、常に完璧な出力を生成するとは限りません。生成されたドキュメントの内容は必ず人間が確認し、必要に応じて修正を加えてください。
- バイアス: LLMは学習データに含まれるバイアスを反映する可能性があります。出力結果に偏りや不適切な表現がないか注意深く確認してください。
応用例
- 生成AIにレポジトリの内容をまるごと投げることによるリファクタリング：生成AIにレポジトリ内のテキストファイルをまるごと投げることで、簡単にプロジェクトの全体像を伝えることができるため、賢いモデルであればリファクタリングしてもらうこともできます。
- 新規プロジェクトのドキュメント作成: プロジェクトの初期段階で、ツールを使って基本的なREADMEや技術文書を自動生成することで、ドキュメント作成の手間を省き、開発をスムーズに進めることができます。
- 既存プロジェクトのドキュメント更新: 定期的にツールを実行することで、READMEや技術文書を最新の状態に保ち、プロジェクトメンバー間での情報共有を促進することができます。
- コードレビュー: コードレビュー時に、ツールを使ってコードの内容を要約したドキュメントを生成することで、レビュアーがコードを理解しやすくなるだけでなく、コードの品質向上にもつながります。
このツールを活用することで、ドキュメント作成の効率化と品質向上を同時に実現したいです。LLMの力を借りて、高品質なドキュメントを自動生成し、開発チーム全体の生産性を高めていけたらなと企んでます。
ぜひ一度試してみて、フィードバックやご意見をいただけると嬉しいです。
Discussion