Claude Codeドキュメント生成 — JSDoc・README・変更ログの手順

Claude Codeにドキュメントを書かせるとは、コードを読ませてJSDocやdocstring、README、変更ログをそのプロジェクトの文脈に沿って生成・更新させる作業です。手作業で書くより速いだけでなく、コードとドキュメントが同じセッションで同時に確認できるため、実装との食い違いにも気づきやすくなります。本記事では未文書化コードの洗い出しから、生成物のレビュー、チームでの表記統一まで、実行順に手順を追います。

Claude Codeにドキュメントを書かせるとできること

Claude Codeのドキュメント生成は、コード自体を直接読んだうえで文章を組み立てる点が既存のドキュメント自動生成ツールと異なります。シグネチャから型を機械的に抜き出すだけでなく、関数の呼び出し元や条件分岐まで読んで「なぜこの引数が必要か」まで説明文に反映できます。

対応する範囲は大きく4つです。

• 関数・クラスのコメント生成: JSDoc、Pythonのdocstring、Goのdoc commentなど言語ごとの規約に沿ったコメントを追加する
• READMEの新規作成・更新: セットアップ手順や使い方をコードの実態に合わせて書く、または実装が変わった箇所だけ差分更新する
• 変更ログの生成: gitのcommit logやdiffをもとに、リリースノート形式で変更点をまとめる
• 既存ドキュメントの規約チェック: プロジェクトの表記ルールに沿っているかをレビューさせる

これらはすべて同じ会話の流れで実行できます。コードを変更した直後に「このファイルのドキュメントも直して」と続けるだけで、実装とドキュメントのずれを最小限に抑えられます。

未文書化のコードを洗い出すところから始める

最初のステップは、どこにドキュメントが欠けているかを特定することです。対象を絞らずに「プロジェクト全体にコメントを付けて」と頼むと、変更範囲が広がりすぎてレビューが困難になります。モジュール単位・ファイル単位で範囲を区切るのが安全です。

find functions without proper JSDoc comments in the auth module

このプロンプトに対してClaude Codeは対象ディレクトリのファイルを実際に開き、コメントが無い関数・型定義が不十分な関数を一覧にして返します。ここで一覧を確認し、優先度の高いファイルから次のステップに進みます。

JSDoc・docstringを一括生成する

対象が絞れたら、実際にコメントを追加させます。

add JSDoc comments to the undocumented functions in auth.js

生成させるときは、スタイルを明示すると仕上がりが安定します。何も指定しないとClaude Codeは既存コードの周辺スタイルから推測しますが、プロジェクトに複数のスタイルが混在している場合は推測が割れることがあります。

公開APIやインターフェース、複雑な条件分岐を含む関数は、コメントの効果が特に大きい対象です。逆に自明なgetter/setterまで機械的にコメントで埋めると、かえってノイズになります。「公開関数だけに絞って」「複雑度の高い関数を優先して」のように対象を条件で絞ると、必要な箇所だけに労力を割けます。

生成直後の文章は汎用的な言い回しに寄りがちです。「この関数の意図と、なぜこの実装になったかの背景も含めて」のように依頼すると、コードの表面をなぞるだけでなく設計判断まで説明に反映されます。具体例を含めてほしいときは「使用例を1つ添えて」と付け加えます。

READMEと変更ログを更新させる

READMEは実装が進むほど実態とずれていきます。機能追加のたびに手で直すのは負担が大きいため、まとまった変更の後にClaude Codeへ差分更新を頼む運用が現実的です。

Update the README's setup section to match the current package.json scripts

変更ログは、gitのコミット履歴やタグ間のdiffを実際に読ませて生成します。記憶や推測でまとめさせると、実装していない変更が紛れ込む危険があるため、必ず具体的な範囲を指定します。

Summarize the commits between v1.2.0 and HEAD into CHANGELOG.md, grouped by feature and fix

この指定方法なら、Claude Codeは git log や git diff を実際に実行してから文章を組み立てます。範囲を指定せずに「変更ログを書いて」とだけ頼むと、会話の文脈にある情報だけで書いてしまい、直近のコミットが漏れることがあります。

生成したドキュメントを検証する

生成して終わりにせず、プロジェクトの規約に沿っているかを確認する工程を挟みます。

check if the documentation follows our project standards

このときCLAUDE.mdにドキュメントの書式ルール(コメントの言語、必須項目、禁止表現など)を書いておくと、Claude Codeは毎回そのルールを踏まえて生成・レビューします。CLAUDE.mdの書き方はClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンで扱っています。

