はじめに
「コードは書けるけどドキュメントを書くのが苦手」
「READMEが古いままで実態と乖離している」
「APIリファレンスを整備する時間がない」
ドキュメントはソフトウェア開発において重要ですが、実装に追われると後回しにされがちです。Claude Codeを使えば、コードを分析して適切なドキュメントを自動生成できます。
目次
- Claude Codeでドキュメントを生成するメリット
- READMEの自動生成
- APIリファレンスの自動生成
- コードコメントの追加・改善
- CHANGELOGの自動生成
- 技術仕様書の作成
- ドキュメントの鮮度を保つ運用
- まとめ
1. Claude Codeでドキュメントを生成するメリット
コードと一致したドキュメント
Claude Codeは実際のコードを読んでドキュメントを生成するため、「ドキュメントと実装が一致しない」問題が起きにくいです。
多言語対応
> README.mdを英語と日本語の両方で作成してくださいこのように簡単に多言語ドキュメントを生成できます。
継続的な更新が可能
コードの変更に合わせてドキュメントを随時更新するよう指示できます。
2. READMEの自動生成
基本的なREADME生成
> このプロジェクトのREADME.mdを作成してください。
プロジェクトの構成・使用技術・設定ファイルを分析して
適切な内容を作成してください。
含める内容：
- プロジェクトの概要（1〜2文）
- 主な機能
- 必要な環境（Node.jsバージョンなど）
- インストール手順
- 基本的な使い方
- 環境変数の説明
- ライセンス既存READMEの更新
> README.mdを現在のコードと照合して、
古くなっている情報を更新してください。
特に以下を確認してください：
- インストール手順が最新か
- 環境変数の記述が.env.exampleと一致しているか
- スクリーンショットや図が実際のUIと一致しているか
- バッジ（テストカバレッジ・バージョンなど）が最新か効果的なREADMEの構成テンプレート
> 以下の構成でREADME.mdを作成してください：
1. バッジ（CI状態・カバレッジ・バージョン）
2. プロジェクト名と1行の説明
3. デモGIFまたはスクリーンショット（プレースホルダー可）
4. 特徴
5. クイックスタート（コピペで動くコマンド）
6. 詳細なインストール手順
7. 設定方法
8. 使い方の例
9. API概要
10. 貢献ガイド
11. ライセンス3. APIリファレンスの自動生成
REST APIのドキュメント生成
> src/api/以下のルートファイルを分析して、
APIリファレンスをMarkdown形式で作成してください。
各エンドポイントに以下を記載してください：
- HTTPメソッドとパス
- 説明
- リクエストヘッダー
- リクエストボディ（JSONスキーマ）
- レスポンスの例（成功・エラー）
- 認証が必要かどうか
docs/api-reference.mdとして保存してください。OpenAPI（Swagger）仕様の生成
> src/api/以下のコードを分析して、
OpenAPI 3.0形式のYAMLファイルを生成してください。
openapi.yamlとして保存してください。
生成後にSwagger UIで表示できることを確認してください。JSDoc・TypeScriptの型定義からドキュメント生成
> TypeDocを使って、src/以下のTypeScriptファイルから
APIリファレンスを自動生成する設定を行ってください。
手順：
1. TypeDocをインストール
2. typedoc.jsonを設定
3. npm run docsコマンドでドキュメントが生成されるようにする
4. 既存のコードにJSDocコメントを追加する4. コードコメントの追加・改善
コメントが不足しているファイルへの追加
> src/services/paymentService.jsにコメントを追加してください。
追加するコメント：
- 各関数の上にJSDocコメント（説明・引数・戻り値）
- 複雑なロジックの箇所にインラインコメント
- ファイルの先頭にモジュールの説明
コメントは日本語で書いてください。不適切なコメントの改善
> このファイルのコメントを見直してください。
削除すべきコメント：
- コードを読めば明らかな自明なコメント（例：// iに1を加える）
- 古くなっているコメント（コードと矛盾しているもの）
- コメントアウトされたままのコード
改善すべきコメント：
- 「なぜそうしているか」が書かれていない「何をしているか」だけのコメント5. CHANGELOGの自動生成
Gitのコミット履歴からCHANGELOGを生成
> git logを分析して、CHANGELOG.mdを生成してください。
フォーマット：Keep a Changelog（keepachangelog.com）に準拠
バージョンタグごとにセクションを分ける
変更を以下に分類：
- Added（新機能）
- Changed（既存機能の変更）
- Fixed（バグ修正）
- Security（セキュリティ修正）
- Deprecated（非推奨になったもの）
- Removed（削除されたもの）リリースノートの自動生成
> v2.0.0のリリースノートを作成してください。
v1.x.xからv2.0.0の変更点をgit logから抽出して、
エンドユーザー向けにわかりやすく説明してください。
技術的な内部変更は省いて、ユーザーに影響がある変更のみ記載してください。6. 技術仕様書の作成
アーキテクチャドキュメント
> このプロジェクトのアーキテクチャドキュメントを作成してください。
含める内容：
- システム全体の構成図（Mermaid記法で）
- 主要なコンポーネントの説明
- データフロー
- 外部サービスとの連携
- 技術選定の理由
docs/architecture.mdとして保存してください。データベーススキーマのドキュメント
> データベースのスキーマをドキュメント化してください。
Prismaスキーマ（またはマイグレーションファイル）を分析して、
以下を含むドキュメントを作成してください：
- 各テーブルの説明
- カラムの意味と型
- テーブル間のリレーション（ER図：Mermaid記法）
- インデックスの説明オンボーディングドキュメント
> 新しいメンバーがプロジェクトを理解してローカル環境を構築するための
オンボーディングドキュメントを作成してください。
含める内容：
- プロジェクトの概要と目的
- ローカル環境構築の手順（コピペで動くレベルに詳細に）
- 開発フロー（ブランチ戦略・PR・レビュー）
- よくある問題とその解決方法
- 役立つリソース・リンク集7. ドキュメントの鮮度を保つ運用
コード変更時にドキュメントを自動更新する
> mainブランチへのpush時に、変更されたファイルに関連するドキュメントを
自動で更新するGitHub Actionsワークフローを作成してください。
更新対象：
- APIのコードが変更されたらAPIリファレンスを更新
- package.jsonが変更されたらREADMEのバージョン情報を更新
- データベーススキーマが変更されたらDBドキュメントを更新ドキュメントの陳腐化チェック
> 現在のコードとドキュメントを比較して、
内容が古くなっているドキュメントを特定してください。
チェック対象：
- README.mdのインストール手順
- APIリファレンスのエンドポイント一覧
- 環境変数の一覧
- アーキテクチャ図8. まとめ
Claude Codeで自動生成できるドキュメント：
- README.md（プロジェクト概要・インストール手順・使い方）
- APIリファレンス（REST API・OpenAPI・TypeDoc）
- コードコメント（JSDoc・インラインコメント）
- CHANGELOG.md（コミット履歴から自動生成）
- 技術仕様書（アーキテクチャ・DBスキーマ・オンボーディング）
ドキュメント生成の効果的な指示：
- 含めてほしい内容を箇条書きで明示する
- フォーマット（Markdown・OpenAPI等）を指定する
- 保存先のファイルパスも指定する
鮮度を保つ工夫：
- コード変更時にドキュメントも更新するGitHub Actionsを設定する
- 定期的にドキュメントの陳腐化チェックを依頼する
次回の第17回：プログラミング未経験者が使う方法では、コードが読めなくてもClaude Codeでできることを10個紹介します。
よくある質問（FAQ）
Q. 生成されたドキュメントは公開してもいいですか？
A. はい、ただし内容の確認は必要です。特にAPIリファレンスは実装と一致しているか、セキュリティ上公開してはいけない情報が含まれていないかを確認してから公開してください。
Q. 多言語ドキュメントの生成も可能ですか？
A. 可能です。「日本語版と英語版を作成してください」と指示するだけで両方生成できます。ただし機械翻訳のため、重要なドキュメントはネイティブスピーカーによる確認を推奨します。
この記事はClaude Code入門シリーズ（第2部）の第16回です。← 第15回：リファクタリング ｜ 第17回：未経験者の使い方 →
ご質問はお問い合わせページからお気軽にどうぞ。
