Typescript Rules Agent Skill

TypeScript 開発ルール

前提条件の検出

プロジェクト規約を適用する前に、tsconfig、ランタイム・フレームワーク設定、lint・format設定、パスエイリアス、package scripts、代表的なモジュールを確認する。設定または確立済みのパターンに裏付けられたルールだけをプロジェクト固有として扱う。限られたパターンから導いた結論には推測であることを明記する。競合する規約によって公開契約、ランタイムの振る舞い、エラー境界が変わる場合は作業を止め、必要な情報源またはユーザー判断を具体的に示す。

Backend実装における型安全性

データフローでの型安全性

入力層（unknown） → 型ガード → ビジネス層（型保証） → 出力層（シリアライズ）

Backend固有の型シナリオ:

• API通信: レスポンスはunknownで受け、型ガードで検証
• フォーム入力: 外部入力はunknown、バリデーション後に型確定
• レガシー統合: レガシーとの境界ではunknownとして受け取り、根拠のある型アサーションが必要な場合は、その境界を所有するアダプター内に限定する
• テストコード: 設定済みのテストハーネスでモックの入出力型を定義する。意図的に一部だけを持つfixtureにはPartial<T>を使用し、Vitestが設定されている場合にのみ型付きのvi.fn<[Args], Return>()を使用する

コーディング規約

クラス使用の判断基準

• 推奨：関数とinterfaceでの実装
• 背景: テスタビリティと関数合成の柔軟性が向上
• クラス使用を許可:
• フレームワーク要求時（NestJSのController/Service、TypeORMのEntity等）
• カスタムエラークラス定義時
• 状態とビジネスロジックが密結合している場合（例: ShoppingCart、Session、StateMachine）
• 判断基準: 「このデータは振る舞いを持つか？」がYesならクラス検討

  // 関数とinterface
  interface UserService { create(data: UserData): User }
  const userService: UserService = { create: (data) => {...} }

関数設計

• 引数は0-2個まで: 3個以上はオブジェクト化

  // オブジェクト引数
  function createUser({ name, email, role }: CreateUserParams) {}

依存性注入

• 外部依存は引数で注入: テスト可能性とモジュール性確保

  // 依存性を引数で受け取る
  function createService(repository: Repository) { return {...} }

非同期処理

• Promise処理: リポジトリで確立済みのスタイルに従う。処理順序とエラー伝播を明確にできる場合はasync/awaitを使用する
• エラーハンドリング: 現在の層で失敗の変換、情報付加、復旧、記録ができる場合にtry-catchを追加する。それ以外は、所有する境界までPromiseのrejectionを伝播させる
• 型定義: 戻り値の型は明示的に定義（例: Promise<Result>）

フォーマット規則

• セミコロンの扱いを含め、リポジトリで設定されたformatterに従う
• 型はPascalCase、変数・関数はcamelCase
• 絶対importはtsconfigまたは設定済みのビルドツールで宣言されたaliasを通じて使用する。それ以外は相対importを使用する

クリーンコード原則

• 今回の変更範囲にある未使用コードを削除する
• デバッグ用console.log()は削除
• 実行可能なソースにはコメントアウトしたコードを残さない。削除した実装の履歴はバージョン管理で保持する
• コメントは「なぜ」を説明（「何」ではなく）

エラーハンドリング

エラー結果のルール: すべての失敗に対して、型付きの想定内エラーを返す、明記された要件に従って復旧する、診断情報を付加して伝播する、のいずれか1つを所有する結果として定める。同じ失敗を重複して記録しないよう、可観測性を所有する境界でログを出力する。

Fail-Fast原則: エラー時は速やかに失敗させ、不正な状態での処理継続を防ぐ

// 無効: 呼び出し元が必要とする失敗をフォールバックで隠している
catch (error) {
  return defaultValue // エラーを隠蔽
}

// 情報を付加して明示的に伝播する
catch (error) {
  throw new Error('処理失敗', { cause: error })
}

Result型パターン: エラーを型で表現し、明示的に処理

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }

// 使用例：エラーの可能性を型で表現
function parseUser(data: unknown): Result<User, ValidationError> {
  if (!isValid(data)) return { ok: false, error: new ValidationError() }
  return { ok: true, value: data as User }
}

カスタムエラークラス

export class AppError extends Error {
  constructor(message: string, public readonly code: string, public readonly statusCode = 500) {
    super(message)
    this.name = this.constructor.name
  }
}
// 用途別: ValidationError(400), BusinessRuleError(400), DatabaseError(500), ExternalServiceError(502)

層別エラー処理

• API層: HTTPレスポンスに変換、機密情報を除外してログ出力
• サービス層: ビジネスルール違反を検出、AppErrorはそのまま伝播
• リポジトリ層: 技術的エラーをドメインエラーに変換

構造化ログと機密情報保護

現在の信頼境界で許可されたフィールドだけをログに含める。認証情報、トークン、シークレット、決済情報、個人データはログ出力前に除去する。

非同期エラーハンドリング

• ランタイムがunhandledRejectionやuncaughtExceptionを公開する場合は、アプリケーションのentry pointでランタイムレベルのhandlerを設定する。ライブラリではプロセスレベルの方針をhostに委ねる
• 非同期の失敗は、型付きの結果、復旧、診断情報のいずれかを付加できる層でcatchする
• その層での復旧を要件が明記している場合を除き、情報を付加した失敗は伝播させる

パフォーマンス最適化

• ストリーミング処理: 計測した入力サイズが利用可能なメモリ予算を超える場合、または要件で逐次出力が必要な場合は、ストリーミングまたは上限付きbatchを使用し、判断の根拠となった計測値または制約を記録する
• リソースのライフタイム: timer、subscription、handle、保持している参照は、そのライフサイクルを所有する境界で解放する