CodeCraft Lab

ドキュメントを自動生成する

README・API仕様書・コードコメント・CHANGELOGの自動生成から、コード変更に追従させる運用方法までを学びます

実践18分で読了
ドキュメントREADMEOpenAPICHANGELOG

このレッスンで学ぶこと

  • README・API仕様書（OpenAPI）・コードコメントを自動生成するワークフロー
  • コミット履歴からCHANGELOGを自動生成する方法
  • ドキュメントの鮮度を保ち、コード変更に追従させる運用の仕組み

前提条件

  • Lesson 3「テストコードを効率的に生成する」を読んでいること
  • プロジェクトがGitで管理されており、ある程度のコミット履歴があること

ドキュメントが「すぐ古くなる」根本原因

ドキュメントは書いた瞬間がいちばん新鮮で、コードが変わるたびに少しずつ実態とずれていきます。多くのプロジェクトでドキュメントが信頼されなくなる理由は、書く労力が足りないからではなく、更新する仕組みがないからです。

このレッスンでは、Claude Codeを使ってドキュメントを「生成する」段階と、生成したドキュメントを「鮮度を保ったまま運用する」段階の両方を扱います。前半の生成だけで終わらせず、後半の運用設計まで含めるのが、このレッスンのゴールです。

flowchart LR
    A["生成<br/>README/API仕様/コメント/CHANGELOG"]
    B["運用<br/>コード変更時の同期"]
    A --> B --> A
 
    style A fill:#e8f4fd,stroke:#1a73e8
    style B fill:#fff3e0,stroke:#e65100

README自動生成のワークフロー

ゼロから生成する

新規プロジェクトや、READMEが整備されていないプロジェクトでは、コードベース全体を分析させてREADMEの土台を作らせます。

このプロジェクトのコードベースを分析して、READMEを生成して。
 
含めてほしい項目:
- プロジェクトの概要（何を解決するツール/サービスか）
- セットアップ手順（依存関係のインストール、環境変数の設定）
- 開発時によく使うコマンド（起動、テスト、ビルド、Lint）
- ディレクトリ構成の説明
- 主要な技術スタック

Claude Codeは package.json のスクリプトやディレクトリ構造、設定ファイルを横断的に読み取り、ある程度実態に即したREADMEを生成できます。ただし、「なぜこの技術を選んだか」のような背景情報まではコードから推測できないため、人間による加筆が必要です。

生成は土台、仕上げは人間

自動生成したREADMEをそのまま公開するのではなく、「読者が最初に知りたいこと」が冒頭にあるか、専門用語が説明なしに使われていないかを必ず確認しましょう。特にOSSとして公開する場合は、初めて訪れる読者の視点でのレビューが欠かせません。

既存READMEを部分更新する

新機能の追加時に、READMEの該当セクションだけを更新したい場面も多いはずです。全体を作り直すのではなく、差分ベースで依頼します。

今回追加したCLIオプション（--dry-run, --verbose）について、
README.mdの「使い方」セクションに説明を追記して。
既存の記述スタイル（見出しレベル、コード例のフォーマット）に合わせて

API仕様書（OpenAPI）の生成

コードからOpenAPIスキーマを起こす

REST APIのエンドポイント実装からOpenAPI（Swagger）形式の仕様書を生成させると、実装と仕様の乖離を防ぎやすくなります。

src/api/routes/ 以下の全エンドポイントを分析して、
OpenAPI 3.0形式のyamlファイル（docs/openapi.yaml）を生成して。
 
含める内容:
- 各エンドポイントのパス、メソッド、パラメータ
- リクエスト/レスポンスのスキーマ（型定義ファイルから推測）
- 認証要件（ミドルウェアの実装から判断）
- エラーレスポンスのパターン（実装されているエラーハンドリングから抽出）

型定義（TypeScriptのinterfaceやZodスキーマなど）が整備されているプロジェクトほど、生成されるOpenAPIスキーマの精度は高くなります。型情報が乏しい場合は、先に型を整備してから仕様書を生成する方が結果的に近道です。

仕様とコードの整合性を検証する

生成して終わりではなく、既存の仕様書がある場合は実装との不一致を検出させることもできます。

docs/openapi.yaml の内容と、src/api/routes/ の実装を突き合わせて、
不一致がないか確認して。
 
