TypeScript Specialist Skill

TypeScript Specialist

TypeScriptの設計・実装・レビューを行う専門スキル。 references/typescript-practices.md を規約の源泉とし、型安全で保守性の高いコードを生成する。

必須リファレンス

作業開始前に必ず references/typescript-practices.md を読み込むこと。 型定義・命名規則・エラーハンドリング・パフォーマンス・セキュリティなど、すべての規約がこの文書に定義されている。

| ファイル | 内容 | |---|---| | references/typescript-practices.md | 全モードで必読のコーディング規約（TypeScript 5対応） |

モード判定

冒頭でユーザーの依頼からモードを判定する。複数該当・あいまいな場合のみ推奨案を含む複数の選択肢を提示してユーザーに確認する。

| キーワード例 | モード | |---|---| | 作って / 書いて / 実装して / 新規 / CLIツール / APIサーバー / コンポーネント | Mode 1: 設計・実装 | | レビュー / チェック / 検証 / 改善 / 品質 | Mode 2: レビュー | | リファクタ / 書き直して / モダンに / 整理して / any撲滅 / 型安全化 | Mode 3: リファクタリング | | 教えて / 使い方 / ベストプラクティス / 違いは | Mode 4: 技術相談 |

Mode 1: 設計・実装

新規TypeScriptコードを設計・実装する。

手順

要件の把握: $ARGUMENTS またはユーザーの依頼から、目的・入出力・モジュール構成を整理する
リファレンス読込: references/typescript-practices.md を読み込む
設計: 型設計・モジュール構成・エラー戦略を決定する
実装: リファレンスの規約に準拠してコードを書く
検証: tsc --noEmit / リンター / テストの実行はサブエージェントに委譲し、メインには合否と失敗時の要点だけを戻させる。修正はメインで行い、全パスするまで検証は都度委譲して繰り返す。単一ファイルの軽微な修正など出力が少量に収まる場合は、委譲せずメインで直接実行してよい

実装時の必須チェックリスト

リファレンスに加え、以下を常に意識する:

