ドキュメント作成の自動化
ストーリー
「ドキュメント書くの、好き？」
中島先輩の質問に正直に答えた。
「正直、苦手です... コード書く方が楽で」
「だろうな（笑）。でもドキュメントは大事だ。そして、AIが最も価値を発揮するタスクの一つでもある」
「えっ、ドキュメントもAIに書かせられるんですか？」
「完全自動化とはいかないけど、下書きの80%はAIに任せられる。 残りの20%を人間が調整すればいい」
AIでドキュメントを書く基本アプローチ
3つのパターン
| パターン | 説明 | 適用場面 |
|---|---|---|
| コードから生成 | 既存のコードからドキュメントを自動生成 | JSDoc、README、API仕様書 |
| テンプレートから生成 | テンプレートに情報を埋めて生成 | 設計書、手順書 |
| 対話的に作成 | AIと対話しながら段階的に作成 | ADR、技術選定書 |
パターン1: コードからドキュメント生成
JSDoc / コメント生成
プロンプト:
以下のTypeScript関数にJSDocコメントを追加してください。
パラメータの説明、戻り値、例外、使用例を含めてください。
const calculateShippingFee = async (
items: CartItem[],
destination: Prefecture,
expressDelivery: boolean
): Promise<Result<ShippingFee, ShippingError>> => {
// ... 実装
};
AIの出力例:
typescript
/**
* カート内商品の配送料を計算する
*
* 商品の合計重量と配送先の都道府県、速達オプションに基づいて
* 配送料を算出する。合計金額が10,000円以上の場合は送料無料。
*
* @param items - カート内の商品リスト
* @param destination - 配送先の都道府県
* @param expressDelivery - 速達配送を利用するか
* @returns 成功時は配送料情報、失敗時はエラー
* @throws {ShippingError} 配送不可地域の場合
*
* @example
* const fee = await calculateShippingFee(
* [{ productId: "1", weight: 500, price: 3000 }],
* "東京都",
* false
* );
*/README 生成
プロンプト:
以下のプロジェクト情報に基づいて、GitHubのREADME.mdを作成してください。
プロジェクト名: task-manager-api
説明: チームタスク管理のバックエンドAPI
技術スタック: Node.js, Express, TypeScript, Prisma, PostgreSQL
機能: ユーザー管理、タスクCRUD、チーム管理、通知
セットアップ: npm install → .env設定 → prisma migrate → npm run dev
含めてほしいセクション:
1. プロジェクト概要
2. 技術スタック（バッジ付き）
3. セットアップ手順
4. API概要（主要エンドポイント）
5. 開発ガイド
6. ライセンス
パターン2: テンプレートベースの生成
API仕様書テンプレート
プロンプト:
以下のExpressルーターのコードから、API仕様書を生成してください。
出力形式:
各エンドポイントについて以下を含める
- メソッドとパス
- 説明
- リクエスト（パラメータ、ボディ、ヘッダー）
- レスポンス（成功時、エラー時）
- 使用例（curlコマンド）
[Expressルーターのコードを貼り付け]
障害報告書テンプレート
プロンプト:
以下の情報から障害報告書を作成してください。
事象: 商品検索APIのレスポンスが10秒以上かかる
発生日時: 2025-03-15 14:30
影響範囲: 全ユーザーの商品検索機能
原因: DBのインデックスが欠落していた
対応: productsテーブルのnameカラムにインデックスを追加
再発防止策: マイグレーション時のインデックスチェックをCIに追加
出力形式:
1. 概要（1段落）
2. タイムライン（表形式）
3. 原因分析（5 Whys形式）
4. 対応内容
5. 再発防止策
6. 関連チケット
パターン3: 対話的な作成
ADR（Architecture Decision Record）の作成
プロンプト:
以下の技術選定についてADR（Architecture Decision Record）を
対話形式で作成したいです。
決定事項: 認証方式をJWTからセッションベースに変更する
まず、以下の質問に回答してください:
1. この変更の背景と動機は何ですか？
2. 検討した代替案は何ですか？
3. それぞれのメリット・デメリットは？
4. 最終的にこの選択をした理由は？
私が回答した内容をもとに、ADRフォーマットの文書にまとめてください。
このように対話しながら進めると、情報の抜け漏れを防げます。
ドキュメント作成の品質チェック
AIが生成したドキュメントの確認ポイント
| チェック項目 | 確認方法 |
|---|---|
| 技術的な正確さ | コードとドキュメントの整合性を確認 |
| 用語の統一 | プロジェクト固有の用語が正しく使われているか |
| 対象読者の適切さ | 想定読者にとって難しすぎ／簡単すぎないか |
| 情報の鮮度 | 現在のコードベースを反映しているか |
| 再現性 | 手順書なら実際に手順を実行して確認 |
まとめ
| ポイント | 内容 |
|---|---|
| コードから生成 | JSDoc、README、API仕様書を既存コードから自動生成 |
| テンプレートから生成 | 情報を与えてフォーマットに沿った文書を生成 |
| 対話的に作成 | AIと質疑応答しながら段階的に文書を完成させる |
| 品質確認 | 技術的正確さ、用語統一、再現性を人間が検証 |
チェックリスト
- 3つのドキュメント生成パターンを理解した
- コードからJSDocやREADMEを生成するプロンプトが書ける
- AIが生成したドキュメントの確認ポイントを把握した
- 実際にコードからドキュメントを生成してみた
次のステップへ
ドキュメント作成の次は、デバッグとトラブルシューティングです。 エラーの原因特定と解決にAIを活用する具体的な方法を学びます。
推定読了時間: 30分