- 仕様書にあるが実装にないエンドポイント
- 実装にあるが仕様書にないエンドポイント
- パラメータやレスポンス型の不一致
 
見つかった不一致を一覧で報告して。修正はまだしないで
自動生成のOpenAPIは「叩き台」として扱う

自動生成された仕様書は、実装の構造をそのまま反映しがちです。実装上の都合で複雑になっているレスポンス構造などは、API利用者にとって読みやすい形に人間が整理し直す価値があります。

コードコメント・JSDoc/docstringの一括生成

対象を絞って生成する

コードコメントの一括生成は、対象を広げすぎると質が落ちやすい作業です。まずは公開APIやコアロジックなど、優先度の高い範囲から着手しましょう。

src/lib/ 以下の、外部に公開されている関数（exportされている関数）で、
JSDocコメントが付いていないものを一覧にして
先ほどリストアップした関数にJSDocコメントを追加して。
 
含める内容:
- 関数の目的（何をするか、なぜ必要か）
- 各パラメータの説明と型
- 戻り値の説明
- 副作用がある場合はその明記
- 自明な内容（「ユーザーを取得する関数」のような型から分かる説明だけ）は書かない

最後の「自明な内容は書かない」という指示が重要です。指定しないと、型情報をそのまま日本語に翻訳しただけの、情報量の少ないコメントが大量生産されることがあります。

言語に応じたフォーマットを指定する

src/services/user_service.py の関数にdocstringを追加して。
Googleスタイルのdocstring形式（Args, Returns, Raises）で書いて
CLAUDE.mdに「意図を説明するコメント」の方針を明記する

このリポジトリのCLAUDE.mdにある「コメントは積極的に書く」「ビジネスロジックの背景や制約事項はコメントで補足する」という方針は、まさにこの一括生成作業にも適用すべきルールです。一度書いておけば、コメント生成のたびに同じ指示を繰り返す必要がなくなります。

CHANGELOGの自動生成

コミット履歴から生成する

Git のコミット履歴を読み取らせて、リリースノート形式のCHANGELOGを生成させます。コミットメッセージの質に結果が左右されるため、日頃のコミット運用と合わせて考える必要があります。

git log v1.2.0..HEAD の内容を確認して、CHANGELOG.mdに
新しいバージョン（v1.3.0）のエントリを追加して。
 
分類:
- Added: 新機能
- Changed: 既存機能の変更
- Fixed: バグ修正
- Deprecated: 非推奨化された機能
 
Conventional Commits形式（feat:, fix:, chore:等）のプレフィックスを
手がかりに分類して。プレフィックスがないコミットは内容から判断して

PRの内容からより詳しい説明を補う

コミットメッセージだけでは情報が不足する場合、関連するPRの説明を参照させると精度が上がります。

今回のリリースに含まれるPR一覧を `gh pr list --state merged --base main` で取得して、
各PRの説明文も参考にしながら、CHANGELOG.mdのエントリをより詳しく書いて。
ユーザー視点で「何が変わったか」が伝わる文章にして
破壊的変更は必ず目立たせる

自動生成したCHANGELOGをそのまま公開する前に、破壊的変更（Breaking Changes）が正しく分類され、目立つ位置に記載されているかを必ず確認しましょう。見落とすと、利用者が気づかずにアップデートしてトラブルになる可能性があります。

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

ここまでの生成ワークフローは「一度作る」ための手順です。実務で本当に重要なのは、コードが変わった後もドキュメントが追従し続ける仕組みを作ることです。

コード変更時にドキュメント更新を促す

PRの中でコードとドキュメントをセットで変更する習慣をつけるのが最も確実です。Claude Codeに変更内容からドキュメント更新の要否を判断させましょう。

このブランチの変更内容を確認して、
更新が必要そうなドキュメント（README.md, docs/openapi.yaml,
関連するJSDocコメント）がないか調べて報告して

これをPR作成前のルーティンに組み込むと、ドキュメントの陳腐化を早期に検知できます。

CLAUDE.mdにドキュメント同期のルールを書く

「ドキュメントを更新し忘れる」という問題は、結局のところ人間の記憶力に依存している限り再発します。プロジェクトのルールとして明文化しましょう。

