Claude Codeでコメント・docstringを整備する【2026】

「あとでコメント書こう」と思って数ヶ月、というコードは誰にでもあります。正直に言うと、ドキュメント整備はやる価値が分かっていても、後回しにされる代表格ですよね。

Claude Code は既存コードを読んで docstring やコメントの叩き台を作るのが得意です。実際に大規模リポジトリ（数十万行規模）の整備を進めたチームでも、ゼロから人が書くより「叩き台を直す」ほうが圧倒的に速い、という声が多いです。一方で、これを丸投げにすると実装と食い違った嘘ドキュメントを量産しかねません。本記事では、2026年6月時点の Claude Code 公式仕様に沿って、コメント・docstring を「速く、かつ正確に」整備する実践手順をまとめます。

なお、本記事の手順は一般化した実装パターンの解説です。記載した時間短縮の感触はチーム規模やコード状態に依存するため、自分の環境で小さく試してから判断してください。

そもそもコメントと docstring は何が違うのか

整備を始める前に、対象を整理しておきます。雑にひとくくりにすると、どこに何を書くべきか曖昧になり、Claude Code への指示もぶれます。

• インラインコメント：実装の「なぜ」を補足する。// ここは API のレート制限を避けるため意図的に直列化 のような、コードを読んでも分からない背景を残す。
• docstring（ドキュメンテーション文字列）：関数・クラス・モジュールの「契約」を書く。引数・戻り値・例外・使い方。Python なら関数直下の三重引用符、JS/TS なら JSDoc 形式の /** ... */。

Python の docstring の置き場所と基本ルールは PEP 257（Docstring Conventions） が標準です。JavaScript / TypeScript なら JSDoc のタグ（@param / @returns / @throws）が事実上の共通言語になります。Claude Code に整備を頼むときも、この「どの規約に寄せるか」を最初に決めておくと出力が安定します。

Step 1: 未文書化のコードを洗い出す

いきなり「全部にコメントを付けて」と頼むと、範囲が広すぎて精度が落ちます。まずは対象の可視化から始めるのが定石です。Claude Code 公式の Handle documentation ワークフローでも、最初のステップは「文書化されていない箇所を見つける」です（出典: code.claude.com 公式ドキュメント common-workflows、2026年6月時点）。

1. 対象モジュールを絞る（いきなりリポジトリ全体を対象にしない）。
2. 未文書化の関数を列挙させる。
3. 列挙結果を見て、優先度の高い public API から着手する。

列挙を頼むときのプロンプト例です。@ でファイルを直接参照すると、Claude が読み込みを待たずに対象を特定できます（@ ファイル参照は公式機能）。

find functions without proper JSDoc comments in @src/auth/

各関数について、以下の表で返してください。
- ファイルパスと関数名
- public か internal か
- 引数・戻り値が型情報から自明か、コメントが必要か

不足している情報があれば、最初に質問してから作業を開始してください。
仮定した点は必ず"仮定"と明記してください。

ポイントは「列挙だけさせて、まだ書かせない」こと。ここで全体像を人が確認してから次に進むと、無駄な大量生成を避けられます。

Step 2: docstring・コメントの叩き台を生成する

洗い出しが済んだら、書式を指定して叩き台を作らせます。書式を曖昧にすると、Python なのに JSDoc 風になったり、プロジェクトの既存スタイルと混ざったりします。規約を明示するのが事故防止の第一歩です。

Python（PEP 257 準拠）の例です。

@src/services/billing.py の calculate_invoice 関数に
PEP 257 準拠の docstring を追加してください。

要件:
- 1行サマリ + 空行 + 詳細説明
- Args / Returns / Raises を Google スタイルで記述
- 実装から読み取れない「なぜ」だけをインラインコメントに残す
- 型ヒントで自明な情報をコメントで重複させない

実装を読んで確証が持てない引数の意味は、断定せず "要確認" と書いてください。

生成される docstring のイメージはこうなります。

def calculate_invoice(items, tax_rate, currency="JPY"):
    """注文明細から請求金額を計算して返す。

    端数は currency ごとの最小単位で切り捨てる（要確認: JPY 以外の挙動）。

    Args:
        items (list[LineItem]): 請求対象の明細。空リストは 0 を返す。
        tax_rate (float): 税率。0.10 のような小数で指定する。
        currency (str): ISO 4217 通貨コード。デフォルトは "JPY"。

    Returns:
        Decimal: 税込みの合計金額。

    Raises:
        ValueError: tax_rate が負のとき。
    """

JavaScript / TypeScript なら JSDoc 形式を指定します。

@src/lib/retry.ts の withRetry に JSDoc を追加してください。

