はじめに
「ドキュメントを書く時間があったら、コードを書きたい」
多くの開発者の方に共感していただけるのではないでしょうか。
とはいえソフトウェア開発プロジェクトにおいて、技術ドキュメントの作成は避けて通れない重要なタスクです。実際、業界の調査によると、開発者は作業時間の15-20%をドキュメント作成に費やしているとされています。コードを直接記述したエンジニアが作成する必要があるドキュメントも多く、この作業負荷は決して無視できないものです。
もしこの作業時間を数時間単位で削減できたら?
本記事では、ChatGPTなどのAIを活用して、技術ドキュメント作成を効率化する具体的な方法を紹介します。適切なプロンプトと組み合わせることで、ドキュメント作成の時間を大幅に削減し、より本質的な開発作業に時間を割くことができるようになります。場合によってはエンジニア本人ではなく、アシスタントさんなどに作業を割り振ることもできるでしょう。
今回は特に効果の高い6つの活用法を厳選してご紹介します。これらの手法を組み合わせることで、プロジェクト全体で数十時間規模の工数削減も決して夢ではありません。ぜひ最後までお付き合いください。
目次
- 機能・関数の説明生成
- 手順
- 実際の出力例
- ディレクトリ構成の記述
- 手順
- 実際の生成例
- シーケンス図の自動生成
- 手順
- 生成例と実際の図
- APIドキュメントの自動生成
- 手順
- Swagger UI活用
- データベース設計書の生成
- 手順
- テーブル説明と設計図の生成
- エラーハンドリングドキュメントの作成
- 手順
- 出力例
- まとめ
- メリット
- 注意点
1. 機能・関数の説明生成
開発者にとって最も時間がかかる作業の一つが、個々の関数やメソッドの詳細な説明を書くことです。AIを使用することで、この作業を大幅に効率化できます。
具体的な手順:
- 対象のコードをChatGPTに入力します(なお機密保持の観点で、有料版のPlaygroundを使うか、API経由でのご利用を推奨します)
以下のようなプロンプトを入力:
以下のコードを関数ごとに説明してください。説明は以下の例のようなフォーマットで記述すること。 例) 関数名:fetchData スクロールを監視し、ページ下部付近でさらにデータをフェッチします {あなたのコード}
試しに筆者の開発したコードを読み込ませてみると、以下のようなレスポンスが返ってきます。このような機能一覧をわずか数秒で作成することができます。
`initializeApp`
初期化された設定に基づいてアプリを初期化し、セットアップ。データをフェッチします。
`initializeSAMPLE`
アプリを初期化し、ログインユーザーのプロフィールを取得。未ログイン時は警告を表示します。
`handleScroll`
スクロール位置を監視し、ページ下部付近で追加のデータをフェッチして表示を更新します。
`fetchMore`
現在の状態を確認しながら、追加のデータを非同期でサーバから取得します。
`renderTabs`
タブクリックイベントを登録し、選択されたタブに応じてデータのレンダリングやクリップボードを更新します。
`renderStatistics`
ユーザーの統計データを表示し、時間別に分けて表示します。
このアプローチによって、時間の大幅な節約ができるとともに、一貫性のある説明フォーマットを持つことができ、読み手にとっても利便性の高い機能一覧を作成することができます。
2. ディレクトリ構成の記述
プログラムの構成はアプリケーションやシステムの動作に必須の要素です。正しいディレクトリ構造の文書化は非常に重要です。AIを使用することで、この作業を自動化できます。
手順:
- プロジェクトのディレクトリ構造のスクリーンショットを撮影
以下のようなプロンプトを入力:
この画像は、プログラムのディレクトリ構成を示しています。このディレクトリ構成をmarkdownファイル用に記述してください {画像}
実際に入力に使った画像はこちらです。
/
├── app/
├── artisan
├── bootstrap/
├── composer.json
├── composer.lock
├── config/
├── database/
├── lang/
├── package.json
├── phpunit.xml
├── public/
├── README.md
├── resources/
│ ├── css/
│ ├── js/
│ ├── lang/
│ └── views/
│ ├── articles/
│ │ ├── articles.blade.php
│ │ ├── bookmarks.blade.php
│ │ ├── create.blade.php
│ │ ├── edit.blade.php
│ │ ├── form.blade.php
│ │ ├── index.blade.php
│ │ └── show.blade.php
│ ├── auth/
│ ├── commons/
│ │ └── home.blade.php
│ ├── layouts/
│ └── welcome.blade.php
├── routes/
├── storage/
├── tests/
├── vendor/
└── vite.config.js
3. シーケンス図の自動生成
シーケンス図も、ドキュメントの重要な要素です。AIを使用してPlantUMLのコードを生成することで、見やすいシーケンス図を効率的に作成できます。もちろんDraw.ioなど、納品ドキュメントの要件に合わせてプロンプトは修正してください。
手順:
- 対象のコードをChatGPTに入力します(なお機密保持の観点で、有料版のPlaygroundを使うか、API経由でのご利用を推奨します)
以下のプロンプトを使用:
以下のコードを処理の流れを箇条書きで示し、さらにPlantUMLで作図できるように記述してください。 {あなたのコード}
以下のようなPlantUMLのコードが生成されます。
@startuml
actor User
participant "Web Browser" as WB
participant "Web Server" as WS
participant "LIFF Service" as LIFF
User -> WB: Access Application
WB -> WS: Fetch config.json
WS -> WB: Return settings
alt Environment Check
WB -> WB: Initialize in 'dev'
else
WB -> WB: Initialize in 'prod'
end
WB -> LIFF: Initialize LIFF
alt User Logged In
LIFF -> WB: Return Profile
WB -> WB: Render User Interface
WB -> WS: Fetch Meals
WS -> WB: Return Meal Data
else
LIFF -> WB: Show login message
end
@enduml
生成されたコードで作図するとこのような感じになります。全く問題がありません。1時間の作業が2分に縮まりました。
4. APIドキュメントの自動生成
APIドキュメントが不完全または古い状態になっているのは珍しいことではありません。ありがちなのは、テストに使っているcurlコマンドだけ最新版であるとかそんな感じでしょうか。この項ではcurlからOpenAPI形式のドキュメントを生成し、swagger向けにするというシナリオを想定しています。
手順:
- curlコマンドを用意
以下のプロンプトを使用:
以下のコマンドをopenapiの形式に変換してください。 {curl}
生成されたOpenAPIの記述はそのままSwagger UIでの表示が可能です。
5. データベース設計書の生成
データベース設計のドキュメント化は、特に開発の進行に伴って変更が加わったりした場合に困難になりがちです。これもAIを使用することで、最新の状態を反映した設計図を簡単に生成できます。
手順:
- SHOW CREATE TABLEの出力やDB管理画面のスクリーンショットを用意
以下のプロンプトを使用:
以下はデータベースの構造を示しています。各テーブルを説明し、さらにPlantUMLのテーブル設計図を記述してください {画像1}{画像2}{画像3}
スクショ画像はテーブル構造の画面が適しています。テーブル数分用意して、ChatGPTに入力してください。まず以下のように説明が出力されます
`created_at`
- 型: `timestamp`
- 説明: レコードが作成された日時を記録します。デフォルトで現在のタイムスタンプが設定されます。
`updated_at`
- 型: `timestamp`
- 説明: レコードが最後に更新された日時を記録します。更新時にタイムスタンプが自動更新されます。
続いて作図用のPlantUMLの記述が出力されます。
@startuml
entity "meals" as M {
* park_id : int <<PK>>
--
user_id : varchar
park_time : timestamp
photo_url : varchar
created_at : timestamp
updated_at : timestamp
}
entity "car_details" as MD {
* detail_id : int <<PK>>
--
park_id : int <<FK>>
name : varchar
color : int
number : int
created_at : timestamp
updated_at : timestamp
}
M ||--o{ MD : meal_id
@enduml
作図結果です。
6. エラーハンドリングドキュメントの作成
エラーの文書化は、運用フェーズで特に重要になります。文書作成時に各種エラー出力の内容をコード全体から集めるのも非常に時間がかかりますが、AIを使用することで、包括的なエラーハンドリングドキュメントを効率的に作成できます。
手順:
- 対象コードをChatGPTに入力
以下のプロンプトを使用:
以下のコードの各処理におけるエラーについて記述してください。通知先などがある場合は通知先も記述してください {あなたのコード}
出力結果
`設定ファイルの読み込み`
- **エラー**: `config.json`がロードできない場合
- **通知**: コンソールにエラーメッセージを表示
`LIFF初期化`
- **エラー**: LIFFの初期化やプロフィール取得の失敗
- **通知**: コンソールにエラーメッセージを表示
`データのフェッチ`
- **エラー**: `fetch`関数でデータ取得が失敗
- **通知**: コンソールにエラーメッセージを表示
`全データのフェッチ`
- **エラー**: `fetchAll`関数でデータ取得が失敗
- **通知**: コンソールにエラーメッセージを表示
まとめ
本記事で紹介したAIを活用した技術ドキュメント作成手法により、以下のような具体的な成果を得ることができます:
即効性のあるメリット
作業時間の大幅な削減
- 機能説明書作成:3時間 → 30分
- シーケンス図作成:2時間 → 15分
- DB設計書更新:4時間 → 1時間
ドキュメントの品質向上
- 一貫性のあるフォーマット
- 漏れのない説明
- 読みやすい構造化
チームワークの改善
- レビュー時間の短縮
- 新メンバーの早期立ち上げ
- 知識共有の効率化
活用時の注意点
- 生成されたドキュメントは必ずレビューを行う
- 機密情報の取り扱いは細心の注意を払う
- AIの出力は、プロジェクトの文脈に合わせて適切に編集する
さらなる効率化へ
今回ご紹介した6つの手法は、個別に活用することももちろん可能ですが、実はこれらを連携させることで、さらなる効率化が可能です。例えば:
- GitHubアクションとの連携
- 自動ドキュメント生成パイプラインの構築
- カスタムAIアシスタントの開発
弊社ではこれらのAIを活用した開発効率化ソリューションをご提供しています。具体的な導入方法や、御社の開発プロセスに合わせたカスタマイズについてもご相談を承っております。
技術ドキュメント作成の効率化は、開発者の本質的な作業時間を確保するための重要な一歩です。ぜひ、まずは取り入れやすい手法から試してみてください。