JSDocでGitHub Copilotの提案が良くなった：AI開発での実用的な活用方法

2025年9月8日(月)11日前

GitHub CopilotでのAI開発が日常的になってきた中で、JSDocを書くことでAIの理解精度が変わるのではないかと考え、実際に試してみました。フロントエンド中心の内容になりますが、実用性を重視した観点から効果を共有したいと思います。

なぜJSDocがAI開発に重要なのか

AI開発が当たり前になってきた現在、業務でCopilotを使う機会が増えています。しかし、コードを見ただけでは「なぜこの機能が必要なのか」「どう使うのが正解なのか」といった背景をAIが理解しにくいという課題があります。

チーム開発では「なんでこうなってるんだっけ？」という状況がよく発生します。JSDocでAIにより多くの文脈を伝えることで、この問題を解決できるのではないかと考えました。

AIが困ってしまうこと

AIエージェントには主に2つの課題があります。コンテキストの不足により、コードの動作は分かっても設計の意図や使用方法が理解しにくいこと、そしてプロジェクト固有の暗黙知（命名ルール・制約条件・コンポーネント間の関係性）が把握できないことです。

JSDocでこの問題を解決する

AI開発では、既存のコンポーネントの用途や使い方をAIが理解するのに時間がかかるという課題があります。JSDocを追加してから、この状況が改善されました。

実例：ボタンコンポーネントの変化

JSDocなし：AIはコードの実装しか把握できない

TSX

export default function Button({ variant, size, children, onClick }: ButtonProps) {
  return (
    <button 
      className={`btn ${variant} ${size}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

JSDoc追加後：AIが目的・使い方・制約を瞬時に理解

TSX

/**
 * 汎用ボタンコンポーネント
 * @description アクション実行用の統一されたボタンUI
 * @param variant - ボタンの種類（primary: 主要アクション、secondary: 補助アクション）
 * @param size - ボタンサイズ（small: 12px、medium: 16px、large: 20px）
 * @example
 * // 保存ボタン（主要アクション）
 * <Button variant="primary" size="medium" onClick={handleSave}>
 *   保存
 * </Button>
 * 
 * // キャンセルボタン（補助アクション）
 * <Button variant="secondary" size="small" onClick={handleCancel}>
 *   キャンセル
 * </Button>
 * @constraints
 * - 重い処理の場合はdisabled状態を設定すること
 * - destructive操作は確認ダイアログと組み合わせること
 */
export default function Button({ variant, size, children, onClick }: ButtonProps) {
  return (
    <button 
      className={`btn ${variant} ${size}`}
      onClick={onClick}
    >
      {children}
    </button>
  );
}

実際に感じられた効果

JSDocを追加してから、AIが生成するコードの精度が向上しました。以前は「なんか違うな」と感じることが多かったのですが、プロジェクトの書き方に合ったコードを提案してくれることが増えました。手直しの回数が減り、その分を他の作業に充てられるのは実用的なメリットです。

効果的なJSDocの書き方

AIに理解してもらいやすいJSDocを書くポイントは、@descriptionでコンポーネントの目的を明確に記述し、@paramで各パラメータの使い方を「primary: 主要アクション」「small: 12px」のように具体的な値と共に説明することです。@exampleには実際の使用例を、@constraintsには注意事項を記載することで、AIが適切な提案をしてくれるようになります。

導入時のアプローチ

実際の導入では、いきなり全部やるのは現実的ではないため、Button・Input・Cardなど使用頻度の高いコンポーネントから始めるのが合理的です。記述内容を統一しておかないと、AIが混乱する可能性もあります。

面白いことに、JSDocの記述自体もAIに書かせることができます。既存のコンポーネントを見せて「このコンポーネントにJSDocを追加して」と指示すると、適切な形式でドキュメントを作成してくれます。手動より効率的で、継続性も保てます。

導入効果の実感

導入から一定期間経った今、AIの提案がプロジェクトの書き方に沿うようになりました。以前は「このコンポーネント、どう使うんだっけ？」と考える時間がありましたが、それが減りました。長期的には、不適切な使い方によるバグも減っているように感じます。

まとめ

JSDocを書くことでAIがコードの背景を少し理解してくれるようになりました。単純にドキュメントを作成するというより、AIと協働するための仕組みとして捉えると実用的な価値があると思います。

JavaScript/TypeScriptでAI開発をしている方には、検討してみることをおすすめします。初期の手間はかかりますが、長期的には投資に見合う効果が得られるのではないでしょうか。

utsusie

UI Designer / Web Director