tsdoc

tsdoc — SKILL.md

バリアント： 標準 · 使用するタイミング： スキルが呼び出され、TypeScript ファイルまたはコード領域に適用されて、ドキュメント化されたコードや規約の判断を返し、制御が呼び出し元に戻るとき。

概要

TSDoc は、TypeScript のドキュメントコメント、つまり宣言の直前に置く /** ... */ ブロックに関する Microsoft の標準文法です。標準ではタグのセットとパーサー（@microsoft/tsdoc）が定められているため、TypeDoc、API Extractor、エディターの IntelliSense などの独立したツールが、コメントの構造について一貫した解釈を行えます。このスキルは、コメントを記述する際の規約です。どのシンボルにドキュメントコメントを付けるか、どの TSDoc タグをどのように使うか、そして TSDoc と従来の JSDoc を分ける唯一のルール、つまりコメントに型を繰り返し記述しないことを定めます。型はすでに TypeScript の型情報が表しているため、コメントでは意図と動作を説明します。これは、公開 API のドキュメント文字列を整備する規律（たとえば、ドキュメント文字列リンターでチェックする Python の Google スタイルドキュメント文字列）に相当する TypeScript 版です。エクスポートされた API 領域を記述し、余計なものは省きます。

有効にするタイミング

• ✅ エクスポート済み／公開 TypeScript シンボル（関数、クラス、型／インターフェイス、React コンポーネントとその props、カスタムフック）にドキュメントコメントを記述するとき。
• ✅ TS コードベースのドキュメントコメント規約を定める、または文書化するとき。
• ✅ 特定のシンボルについて、何をどのように（どのタグを使って）記述するか判断するとき。
• ✅ 既存のコメントをレビュー／修正するとき。たとえば、TS の型と重複する JSDoc 形式の {type} 注釈を削除したり、@return を @returns に修正したりするとき。

次の場合は有効にしないでください：

• 生成ドキュメントのサイトをセットアップする場合。これは TypeDoc の役割です。このスキルでは参照先として示すだけです（「注意点」を参照）。
• コンポーネントカタログやインタラクティブなドキュメントを作成する場合。これは Storybook の役割であり、対象外です（参照先として示すだけです）。
• 一般的なコードスタイルをリンティングまたはフォーマットする場合。これはプロジェクトのリンター／フォーマッター（例：Biome）の役割です。ドキュメントコメントの内容は検証しません。
• 型システムのないプレーンな JavaScript で型を注釈する場合。これは JSDoc を型として使う別の慣習であり、このスキルは TypeScript での使用を明示的に推奨しません。

ワークフロー

ステップ 1：シンボルにドキュメントコメントを付けるか判断する

モジュールの利用者がアクセスする公開／エクスポート済み API 領域を記述します。それ以外は省きます。重要なのはタグの一覧ではなく、この判断です。

記述する対象：

• エクスポートされた関数、クラス、メソッドのうち、名前とシグネチャだけでは動作が完全には明らかでないもの。
• エクスポートされた型とインターフェイス。特に React コンポーネントのprops インターフェイス（自明でない各フィールドに1行の説明を付けます）。
• エクスポートされた React コンポーネントとカスタムフック。レンダリングする内容／返す内容と、自明でないパラメーターやオプションを記述します。

省略する対象（記述しない）：

• 利用者が使う領域の一部ではない非公開／内部シンボル。ツール用にエクスポートされているものの、サードパーティ向けではないシンボルには、公開 API として記述するのではなく @internal 修飾子を付けます。
• 機械生成コード。たとえば OpenAPI／openapi-ts クライアントやコード生成の出力です。生成されたコメント（またはコメントがないこと）はジェネレーターが管理します。手作業で上書きしないでください。
• 名前と型だけで内容がすべて分かる、自明な一行のもの（isEnabled: boolean、値をそのまま返すゲッターなど）。
• 型を言い換えるだけの文章（ステップ 3 の基本ルールを参照）。

ステップ 2：概要を書き、その後 @remarks に詳細を加える

最初の段落、つまり最初のブロックタグより前のすべての部分が概要です。簡潔にまとめてください。ドキュメントサイトでは API インデックスの一覧に表示されます。シンボルの機能を説明する簡潔な文から始めます。

長めの説明（注意事項、設計上の注記、背景情報、関連 API へのリンク）は @remarks ブロックに記述します。@remarks で概要を終え、詳細セクションを始めます。概要を繰り返さないでください。

/**
 * Returns the arithmetic mean of two numbers.
 *
 * @remarks
 * Both inputs are treated as finite; passing `NaN` propagates `NaN`.
 * For a list of values, use {@link average} instead.
 *
 * @param x - The first input number
 * @param y - The second input number
 * @returns The arithmetic mean of `x` and `y`
 *
 * @example
 * Basic usage:
 *
 *     mean(2, 4); // 3
 */
export function mean(x: number, y: number): number {
  return (x + y) / 2;
}

ステップ 3：型ではなく意図を文書化する（TSDoc と JSDoc）