要件:
- @param / @returns / @throws を付ける
- @example に最小の使用例を1つ
- ジェネリクスの型パラメータも説明する

複数ファイルをまとめて渡したい場合は @file1.ts and @file2.ts のように1メッセージで複数参照できます。ただし、一度に大量を投げると人のレビューが追いつかないので、5〜10関数くらいの粒度に区切るのが現実的です。

このあたりは大規模コードベースの読み解き方とも地続きで、構造把握から入るアプローチはClaude Codeで大規模コードベースを理解するガイドでも詳しく扱っています。

Step 3: コードとドキュメントの同期を保つ運用

ドキュメント整備で一番つらいのは「最初に書くこと」ではなく「更新し続けること」です。実装を変えたのに docstring が古いまま、というのが嘘ドキュメントの典型的な発生源です。Claude Code を使う場合は、生成だけでなく更新の流れも仕組み化します。

1. 差分ベースで更新を頼む。新規生成ではなく「変更箇所のドキュメントだけ直す」に限定する。
2. レビュー前に変更を確認する。Plan モードを使えば、ファイルに書き込む前に変更計画を確認できます（公式機能）。
3. CI に組み込む。非対話モードで Claude をスクリプトにパイプし、未文書化の検出や差分チェックを自動化する。

差分ベースの更新プロンプト例です。コミット差分を直接渡します。

git diff HEAD~1 した変更のうち、
シグネチャや挙動が変わった関数だけを対象に、
docstring / JSDoc を実装に合わせて更新してください。

- 変わっていない関数のコメントは触らない
- 実装と既存コメントが矛盾している箇所は、修正案と理由を別途リストにする

CI で「未文書化を増やさない」ゲートを作るなら、非対話モード（claude -p）でスクリプトに組み込めます。

git diff origin/main...HEAD --name-only \
  | claude -p "この差分で新しく追加された public 関数のうち、docstring が無いものをリスト化して。なければ 'OK' とだけ返して。"

「いつ・どの粒度で更新するか」をルール化しておくと、ドキュメントの腐敗を抑えられます。差分レビューの標準化はClaude Codeでコードレビューを効率化する実践ガイドと組み合わせると効きます。

Step 4: 規約・方針を CLAUDE.md に固定する

毎回プロンプトで「PEP 257 で」「JSDoc で」と書くのは面倒だし、メンバーによってブレます。Claude Code の CLAUDE.md はプロジェクトのコーディング規約や慣習を毎セッション読み込ませるための仕組みで、ここにドキュメント方針を書いておけば指示が安定します（出典: code.claude.com 公式ドキュメント memory、2026年6月時点）。

具体的に書くのがコツです。公式も「Format code properly ではなく Use 2-space indentation」のように検証可能な粒度を推奨しています。ドキュメント方針なら、たとえば次のように書きます。

# Documentation conventions

- Python の docstring は PEP 257 準拠・Google スタイル（Args/Returns/Raises）
- JS/TS は JSDoc。public 関数には @param / @returns / @throws を必須
- 型ヒント・型注釈で自明な情報をコメントで重複させない
- 「なぜ」だけをインラインコメントに残す（「何を」はコードで表現）
- 実装から確証が持てない箇所は "要確認" と明記し、断定しない

ファイル種別ごとに方針を分けたい場合は、.claude/rules/ に paths 付きのルールを置くと、対象ファイルを触ったときだけ読み込まれます。CLAUDE.md は200行以内に保つのが推奨なので、規約が膨らんできたらこちらに切り出します。CLAUDE.md 設計そのものはCLAUDE.md設計・運用ガイドにまとめています。

Step 5: 生成物を人がレビューする（嘘ドキュメント対策）

ここが本記事で一番強調したい部分です。生成された docstring は「もっともらしいが間違っている」ことがあります。実装を読んでいるとはいえ、Claude が挙動を推測で埋めるケースは普通にあります。レビューなしで公開ドキュメントに反映すると、嘘ドキュメントが固定化されて後で大きな負債になります。

レビューで最低限確認したいチェックポイントです。

1. 実装と一致しているか：引数の意味・戻り値・例外が、実際のコードの挙動と合っているか。特に「要確認」と書かれた箇所は必ず人が埋める。
2. 過剰コメントになっていないか：i += 1 # i に 1 を足す のような、コードを読めば分かる説明を量産していないか。
3. 機密情報が紛れていないか：API キー、内部URL、顧客名、未公開の仕様などをコメントに書かせていないか。生成物は人の目で確認する前提にする。
4. 古い前提を引きずっていないか：既存コメントが間違っていた場合、それをそのまま踏襲していないか。

