typescript

JavaScript & TypeScript

主な参考資料：TypeScript ドキュメント。以下のルールファイルから、それぞれが反映しているドキュメントの該当セクションにリンクしています。ルールと公式ドキュメントの内容が異なる場合は、ドキュメントを優先し、ルールを更新してください。

プロジェクトの方針に従う

リポジトリで設定されているランタイム、インポート、テストランナー、検証コマンドを使用してください。 ツールを変更したりワークフローを導入したりする前に、エージェント向けの指示と設定を確認してください。

サブスキルの参照先

type-system/ と zod/ は、このルーターから必要に応じて参照するリファレンス集です。独立して検出されるスキルではないため、それぞれのフロントマターは意図的に最小限にしてあります（トリガーリストの重複は不要です）。

→ 型システム（unknown/any、型の絞り込み、判別可能なユニオン、マップ型など）→ type-system/SKILL.md → Total TypeScript / Matt Pocock（型の導出、satisfies、ジェネリックの推論、NoInfer、分配、型テスト）→ references/total-typescript.md → Zod（スキーマ検証、変換、型強制、ブランド型など）→ zod/SKILL.md → 関数型合成（pipe/compose、カリー化、純粋関数、ファクトリー、関数型ミックスイン、モノイドなど）→ composition/SKILL.md → Node.js の設計パターン（非同期制御フロー、ストリーム、EventEmitter、DI、バッチ処理、ワーカー、スケーリング）→ references/node-patterns.md → JS ランタイムの仕組み（this、クロージャー、プロトタイプ、ジェネレーター、イベントループの順序、プロミス）→ references/js-runtime-mechanics.md → JS の落とし穴とイディオム（型強制、辞書、配列／反復処理、API 設計、非同期処理の規律、定着したパターン）→ references/js-pitfalls-and-idioms.md → エディション別 ES 機能（ES2015～ES2025 の追加機能、最新の代替手段、target/lib の指針）→ references/es-features-by-edition.md → ドメインモデリング（パイプラインとしてのワークフロー、型による状態機械、Result エラー、DTO の境界、端点での永続化）→ references/domain-modeling-functional.md → TS 言語のギャップ（分散性、オーバーロード、アサーション関数、モジュール解決、型駆動設計）→ references/ts-language-gaps.md → Deno ランタイム（ランタイムのサポート終了に関する告知。既存プロジェクトの保守のみを対象：設定、権限、依存関係、HTTP、テスト、Node 互換性）→ references/deno.md → デザインパターン（Strategy、Factory、Builder、Decorator、Mixin など）→ object-oriented-programming スキル → SOLID 原則（SRP、OCP、LSP、ISP、DIP）→ object-oriented-programming スキル → テスト（ユニットテスト、モックとスタブの違い、壊れやすいテスト、テストピラミッド）→ testing スキル

---

エラー処理

戦略	呼び出し元に処理が強制されるか	合成可能性
T | null を返す	はい（null チェック）	低
例外をスローする	いいえ — 見落としやすい	高
例外を返す T | ErrorA | ErrorB	はい — ユニオンの網羅性	中
Option/Either 型	.flatMap チェーン経由	高（ライブラリが必要）

例外を返す（想定される失敗に推奨）：

class BadRequestError extends Error {
  readonly status = 400 as const;
}
class UnauthorizedError extends Error {
  readonly status = 401 as const;
}
class NotFoundError extends Error {
  readonly status = 404 as const;
}

function resolveUser(
  token: string,
  id: string,
): User | BadRequestError | UnauthorizedError | NotFoundError {
  if (!id.trim()) return new BadRequestError("Missing user ID");
  if (!isValidJwt(token)) return new UnauthorizedError("Invalid token");
  const user = userStore.get(id);
  if (!user) return new NotFoundError(`User ${id} not found`);
  return user;
}

const result = resolveUser(authHeader, userId);
if (result instanceof BadRequestError) res.status(400).send(result.message);
else if (result instanceof UnauthorizedError)
  res.status(401).send(result.message);
else if (result instanceof NotFoundError) res.status(404).send(result.message);
else res.status(200).json(result);

---

大規模な TypeScript