最も重要な原則です。JSDoc では歴史的に、プレーンな JavaScript には型がなかったため、コメント内に型を注記していました（@param {string} name）。TypeScript ではコード内ですでに型を宣言するため、TSDoc タグに {type} は含めません。TSDoc の @param は、@param name - description の形式です。それ以上でもそれ以下でもありません。文書化するのは、なぜ／どのように／何を意味するかであり、型が何かではありません。

// ANTI-PATTERN — JSDoc-style type annotation, redundant with the TS signature
/**
 * @param {string} userId  the user id
 * @param {number} limit   the limit
 * @returns {Promise<User[]>}
 */

// CORRECT — TSDoc: hyphen syntax, no types, documents intent
/**
 * Fetches the most recent users created by `userId`'s organization.
 *
 * @param userId - Owner whose organization is queried
 * @param limit - Maximum rows to return; the server caps this at 100
 * @returns The users, newest first
 */
export async function recentUsers(userId: string, limit: number): Promise<User[]> { /* ... */ }

仕様上、@param name - description のハイフンは必須です。省略すると TSDoc パーサーに警告されます。

ステップ 4：適切なタグを使う

references/tag-taxonomy.md にある分類（ブロック／インライン／修飾子）を使用してください。タグごとの詳細が必要な場合は読み込んでください。日常的に使うタグは次のとおりです。

• @param name - desc、@returns desc — 重要な場合に、関数の入力／出力を説明します。
• @typeParam T - desc — ジェネリック型パラメーターを説明します（@param と同じハイフン構文です）。
• @remarks — 要約を超える詳細な説明を記述します。
• @example — 使用例のスニペットを記述します。最初の行は例のタイトルとして扱われます。
• @defaultValue — クラス／インターフェースのフィールドまたはプロパティのデフォルト値を記述します。
• @throws — 呼び出し元が把握しておくべき例外の型ごとに、ブロックを 1 つ記述します。
• @see — 相互参照を示します。@deprecated <message> — 削除予定であることを示し、代替手段を記載します。
• {@link Target | label}、{@inheritDoc} — インラインの相互参照／基底メンバーのドキュメントを継承します。
• @public / @internal / @beta / @alpha — 公開リリースで公開する内容を制御する、リリース段階の修飾子です。

ステップ 5：適用 — デフォルトでは規約のみ

コードをリントするリンター／フォーマッター（例：Biome）は、ドキュメントコメントの内容を検証しません。TSDoc 準拠ルールがないためです。そのため、デフォルトでは規約のみとします。このスキルを標準とし、追加のツールや 2 つ目のリンターは使いません。

プロジェクトで TSDoc の構文を CI により機械的に検証したい場合、公式ツールは eslint-plugin-tsdoc（単一ルール tsdoc/syntax）です。設定スニペットと明示的なトレードオフについては、references/enforcement.md を参照してください。**ESLint が必要なため、導入すると既存の高速なリンターとともに ESLint を再導入することになります。これは、単一リンター構成が避けようとしていた 2 つのリンターを使う状況です。**デフォルトではなく、任意で導入する CI の選択肢として扱ってください。

ルール

必ず守るルール（例外なし）：

• コメントに型を書かないでください。 TSDoc タグに {type} は含めません。型の信頼できる情報源は TS シグネチャであり、コメントは意図や動作を説明するためのものです。.ts／.tsx ファイルで JSDoc 形式の {type} 注記を提案したり記述したりしないでください。
• 公開される範囲を文書化し、それ以外は省略してください。 エクスポートされるシンボルや利用されるシンボルには、動作が自明でない場合にコメントを付けます。プライベート／内部のシンボル、生成コード、単純で自明なケースには、コメントを付けません。
• タグを正しく分類してください。 ブロックタグはセクションを導入します（行の先頭に置きます）。修飾子タグは内容を持たない単独のフラグです。インラインタグはテキスト内の {@...} です。標準外のタグを作らないでください。認識できないタグはパーサーに警告されます。
• @param／@typeParam ではハイフンを使ってください： @param name - description。@return ではなく @returns を使います。
• 要約は簡潔にし、詳細は @remarks に記載してください。 要約の段落にすべてを詰め込まないでください。

推奨事項（変更可）：

• デフォルトでは適用を規約のみとします。CI での構文検証が明示的に求められ、2 つ目のリンターを導入するコストが許容される場合に限り、eslint-plugin-tsdoc を追加してください。
• 自明なシグネチャを言い換えるよりも、自明でない動作やエッジケースの文書化を優先してください。
• 関連 API の説明を繰り返すのではなく、{@link} でつないでください。

注意点

