コードドキュメントをClaudeに書かせる技術

ドキュメントを書くのが面倒で後回しにしてしまう、そんな経験は誰にでもあるはずです。Claude Codeを活用すれば、JSDocやTypeDocのコメントを高品質で自動生成できます。コツはプロンプトの伝え方にあります。

基本プロンプト：「何を」「どの形式で」を明示する

Claude Codeに漠然と「ドキュメントを書いて」と頼むだけでは、品質にばらつきが出ます。次のように「対象・形式・含めるべき情報」を具体的に指示しましょう。

以下のTypeScript関数にJSDoc形式のドキュメントを追加してください。
- @param、@returns、@throws、@example を必ず含める
- 引数と戻り値の型はTypeScriptの型定義から読み取る
- @example には実際の使用例をコードで示す

このように箇条書きで条件を列挙すると、Claude Codeは抜け漏れなくドキュメントを生成してくれます。

※TypeScript: JavaScriptに型定義を追加した言語。型チェックによりバグを事前に発見しやすくなる。※プロンプト: AIへの指示文。Claude Codeへの指示の質がそのまま出力の質に影響する。

ファイル全体を一括処理するコマンド例

個別関数だけでなく、ファイル全体のドキュメントを一括生成させることもできます。Claude Codeのチャット欄で以下のように入力してみましょう。

@src/utils/api.ts を開いて、すべてのexportされた関数・クラス・インターフェースに
TypeDoc互換のJSDocコメントを追加してください。
既存のコメントがある場合は内容を確認して補完してください。
変更後のファイル全体を出力してください。

実際に生成されるドキュメントの例はこのようになります。

/**
 * ユーザー情報をIDで取得する
 *
 * @param userId - 取得対象のユーザーID
 * @param options - 追加オプション（省略可）
 * @returns ユーザー情報のPromise
 * @throws {NotFoundError} 指定したIDのユーザーが存在しない場合
 * @example
 * const user = await getUser("u_12345");
 * console.log(user.name); // "山田太郎"
 */
async function getUser(userId: string, options?: GetUserOptions): Promise<User> {
  // ...
}

品質を上げる追加テクニック

生成結果の品質をさらに高めるには、プロジェクトのコーディングスタイルをClaudeに事前に伝えるのが効果的です。CLAUDE.md にドキュメントの規約を記載しておくと、毎回指示しなくても一貫したスタイルで生成されます。

また、生成後に「このドキュメントに不足している情報や誤りがあれば指摘してください」とレビューを依頼するのもおすすめです。Claudeが自分の出力をセルフチェックする形になり、精度が上がります。

一度よいプロンプトのテンプレートができれば、あとはコードを貼り付けるだけで高品質なドキュメントが手に入ります。ぜひ自分のプロジェクトに合わせてカスタマイズしてみてください。

※CLAUDE.md: プロジェクトのルートに置くClaude Code専用の設定ファイル。プロジェクト固有のルールやコンテキストを記述する。