1. "strict": true を全体で有効にし、CI で適用します（コンパイラーオプション）。strict に含まれない次のフラグも追加します：noUncheckedIndexedAccess、noImplicitReturns、noFallthroughCasesInSwitch、noUnusedLocals、noUnusedParameters
2. @ts-ignore よりも @ts-expect-error を使用します
3. @typescript-eslint/no-explicit-any を使って any の使用状況を追跡します
4. API／DTO 型とドメイン型を分け、境界でマッピングします（以下の例を参照）
5. 外部入力（API 本文、環境変数、キュー）は境界で Zod を使って検証します（例：zod/SKILL.md）
6. ドメインコントラクトを @org/contracts として公開し、境界にはプロジェクト参照を使用します（プロジェクト参照）

必要に応じて参照

• Effect TS — 型付きエラー、並行処理、リソース管理、依存関係の要件については公式ドキュメントを参照してください。API の例を使用する前に、ドキュメントのバージョンがプロジェクトにインストールされている effect のバージョンと一致していることを確認してください。
• ドメインと DTO のマッピング例 — DTO の形状をドメインに持ち込まないでください：

export type UserDTO = {
  user_id: string;
  display_name: string;
  created_at: string;
};

export type User = { id: string; name: string; createdAt: Date };

export function toDomain(dto: UserDTO): User {
  return {
    id: dto.user_id,
    name: dto.display_name,
    createdAt: new Date(dto.created_at),
  };
}

• Zod による境界検証の例：zod/SKILL.md。
• Node.js ランタイムのトピック（イベントループ／libuv、コアモジュール、CJS／ESM、デバッグとプロファイリング、HTTP エコシステム、npm／パッケージング、セキュリティ）：無料の電子書籍「Become a Node.js developer」（オンライン版）を参照してください。注：フランス語版は完成していますが、英語版は一部のみです。
• ECMAScript のエディションの歴史（ES1 1997 → ES2025）：MDN の JavaScript エディション年表を参照してください。機能がどのエディションで初めて導入されたか、古いランタイムでどの機能にポリフィルが必要か、対象環境でどの構文が安全か、または tsconfig の target／lib を選ぶ際に利用してください。

ルール（JavaScript と TypeScript、常に適用）

JavaScript の基礎

ルール	ファイル
JavaScript の一般的な規約（命名、const／let、分割代入、テンプレートリテラル）を使用します	rules/js-general-conventions.md
暗黙的な this より、明示的なコンテキスト（パラメーター）を優先します	rules/prefer-explicit-context-over-this.md
バレルファイル（index.js／index.ts からの再エクスポート）は使用しません	rules/no-barrel-files.md
ホットパスで中間配列を作成しないでください（filter().map() の連鎖）	rules/avoid-intermediate-arrays.md
値が存在しない場合は undefined、API／外部コントラクトでは null を使用します	rules/null-undefined.md

TypeScript 固有

ルール	ファイル
型アサーション（as T、!、as unknown as T）を避ける	rules/avoid-type-assertions.md
as const より既存の型を優先する	rules/favor-existing-types-over-as-const.md
インターフェース名に I を付けない	rules/no-interface-prefix.md
不変であることを示すため、プロパティと配列に readonly を付ける	rules/readonly.md
明らかなローカル関数の戻り値は型推論に任せ、公開 API と推論にリスクのある箇所には型注釈を付け、noImplicitAny を有効にする	rules/explicit-return-types.md
名前空間ではなくモジュールを使い、名前付きエクスポートを優先する	rules/module-organization.md
提供されている型または @types/* を優先し、それ以外の場合は最小限の .d.ts を追加する	rules/js-interop-declarations.md

---

ベンチマーク

このルーターには固有のシナリオがありません。ゲートのデータは各リーフのフッターにあります。

• type-system/SKILL.md → ## Benchmark（シナリオ typescript-001 は PASS、typescript-002 は SOFT PASS、実行日 2026-08-31）。
• composition/SKILL.md → ## Benchmark（シナリオ composing-software-001、実行日 2026-08-31、PASS）。
• 過去のオプティマイザー実行：run-history.md（スキルごとのゲート目標を含みます）。

ゲートは .agents/skills/skill-optimizer/rules/release-gates.md に従います。