ドキュメントとナレッジ共有

🔄 前のレッスンでコードレビューとリファクタリングを学んだ。今回は開発者が最も避けがちな作業——ドキュメントをAIで攻略する。

なぜドキュメントを書かないのか

開発者がドキュメントを書かない理由ランキング：

1. 時間がない（1位はこれ）
2. コードが変わるからすぐ陳腐化する
3. 「コードが最良のドキュメント」と信じている
4. 単純に面倒くさい

AIは1と4を解決する。2は「AIに更新させる」ことで緩和できる。3は……残念ながら間違い。

AIドキュメント生成のパターン

パターン1：関数・クラスのdocstring

以下のコードにdocstringを追加してください。

```[language]
[コード]

条件：

• [Google Style / NumPy Style / JSDoc]形式
• パラメータの型と説明
• 戻り値の型と説明
• 使用例を1つ含む
• エッジケースの注意点があれば記載

### パターン2：APIドキュメント

以下のAPIエンドポイントのドキュメントを生成してください。

エンドポイントコード：

[ルーティング＋ハンドラのコード]

データモデル：

[リクエスト/レスポンスの型定義]

以下を含めてください：

• HTTPメソッドとURL
• リクエストパラメータ/ボディの説明
• レスポンスの構造
• エラーコードとその意味
• curlでのリクエスト例

### パターン3：レガシーコードの解説

以下のコードの動作を、新しくチームに入った開発者向けに説明してください。

[レガシーコード]

以下の構成で：

1. このコードが何をしているかの概要（3行以内）
2. 処理の流れ（ステップバイステップ）
3. 注意すべきエッジケースや「罠」
4. このコードに依存している/このコードが依存しているモジュール

### パターン4：ADR（Architecture Decision Record）

以下の技術選定についてADRを作成してください。

決定事項：[例：キャッシュにRedisを採用] 背景：[なぜこの決定が必要だったか] 検討した選択肢：

1. [選択肢A]
2. [選択肢B]
3. [選択肢C]

ADRテンプレート形式で：

• タイトル
• ステータス
• コンテキスト
• 決定
• 結果（ポジティブ・ネガティブ・リスク）

## ドキュメントの鮮度を保つ

AI生成ドキュメントの最大の問題：**陳腐化**。

**対策：**
1. **コード変更時にAIにドキュメント更新を依頼**するフローを作る
2. **CI/CDパイプライン**にドキュメント生成ステップを組み込む
3. **README.mdの定期レビュー**をスプリント計画に含める

## 実践演習

1. 自分のプロジェクトから最もドキュメントがない部分を選ぶ
2. AIでドキュメントを生成する
3. 生成内容が実際のコード動作と一致するか検証する

> 💡 **ポイント：** 完璧なドキュメントを目指すと永遠に書かない。AIで80%の精度のドキュメントを素早く作り、必要に応じて修正する方がゼロより無限に良い。