図やサンプルを入れる場合も同じです。docstring の @example や使用例コードは、実際に動く形かを必ず人が確認します。動かないサンプルは、無いより有害なことがあります。

【要注意】よくある失敗パターンと回避策

失敗1：範囲を絞らず「全部にコメント」と頼む

❌「このリポジトリ全部に docstring 付けて」
⭕「@src/auth/ の未文書化 public 関数だけ、PEP 257 で叩き台を作って」

なぜ重要か：範囲が広いとレビューが破綻し、結局誰も確認しないまま大量のコメントだけ残ります。可視化→小さく区切る、が鉄則です。

失敗2：規約を指定せず書式がバラバラになる

❌「いい感じにコメント付けて」
⭕「JSDoc 形式で @param / @returns / @throws を必須に」

なぜ重要か：書式がブレると、後から lint や doc 生成ツールに通らず、整備したつもりが二度手間になります。規約は CLAUDE.md に固定するのが確実です。

失敗3：生成物を確認せず反映する

❌ 生成された docstring をそのままコミット
⭕ 「要確認」「推測で埋めた箇所」を人が検証してからコミット

なぜ重要か：嘘ドキュメントは、コードのバグより発見が遅れます。正直にお伝えすると、AI が生成したドキュメントの正確性チェックは省略できません。AI は補助ツールであり、最終判断者ではありません。所属組織のコーディング規約・公開ポリシーに従ってください。

よくある質問（FAQ）

Q1. Claude Code は本当にコメント・docstring を生成できますか？

はい。公式の Handle documentation ワークフローとして、未文書化関数の検出、JSDoc / docstring の追加、生成物の改善が手順化されています（出典: code.claude.com 公式ドキュメント、2026年6月時点）。ただし生成物は人のレビューが前提です。

Q2. PythonとJavaScriptで書き方は変わりますか？

変わります。Python は PEP 257 に沿った docstring、JS/TS は JSDoc 形式が標準です。どちらに寄せるかをプロンプトか CLAUDE.md で指定すると、出力が安定します。

Q3. ドキュメントとコードがズレるのを防ぐには？

新規生成ではなく差分ベースの更新に限定し、Plan モードで変更を確認してから反映するのが基本です。CI に claude -p を組み込み、未文書化の増加を検出する運用も有効です。

Q4. 生成されたコメントはそのまま使って大丈夫ですか？

いいえ。実装との一致、過剰コメント、機密情報の混入を人が確認してください。特に「要確認」と明記された箇所は、推測のまま残さず人が埋めます。

Q5. CLAUDE.md には何を書けばいいですか？

ドキュメント規約（PEP 257 / JSDoc）、必須タグ、「なぜ」だけを書くなどの方針を、検証可能な具体度で書きます。規約が増えたら .claude/rules/ に paths 付きで切り出すと、対象ファイルを触ったときだけ読み込まれます。

まとめ：今日から始める3つのアクション

1. 担当モジュール1つで未文書化の public 関数を列挙させ、対象を可視化する。
2. 規約（PEP 257 / JSDoc）を指定して5〜10関数だけ叩き台を作り、人がレビューする。
3. うまくいった方針を CLAUDE.md に書き、次回以降のブレをなくす。

ドキュメント整備は「速く作る」より「正確に保つ」ほうが本質です。Claude Code は初速を上げる強力な道具ですが、嘘ドキュメントを生まない最後の砦は人のレビューです。整備の全体像を体系的に押さえたい方は、Claude Code 実践テクニック完全ガイドもあわせてどうぞ。

著者プロフィール

佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。

参考・出典

• Claude Code 公式ドキュメント — Common workflows（Handle documentation / Reference files with @）
• Claude Code 公式ドキュメント — How Claude remembers your project（CLAUDE.md / .claude/rules/）
• Claude Code 公式ドキュメント — Best practices
• PEP 257 — Docstring Conventions（Python 公式）
• JSDoc 公式リファレンス
• Google Python Style Guide（docstring の Google スタイル）

あわせて読みたい：正規表現をClaude Codeで作る・読み解く実践ガイド【2026】

あわせて読みたい：Python開発をClaude Codeで効率化する実践ガイド【2026】

関連記事（自動）

• ▸ Claude Codeで依存関係を可視化・改善する実践ガイド【2026年最新】
• ▸ Claude Code Dev Container安全導入
• ▸ Claude CodeでADR導入｜設計判断を自動記録・共有する実践ガイド
• ▸ Webマーケ担当者がClaude Codeで広告レポートを自動化【2026年版】
• ▸ 【2026年版】Claude Code×ゲーム開発｜Unity実践ガイド