• コードリンター／フォーマッターはドキュメントコメントをチェックしません。 Biome のようなツールはコードをリント／フォーマットします。ドキュメントコメントに最も近い機能でも、アスタリスクのフォーマット規則（useSingleJsDocAsterisk）と、未使用インポートの検出における {@link} 参照の追跡にとどまり、いずれも TSDoc への 準拠 を検証するものではありません。「リントに合格した」からといって、ドキュメントコメントが正しいとは限りません。これは規約、または eslint-plugin-tsdoc に関する問題です。
• @deprecated は修飾子ではなく、ブロック タグです。 仕様では、推奨される代替手段を示す末尾の文を付けます（@deprecated Use {@link newFn} instead.）。@internal のような内容のないフラグではありません。これを修飾子に分類するのはよくある誤りです。
• @return と @returns の違い。 TSDoc では @returns が標準です。@return は JSDoc の慣れによるよくある誤りで、パーサーに指摘されます。
• @param のハイフンを忘れないでください。 @param x The value は不正な形式です。@param x - The value とする必要があります。TSDoc パーサーはハイフンの警告を出します。
• {@inheritDoc} は概要と @remarks を継承しません。 コメントで {@inheritDoc} を使う場合、独自の概要や @remarks セクションも記述してはいけません。これらは継承されます。
• @override と TS のキーワードは別物です。 ソースコードでは TypeScript の override キーワードを優先し、@override 修飾子タグは .d.ts 宣言ファイルからドキュメントを生成する場合に限って使います。
• TypeDoc は利用者であり、書き手ではありません。 TSDoc コメントは、TypeDoc が API サイトを生成するために読み込む 入力 です。そのサイトの生成は別の、対象範囲外の作業です。このスキルでは、TypeDoc が後で利用するコメントのみを作成します。ドキュメントコメントの作業に TypeDoc のセットアップを持ち込まないでください。

アンチパターン

• 「TypeScript に型があるけれど、分かりやすくするために文章でも書き直そう。」 いいえ。@param userId - The user ID string は型を言い換えているだけで、何も付け加えていません。理由や使い方を記述するか、タグを省略してください。
• 「すべてのシンボルに、網羅性のためドキュメントコメントを付けよう。」 いいえ。単純なゲッター、明らかなパラメーター、自明な一行コードへの説明はノイズとなり、重要なコメントが埋もれてしまいます。
• 「生成されたクライアントのコメントも改善しよう。」 いいえ。機械生成コードは生成元が管理します。手動での変更は上書きされるため、ドキュメント作成に時間をかける場所として適切ではありません。
• 「念のため eslint-plugin-tsdoc を追加しよう。」 通常は追加しません。単一の高速なリンターを使うプロジェクトに ESLint を再び持ち込むことになります。既定では規約のみとし、2つ目のリンターを導入する判断が明示的になされた場合に限り、このプラグインを採用してください。
• 「@usage や @note タグを独自に作ろう。」 いいえ。標準外のタグはパーサーの警告を引き起こし、ツール間の相互運用性を損ないます。標準のタグセット（@remarks、@example、@see）を使ってください。

出力

正しく TSDoc に準拠したドキュメントコメントを備える TypeScript の公開インターフェイスです。必要に応じて、概要に加えて @param／@returns／@remarks／@example（および修飾子／インラインタグ）を含めます。プライベート、内部、生成された、または自明なシンボルにはドキュメントを付けず、型を言い換える文章は 一切 含めません。または、明示されたドキュメントコメントの 規約に関する決定（上記の規律に加え、規約のみとするか eslint-plugin-tsdoc で強制するかの選択）です。利用者は次のレビュアーまたは呼び出し元のワークフローです。コメントはエディターの IntelliSense にも使われ、プロジェクトで後に導入された場合は TypeDoc サイトにも反映されます。

関連項目

• references/tag-taxonomy.md — ブロック／インライン／修飾子タグの完全な一覧（一般的なタグ以外が必要な場合に読み込みます）。
• references/enforcement.md — eslint-plugin-tsdoc の設定例と2つ目のリンターを導入する際のトレードオフ、および TypeDoc／Storybook の参考情報。
• references/sources.md — 調査の出典。
• JS／TS リンター＋フォーマッターのスキル（例：Biome スキル）— ドキュメントコメントの内容を 検証しない コード品質ゲートです。このスキルは、それを補完するドキュメントコメントの規約です。
• TypeScript の型チェックのスキル — 型はそれ自体で情報を伝えるため、このスキルでは型を文章で言い換えないようにしています。

段階的な開示

• references/tag-taxonomy.md — ブロックタグ／インラインタグ／修飾タグのリファレンス。タグごとの分類と構文を記載しています。読み込むタイミング：日常的に使う範囲外のタグを記述するとき、またはタグの分類を確認するとき。
• references/enforcement.md — eslint-plugin-tsdoc の設定とトレードオフ、TypeDoc／Storybook の対象範囲外に関する案内。読み込むタイミング：強制適用ツールを選ぶとき、またはドキュメントサイトの生成について尋ねられたとき。
• references/sources.md — 出典。読み込むタイミング：情報の出所を監査するとき。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークン以下 — 毎回のターンでコンテキストに保持されます。
• 参照ファイルごと：10k トークン超で警告、25k 超でエラー。参照ファイルの合計：25k トークン超で警告、50k 超でエラー。