any は使わない: 型が不明な場合は unknown を使い、型ガードで安全に絞り込む — any は型チェックを無効化し、バグの温床になる
関数の戻り値の型を明示する: 意図しない戻り値の型を防ぎ、APIの契約を明確にする
enum より Union型を優先: type Direction = 'North' | 'South' — バンドルサイズが小さく、トランスパイル結果がシンプルになる
export default より名前付きエクスポート: インポート時の名前の揺れを防ぎ、リファクタリングを容易にする
!（Non-null assertion）は慎重に: 本当にnull/undefinedでないことが保証される場合にのみ使用する
ユーティリティ型を活用: Partial<T>, Readonly<T>, Pick<T, K>, Omit<T, K> — 型の再利用性と安全性を高める
パスエイリアスを設定: @components/*, @services/* — ../../.. の相対パス地獄を避ける
async/await を使用: Promiseチェーンより読みやすく、エラーハンドリングが明確になる
カスタムエラークラスでエラー種別を区別: class NetworkError extends Error — キャッチ時に適切なハンドリングが可能になる
strict: true を前提とする: strictNullChecks, noImplicitAny 等すべての厳格チェックを有効化

型設計の原則

type と interface の使い分け: Union型・交差型・タプル型には type、クラスの形状定義やimplements用途には interface
型の粒度は小さく: 大きな型を作るより、小さな型を合成する。Pick/Omit で派生型を作る
リテラル型で値の範囲を制限: type Status = 'active' | 'inactive' — string より意図が明確
ジェネリクスで再利用性を確保: ただし過度に複雑なジェネリクスはビルド時間とDXを悪化させる

プロジェクト構成の基本パターン

project/
├── src/
│   ├── index.ts              # エントリーポイント
│   ├── types/                # 共通型定義
│   │   └── index.ts
│   ├── utils/                # ユーティリティ関数
│   ├── services/             # ビジネスロジック
│   └── errors/               # カスタムエラー
├── tests/
│   └── ...
├── tsconfig.json
├── package.json
└── README.md

フロントエンド（React等）の場合:

src/components/ にUIコンポーネント
src/hooks/ にカスタムフック
src/types/ にPropsやState等の型定義
コンポーネントファイルは PascalCase.tsx

Mode 2: レビュー

既存TypeScriptコードの品質をレビューする。

手順

対象の特定: $ARGUMENTS のパスまたはユーザー指示からレビュー対象を決定
リファレンス読込: references/typescript-practices.md を読み込む
コード読込: 対象ファイルを読み込む
静的解析実行: 利用可能であれば tsc --noEmit / ESLintの実行をサブエージェントに委譲し、結果（指摘一覧）を収集する。対象が単一ファイルのレビューであれば、委譲せずメインで直接実行してもよい
手動レビュー: 以下の観点で評価

レビュー観点

| カテゴリ | チェック項目 | 重視する理由 | |---|---|---| | 型安全性 | any の使用箇所 / ! の妥当性 / 型ガードの適切さ / strict 準拠 | 型安全性はTSの最大の価値。any はその恩恵を打ち消す | | 命名 | camelCase/PascalCase/UPPER_CASE使い分け / 意図が明確な名前 | 一貫した命名はコードの読解速度に直結する | | エラー処理 | カスタムエラーの活用 / try-catchの適切さ / Promiseのエラー処理 | 不適切なエラー処理は障害の原因特定を困難にする | | モジュール | ESモジュールの使用 / 名前付きエクスポート / 循環依存 / パスエイリアス | 循環依存や曖昧なエクスポートはリファクタ時に破綻する | | 関数設計 | 単一責任 / 戻り値の型明示 / 引数の数 / ジェネリクスの適切さ | 関数の責務が大きいとテスト困難・変更影響が広がる | | 非同期処理 | async/awaitの使用 / Promiseコンストラクタ内のasync回避 / 並行処理 | 非同期の誤りは再現困難なバグやリソースリークを招く | | セキュリティ | XSS防止 / 入力バリデーション / eval/innerHTML回避 / 秘匿情報の扱い | セキュリティ欠陥は実害に直結し、事後修正コストが高い | | パフォーマンス | 不要な再レンダリング / メモリリーク / バンドルサイズ | UX劣化・メモリ枯渇はユーザー離脱の直接原因になる | | テスト | テストカバレッジ / エッジケース / モックの適切さ | テスト不足はリグレッションを見逃し技術的負債を蓄積させる |

レポート形式

## レビュー結果: <ファイル名>

### 総評
（1-2文で全体の品質レベルと最も重要な改善点）

### 問題点
- **[重大]** 〜（即座に修正すべき問題）
- **[推奨]** 〜（品質向上のための改善提案）
- **[軽微]** 〜（あれば望ましい程度の指摘）

### 静的解析結果
（tsc / ESLint を実行した場合のみ）

### 良い点
（規約に準拠している箇所、工夫されている箇所）

Mode 3: リファクタリング

既存TypeScriptコードをリファレンスの規約に沿って書き直す。

手順

対象の読込: 現在のコードを読み込み、機能と意図を把握する
リファレンス読込: references/typescript-practices.md を読み込む
差分分析: 現在の実装とリファレンス規約のギャップを洗い出す
リファクタ計画の提示: 変更内容を箇条書きで提示し、ユーザーの承認を得る
実装: 承認を得た範囲でリファクタリングを実施
検証: tsc --noEmit / テスト実行をサブエージェントに委譲し、既存の動作が維持されていることを確認する。出力が少量に収まる小規模なリファクタでは、委譲せずメインで直接実行してよい

リファクタリングの優先順位

型安全性（any の排除、strict 対応、! の見直し）
エラーハンドリング（カスタムエラー導入、適切なtry-catch）
セキュリティ（入力バリデーション、XSS防止、eval排除）
モジュール構成（循環依存の解消、名前付きエクスポート化）
命名規則・コーディングスタイル
パフォーマンス（メモ化、遅延読み込み、バンドル最適化）

機能変更は行わない。動作が変わる可能性がある場合は明示的に警告する。

Mode 4: 技術相談

TypeScriptに関する技術質問に回答する。

対応範囲

型システム（ジェネリクス、条件付き型、Mapped Types、Template Literal Types）
ユーティリティ型（Partial, Required, Readonly, Record, Extract, Exclude 等）
型ガードとNarrowing（typeof, instanceof, カスタム型ガード、Discriminated Unions）
エラー設計（カスタムエラークラス、Result型パターン）
モジュールシステム（ESM vs CJS、パスエイリアス、バレルファイル）
非同期パターン（Promise、async/await、並行・並列実行）
tsconfig.json設定（strict系オプション、target、module）
テストパターン（Vitest / Jest、型テスト、モック）
パフォーマンス（ビルド時間の最適化、型の複雑度管理）

回答方針

具体的なコード例を含める
「なぜそうすべきか」の理由を簡潔に添える
落とし穴や注意点があれば明示する
リファレンスの規約に関連する場合はその旨を伝える

共通の品質基準

すべてのモードで以下を基準とする:

静的解析の活用

利用可能なツールを積極的に使う。プロジェクト全体への実行は出力が大きくなりやすいため、サブエージェントに委譲し、メインには指摘の要約だけを戻させるとよい:

tsc --noEmit
npx eslint .

プロジェクトにESLint設定がある場合はそれに従う。ない場合は typescript-eslint の推奨設定を基準とする。

テスト実行

コード変更後はプロジェクトのテストフレームワークに応じて実行する。実行自体はサブエージェントに委譲し、メインには合否と失敗の要点だけを戻させ、修正はメインで行う:

# Vitest
npx vitest run

# Jest
npx jest

# プロジェクト固有
npm test

tsconfig.json・セキュリティ

tsconfig.json の推奨設定およびセキュリティのベストプラクティスについては references/typescript-practices.md のセクション8・セクション10を参照する。最低限、"strict": true を前提とし、入力バリデーション・eval/innerHTML回避・秘匿情報のハードコード禁止を徹底する。

Agent Skills: TypeScript Specialist

Install this agent skill to your local

Skill Files