agentic-jsdoc は何をしますか？
LLMによる解析に最適化されたJSDocの作成とレビューを行い、エージェント型RAGの取得とアーキテクチャ理解を最大化します。
概要
このスキルは、AIエージェントがコードベースを効率的に解析し、タスクを実行できるように、JSDocコメントを最適化するためのものです。従来の人間向けのドキュメントとは異なり、LLM（大規模言語モデル）が自然言語処理とベクトル検索（RAG）を活用して、関数の目的、パラメータ、戻り値、副作用を正確に解釈できるように設計されています。
機能
- JSDocの作成: 関数、クラス、モジュールに対して、LLMが解析しやすい形式でJSDocを自動生成します。
- JSDocのレビュー: 既存のJSDocを分析し、LLMによる理解を妨げる可能性のある曖昧さや欠落を特定します。
- RAG最適化: ドキュメント内に意味的にリッチな説明、型情報、エッジケース、重要なロジックへの注釈を含めることで、ベクトル検索の精度を向上させます。
対応プラットフォーム
- Claude Code
- Cursor
- Codex
- その他のJSDocをサポートするAIエージェント
使用方法
- プロジェクトのルートディレクトリに移動します。
- 以下のコマンドを実行してスキルをアクティブにします。
# 例: Claude Codeの場合
claude use jbelew/agentic-jsdoc
- スキルがアクティブになると、コード内のJSDocの作成またはレビューを依頼できます。
例
JSDocの作成
関数に対してJSDocを生成するには、以下のように依頼します。
この関数にJSDocを追加してください:
function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
スキルは以下のようなJSDocを生成します。
/**
* 商品リストから合計金額を計算します。
*
* @param {Array<{price: number, quantity: number}>} items - 価格と数量を含む商品オブジェクトの配列。
* @returns {number} すべての商品の合計金額。配列が空の場合は0を返します。
* @example
* // 使用例
* const total = calculateTotal([{ price: 10, quantity: 2 }, { price: 5, quantity: 3 }]);
* // totalは35になります
*/
function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}
JSDocのレビュー
既存のJSDocをレビューするには、以下のように依頼します。
このJSDocをレビューし、LLMの解析を最適化するための改善点を提案してください:
/**
* ユーザーを取得します。
* @param {number} id
*/
function getUser(id) {
// ...
}
スキルは、説明の追加、戻り値の型、エッジケースの文書化などを提案します。
設定
特に設定は必要ありません。スキルはプロジェクトの既存のJSDoc設定を尊重しますが、最適な結果を得るために、プロジェクトで@paramや@returnsタグが使用されていることを確認してください。
注意事項
- このスキルはJSDocの記述スタイルを変更する場合があります。既存のコーディング規約と競合する場合は、適宜調整してください。
- 生成されたJSDocは常にレビューし、正確性とコンテキストの適切性を確認することを推奨します。