レビューでは「説明文が実装と一致しているか」を人間が最終確認します。特に変更ログは、実装していない機能が紛れ込んでいないか、影響範囲の説明が誇張されていないかをチェックします。生成された文章をそのままコミットせず、diffとして一度目を通す工程を必ず挟みます。

複数モジュールにまたがる大規模リポジトリで一括して棚卸しをしたいときは、/batch を使う方法もあります。作業をモジュール単位の独立したまとまりに分解し、それぞれ別のworktreeで並列に処理させられるため、ドキュメント未整備箇所が多いプロジェクトでも1つずつ順番に頼むより短時間で回せます。ただし並列実行した結果は各worktree単位でレビューが必要になるため、変更範囲がある程度大きいときに限定して使う方が扱いやすくなります。

チームで表記を揃えるにはSkillが効く

複数人でClaude Codeを使う場合、同じ指示を毎回書き直すのは非効率です。ドキュメントの書式ルールをSkillとして登録しておくと、メンバーごとに指示文がぶれる問題を避けられます。

Skillはプロンプトとして渡す設定ファイルで、「このプロジェクトのAPIドキュメントはRESTfulな命名規則に従う」のような規約をまとめておけば、Claude Codeが会話の流れで自動的に参照します。CLAUDE.mdが常にセッション全体へ読み込まれるのに対し、Skillはドキュメント生成のような特定作業のときだけ参照される点が違います。プロジェクト全体で常に効かせたいルールはCLAUDE.mdへ、ドキュメント生成時だけ効けばよい細かいルールはSkillへ、と役割を分けると管理しやすくなります。

よくあるつまずき

生成作業を実際にやってみると、次のようなつまずきが起きやすくなります。

• 対象を絞らずに依頼してディレクトリ全体が変更される: 差分が大きくなりすぎ、レビューが現実的でなくなります。ファイル単位・モジュール単位で区切って依頼します
• スタイルが混在する: 同じプロジェクト内でJSDocとGoogleスタイルが混ざるなど、指定を省略した結果スタイルが揃わないことがあります。CLAUDE.mdかSkillに書式を明記しておくと防げます
• 変更ログにハルシネーションが混入する: 範囲を指定せずに変更ログを書かせると、実際にはないコミットの内容が紛れ込むことがあります。git log の範囲を必ず具体的に指定します
• 自明なコードまで過剰にコメントされる: getter/setterのような自明な関数まで一律にコメントが付き、かえって読みにくくなることがあります。対象を「公開APIのみ」のように絞ります
• レビューなしでコミットしてしまう: 生成された文章は自然に読めてしまうため、そのままコミットしがちです。実装との整合性は必ず人間が確認します

よくある質問

生成されたコメントが冗長すぎるときはどう調整すればいいですか

「1文で要約して」「実装の詳細ではなく、呼び出し側が知るべきことだけ書いて」のように、文量と粒度を具体的に指定すると簡潔になります。既存のコメントを1つ例として渡し、「この長さ・トーンに揃えて」と依頼する方法も効果的です。

既存のREADMEを全面的に書き直させても大丈夫ですか

大きな構成変更は差分が広がりレビューが難しくなるため、セクション単位での更新を積み重ねる方が安全です。「セットアップ手順のセクションだけ更新して」のように範囲を区切って依頼します。

変更ログの生成にはどのgitコマンドが使われますか

Claude Codeは git log や git diff を実際のツール呼び出しとして実行し、その出力をもとに文章を組み立てます。範囲(タグ間・コミットハッシュ間)を具体的に指定することで、実行対象のコミット範囲を制御できます。

コメント生成をCIに組み込めますか

Claude Codeはヘッドレスモードでの実行にも対応しており、コミットやPR作成時にドキュメント生成・チェックを自動実行するパイプラインへ組み込む運用も可能です。ただし生成結果を無検証でマージする運用は避け、レビュー工程を残すことをおすすめします。

複数言語が混在するモノレポでも使えますか

使えます。対象言語ごとにスタイルの指定を変え、ディレクトリ単位で依頼を分けるとスタイルの混在を避けられます。モノレポでのCLAUDE.md設計はClaude Codeモノレポ設計 — CLAUDE.md階層とパッケージ単位の権限スコープで扱っています。

まとめ

Claude Codeのドキュメント生成は、未文書化コードの洗い出し→生成→検証という3段階を踏むと安定します。範囲を絞って依頼し、書式ルールをCLAUDE.mdかSkillに固定し、生成後は必ず実装との整合性をレビューする。この3点を守れば、READMEや変更ログが実装からずれていく問題を継続的に抑えられます。チームで導入する場合は、書式ルールを個人の指示文に任せず共有設定へ移すことが定着の分かれ目になります。