## ドキュメント運用ルール
- API（src/api/routes/）に変更を加えた場合は、docs/openapi.yamlも同じPRで更新する
- 公開関数（export）のシグネチャを変更した場合は、JSDocコメントも更新する
- CLIオプションを追加・変更した場合は、README.mdの「使い方」セクションを更新する

CLAUDE.mdにこのルールを書いておくと、Claude Codeは関連する変更を行う際に自然とドキュメント更新も一緒に提案するようになります。

定期的な棚卸しを自動化する

日々の同期に加えて、定期的にドキュメント全体の鮮度をチェックする仕組みも有効です。

docs/ 以下の全ドキュメントについて、
最終更新日から3ヶ月以上経過していて、
かつ関連するソースコードがその後変更されているものを一覧にして

このようなチェックは、Claude Codeのスケジュール実行機能（Routines）を使えば、週次・月次で自動的に実行し、結果をレポートさせることもできます。スケジュール実行の詳細な設定方法は組織導入コースで扱います。

ドキュメントの鮮度は「コード側のシグナル」と紐づける

ドキュメントの更新日だけを見るのではなく、「対応するソースコードが変更されたか」を基準にすることで、本当に同期が必要なドキュメントだけを優先的に洗い出せます。すべてのドキュメントを一律で棚卸しするより効率的です。

ドキュメント生成ワークフロー全体図

このレッスンで扱った内容を、実際のプロジェクトに組み込む際の全体フローとしてまとめます。

flowchart TD
    A["新機能の実装"]
    B["PR作成前に変更内容と<br/>関連ドキュメントの<br/>整合性をチェック"]
    C{"更新が<br/>必要?"}
    D["README/OpenAPI/コメントを<br/>差分ベースで更新"]
    E["PRに変更とドキュメント<br/>更新をセットで含める"]
    F["マージ後、CHANGELOGに<br/>エントリを追加"]
    G["定期的な棚卸しで<br/>取りこぼしを検知"]
 
    A --> B --> C
    C -->|Yes| D --> E
    C -->|No| E
    E --> F --> G
 
    style B fill:#e8f4fd,stroke:#1a73e8
    style G fill:#fff3e0,stroke:#e65100

よくある質問

Q. ドキュメント生成にどれくらいの頻度で時間を使うべきですか?

「コードと同時に小さく更新する」を基本にすれば、まとまった時間を取る必要はほとんどなくなります。大きな棚卸し作業が必要になるのは、ドキュメント同期のルールが整備されていなかった期間が長く続いた場合だけです。

Q. 生成したドキュメントは毎回隅々まで確認すべきですか?

README全体の再生成のような大きな変更は必ず人間がレビューすべきですが、JSDocコメントの追加のような小さく機械的な変更は、/code-review でのセルフチェック程度で十分なことが多いです。変更の影響範囲に応じてレビューの厳しさを調整しましょう。

Q. 多言語対応（英語版READMEなど）も自動生成できますか?

可能です。「README.mdの内容を英語に翻訳してREADME.en.mdとして保存して」のように依頼できます。ただし、翻訳後は文化的なニュアンスや技術用語の使い方が適切か、ネイティブスピーカーまたは翻訳に詳しい人によるチェックを推奨します。

まとめ

  • README・API仕様書・コードコメント・CHANGELOGは、それぞれコードベースや履歴から自動生成できるが、生成結果は「叩き台」として人間が仕上げる
  • コメント生成では「自明な内容は書かない」、CHANGELOGでは「破壊的変更を目立たせる」など、対象に応じた指示の工夫で品質が変わる
  • ドキュメントの鮮度はPR単位での同期、CLAUDE.mdへのルール明記、定期的な棚卸しの3段構えで保つ
  • コード変更とドキュメント更新をセットでPRに含める習慣が、最も確実な鮮度維持の方法
実践コース、お疲れ様でした

これでLesson 1〜4を通じて、コードレビュー・リファクタリング・テスト生成・ドキュメント生成という、日常の開発業務における主要なワークフローを体系的に学びました。続くLesson 5以降では、デバッグ支援やGit操作の効率化、プロンプト設計の技術など、さらに実践的なテーマを扱っていきます。

次のステップ

ドキュメントが整備され、テストも揃ったコードベースでも、開発中には必ずバグに遭遇します。次のLesson 5では、エラー解析やログ追跡、再現手順の特定など、デバッグ作業を加速させるための実践テクニックを学びます。