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

生成させるときは、スタイルを明示します。公式の対応レシピにも「JSDocやdocstringなど、使いたい書式を指定する」というヒントがあり、プロジェクトにスタイルが混在しているなら特に効きます。

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

コメントが付いたら、そのまま続けて補強を頼みます。公式のレシピは、この工程を独立した手順に置いています。

improve the generated documentation with more context and examples

「この関数の意図と、なぜこの実装になったかの背景も含めて」「使用例を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

始点と終点を示すと、どのコミットが材料かが依頼文に残ります。生成後に git log v1.2.0..HEAD の出力と見比べれば、実装していない変更が紛れ込んでいないかを突き合わせられます。

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

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

check if the documentation follows our project standards

CLAUDE.mdがまだ無いプロジェクトでは、/init で雛形を作れます。環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると、Skillやhooks、個人用のメモリーファイルまで順に案内する対話式の流れになります。書式ルールを置く先を決めながら進められます。そのうえでCLAUDE.mdにドキュメントの書式ルール(コメントの言語、必須項目、禁止表現など)を書いておくと、Claude Codeは毎回そのルールを踏まえて生成・レビューします。CLAUDE.mdの書き方はClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンで扱っています。

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

複数モジュールにまたがる大規模リポジトリで一括して棚卸しをしたいときは、/batch を使う方法もあります。

変更は単位ごとに分かれて届くので、レビューも単位ごとに行います。始められない場合の前提条件は、末尾のつまずきの項に挙げています。

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

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

Skillは SKILL.md に書く指示書です。プロジェクト内の .claude/skills/<名前>/SKILL.md に置いてコミットすれば、同じリポジトリのセッションでチーム全員に届きます。~/.claude/skills/ に置いた個人用のSkillは、自分のマシンの全プロジェクトで使えます。

---
description: JSDocとREADMEの書式ルール。ドキュメントを書く・直すときに使う
---
 
- 公開関数だけにJSDocを付ける。`@param` と `@returns` は必須
- 説明文は日本語で、1文目に要約を置く
- 自明なgetter/setterにはコメントを付けない

description に書いた内容に合う依頼が来ると、Claude Codeが自動で読み込みます。.claude/skills/ の中身は、Skillの追加・編集・削除がセッション中にも反映されます(再起動は不要です)。自動で呼ばれたくないSkillには disable-model-invocation: true を付けると、/名前 で呼んだときだけ働きます。

CIからドキュメント生成を回す

コミットやPR作成のタイミングで生成・チェックを走らせたいときは、非対話モードの -p(--print)を使います。claude --help(v2.1.287)には、このときに関わる次のオプションが出ています。

変更ログの生成を例にすると、許可するツールをgitの参照と編集に絞った呼び出しになります。

claude -p "Summarize the commits between v1.2.0 and HEAD into CHANGELOG.md" \
  --allowedTools "Bash(git log *)" Edit \
  --max-budget-usd 1

CIで --bare を付けると起動が最小構成になります。ヘルプによると、--bare はhooks・プラグイン同期・自動メモリーに加えて、CLAUDE.mdの自動探索も飛ばします。認証もOAuthやキーチェーンを読まず、ANTHROPIC_API_KEY かapiKeyHelperだけです。つまりCLAUDE.mdに書いた書式ルールは自動では届かないため、--append-system-prompt か --add-dir で明示的に渡します。Skillは /名前 で呼べば解決されます。

--print の説明には、非対話で動かすとワークスペースの信頼ダイアログが省かれる、とあります。信頼できるディレクトリでだけ使います。生成結果をそのままマージせず、PRとして人が読む段を残します。--max-budget-usd で上限を置いておけば、指示が曖昧で作業が膨らんだときも費用が青天井になりません。

よくあるつまずき

Skillやworktreeを使い始めると、次の点で引っかかります。

• サブディレクトリのSkillが / メニューに出ない: 起動した場所より下の .claude/skills/ は、起動時には読み込まれません。そのディレクトリのファイルをClaude Codeが読むか編集した時点で読み込まれ、/add-dir にパスを渡せば先に読み込めます(v2.1.257以降)。モノレポで頻出します
• ルーチンやクラウドセッションでSkillが見つからない: これらは ~/.claude/skills/ を読みません。個人用のSkillをそこで使うには、リポジトリの .claude/skills/ にコミットします
• スタイルが混在する: 書式の指定を省くとJSDocとGoogleスタイルが混ざることがあります。CLAUDE.mdかSkillに書式を明記しておきます
• /batch が始まらない: gitリポジトリ、または WorktreeCreate hookでworktreeを作る構成が必要です。リポジトリ外ではv2.1.281以降が必要です

よくある質問

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

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

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

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

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

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

まとめ

3種類の生成物のうち、実装とのずれが読み手に最も響くのは変更ログです。実装していない機能の混入や影響範囲の誇張は、git log の出力と突き合わせないと見つかりません。対話で頼むなら生成直後のdiffで、CIで回すなら生成結果をPRとして残して、人が読む段を厚くします。