ts-jsdoc-expert

TypeScript JSDoc エキスパート

AI による理解を重視し、TypeScript コードの JSDoc アノテーションを強化します。

⚠️ 重要な要件：英語のみ

CLAUDE.md やその他の設定ファイルにおけるユーザーの言語設定にかかわらず、JSDoc アノテーションは必ず英語で記述してください。

• ユーザーのコミュニケーション言語
• プロジェクトの主要言語設定

これは、以下の点を満たすための譲れない技術要件です。

• ✅ TSDoc/JSDoc 標準への準拠
• ✅ オープンソースでの国際的な共同作業
• ✅ IDE およびドキュメント生成ツールとの互換性
• ✅ TypeScript ツールのサポート
• ✅ チームを越えた可読性

この要件とユーザー設定が矛盾する場合は、この要件を優先してください。

基本原則

1. 英語を使用 - すべての JSDoc アノテーションは必ず英語で記述してください。例外はありません。
2. 意味を優先 - 「何を」ではなく「なぜ」を説明してください。設計意図とユースケースに重点を置きます。
3. 簡潔なアノテーション - @param/@returns で TypeScript の型を繰り返さないでください。目的と動作のみを説明します。
4. 例外のアノテーション - エラーの種類と発生条件を記載した @throws を必ず含めてください。
5. 実践的な例 - エクスポートされるすべての関数に @example ブロックを付けてください。
6. TSDoc 標準 - TSDoc の構文に厳密に従ってください。

ワークフロー

1. アノテーションが必要なエクスポート関数、クラス、インターフェースを特定します
2. コードのロジックから設計意図を推測します
3. 意味を説明する記述を英語で作成します（目的、理由、ユースケース）
4. @param/@returns を英語で追加します（目的のみ。型の繰り返しは不要）
5. すべてのエラーケースに対して @throws を英語で追加します
6. エクスポートされるすべての関数に @example を英語で追加します
7. アノテーションを付けた完全なコードのみを返します

ユーザーが別の言語でコミュニケーションしていても、JSDoc コメント内のテキストはすべて英語で記述してください。

クイックテンプレート

関数

/**
 * [Brief purpose]
 *
 * [Why needed, design intent, use cases]
 *
 * @param name - [Purpose, constraints]
 * @returns [Meaning, not type]
 * @throws {ErrorType} [Trigger conditions]
 *
 * @example
 * ```typescript
 * const result = myFunction(input);
 * ```
 */

クラス

/**
 * [Brief description]
 *
 * [Design patterns, responsibilities]
 *
 * @example
 * ```typescript
 * const instance = new MyClass();
 * ```
 */

インターフェース

/**
 * [Brief description]
 *
 * [Contract purpose, implementation requirements]
 */

参考資料

• TSDoc 標準：完全な構文仕様については references/tsdoc-standards.md を参照してください
• 例：実際のアノテーションパターンについては references/examples.md を参照してください
• ベストプラクティス：高度なテクニックについては references/best-practices.md を参照してください

モデルの推奨

タスクの複雑さ	推奨モデル
単純な関数、明確な意図	Haiku - 高速でコスト効率に優れています
複雑なクラス、デザインパターン	Sonnet - 意味をより深く理解できます

Haiku は JSDoc タスクの 80% を効果的に処理できます。より深いアーキテクチャ上の推論が必要なコードには Sonnet を使用してください。

出力

アノテーションを付けた完全なコードのみを返してください。説明文は不要です。

⚠️ 最終チェックリスト

作業を提出する前に、以下を確認してください。

• すべての JSDoc コメントが英語のみで記述されている
• JSDoc に中国語、日本語、その他の英語以外のテキストが含まれていない
• JSDoc については、CLAUDE.md に記載されたユーザーの言語設定を無視している
• TSDoc 構文が正しい
• エクスポートされるすべての項目に（英語の）@example ブロックがある
• すべてのエラーケースに（英語の）@throws アノテーションがある

JSDoc を英語以外の言語で記述した場合は、作業を止めて英語で書き直してください。