core-typescript

コア TypeScript 規約 — 基本エンジニアリングスキル

フレームワークの有無を問わず、すべてのプロジェクトに適用される、言語レベルの TypeScript ルールです。react、angular、vue はこれを拡張し、architecture-and-design はこれと組み合わせて使用します。すべてのルールは、コンパイラーが strict モード（compiler-config）で動作することを前提としています。例はフレームワークを使用しない、標準的な TypeScript です。

前提となるスキル。 ありません。これは基本スキルです。

この SKILL.md は単独で利用できます。以下の ルールセット が、完全かつ適用可能なルール一覧です。各 references/<topic>.md には、そのグループの根拠と ❌ / ✅ のコード例が記載されており、references/worked-example.md にはレビュー全体の実例があります。実行環境で可能な場合は、より詳しく確認するためにこれらを開いてください。

---

このスキルの使い方

タスクに合ったモードを選び、手順に沿って進めてください。

モード	手順
生成 — 新しい TypeScript を記述する	1. strict が有効であることを前提とします（compiler-config）。 2. ルールセットを適用しながらコードを記述します。 3. エクスポートするすべての関数の戻り値の型を注釈します（functions）。 4. ルールセットをチェックリストとして実行します。提出前に各不適合を修正します。
レビュー — 差分を確認する	1. 差分に対してルールセットを実行します。 2. 不適合ごとに、以下の出力形式で指摘を 1 件記述します。 3. 指摘は must-fix を先に、その後に consider の順で並べます。 4. 不適合がなければ、その旨を 1 行で伝えます。指摘をでっち上げないでください。
設定 — tsconfig.json と ESLint を設定または監査する	1. assets/tsconfig.base.json と assets/eslint.config.js を起点にします。 2. compiler-config のすべてのフラグと lint のすべてのルールを有効にします。 3. まだ有効にできないフラグには、その理由を記した // TODO を追加します。 4. エラーを解消するためにフラグを緩和したり、ルールを無効にしたりしないでください。コードを修正します。

出力形式

指摘は 1 行に 1 件記述します。

<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>.

• <severity> は、ルール違反またはビルドの失敗につながる場合は must-fix、安全ではあるものの、ルール上は別の形式が推奨される場合は consider です。
• <topic> はルールセットのトピックスラッグです（unsafe-types、narrowing、async など）。

すべてのモードに適用されるルール

• ルールを適用する際は、ルールセットのトピック名を明記します。
• 正確さを保てる最も単純な型を優先します。広すぎる型はバグを見えにくくし、凝りすぎた型は次に読む人の負担になります。
• 説明コメントが必要な型は要注意です。名前を付けるか、より単純にしてください。

---

ルールセット

compiler-config → references/compiler-config.md

• strict に加えて、noUncheckedIndexedAccess、exactOptionalPropertyTypes、noImplicitOverride、noFallthroughCasesInSwitch、noImplicitReturns、 noUnusedLocals、noUnusedParameters、verbatimModuleSyntax、erasableSyntaxOnly を有効にします。
• エラーを解消するためにフラグを緩和してはいけません。代わりにコードを修正します。

unsafe-types → references/unsafe-types.md

• any を使用しません。不明な入力には unknown を指定し、型を絞り込みます。as any と as unknown as T も使用しません。
• 型を強制するために as を使用せず、値が直前の行で存在すると証明されている場合を除き、! も使用しません。それぞれの使用箇所には、安全性を証明するガードまたはコメントが必要です。
• 型として Function、Object、{} を使用しません（プリミティブ以外には object を使用できます）。
• @ts-ignore は使用せず、コメントを添えて @ts-expect-error を使用します。

inference → references/inference.md

• コンパイラーがすでに正確に推論している内容を繰り返す型注釈は使用しません（エクスポートされた API 境界は例外です。functions を参照してください）。
• satisfies を使って、リテラルの型を広げずに形状との適合性を検証します。

data-modeling → references/data-modeling.md

• 文字列の集合は、文字列リテラルのユニオン型か、凍結された as const オブジェクトで表します。TypeScript の enum や const enum は使用しません。
• 変更されないデータには readonly を指定します（リストには readonly T[] を使用します）。
• 相互排他的な状態は、共通の判別フィールドを持つ判別可能なユニオン型で表します。設計の根拠については、architecture-and-design の patterns を参照してください。
• ドメイン ID には専用のブランド型を用意し、境界で許可されたキャストを 1 回だけ使って生成します。設計の根拠については、architecture-and-design の type-safety を参照してください。

narrowing → references/narrowing.md

• unknown とユニオン型は、キャストではなく型ガード（v is T）またはアサーション関数（asserts v is T）で絞り込みます。
• ユニオン型に対するすべての switch は、最後に assertNever のデフォルトケースを置きます。

generics → references/generics.md

• 型パラメーターを追加するのは、2つの型が連動するとき（入力と戻り値の型）のみです。1回しか使わない型パラメーターは使用しません。
• 型パラメーターには extends で制約を設けます。一般的な型パラメーターにはデフォルト値を設定し、呼び出し側がリテラルを渡す場合は const 型パラメーターを使います。

utility-types → references/utility-types.md

• 関連する型は、手作業でコピーせず、Pick / Omit / Partial / Required / Record / ReturnType / Parameters / Awaited / NonNullable / keyof / typeof / インデックスアクセス型 / テンプレートリテラル型で導出します。

nullability → references/nullability.md

• 空の値には undefined を使います。null は、それを送信する外部コントラクトがある場合に限り使用します。
• array[i] と record[key] は undefined の可能性があるものとして読み取ります（noUncheckedIndexedAccess が必要です）。
• デフォルト値には ?. と ?? を使います。0、''、false が有効な値でない場合に限り || を使います。

functions → references/functions.md

• エクスポートする関数にはすべて戻り値の型を注釈します。エクスポートしないローカル関数では型を推論させます。
• 引数が3つを超える場合は、1つのオプションオブジェクトを使います。順序に依存する長い引数リスト、特に真偽値の引数を並べる方法は使いません。
• 本体が同じ場合は、オーバーロードの集合ではなくユニオン型の引数を使います。

async → references/async.md

• Promise を放置しません。すべての Promise を await するか、明示的に void を付けます。
• 独立した非同期処理は Promise.all で実行します。前の結果が必要なステップに限り、直列に await します。
• タイマー、サブスクリプション、ロック、ハンドルなどの破棄可能なリソースは、対象環境が明示的なリソース管理に対応している場合、using / await using で解放します。

errors → references/errors.md

• catch バインディングは unknown（useUnknownInCatchVariables による）とし、フィールドを読み取る前に絞り込みます。
• スローする値には必ず Error を使います。カスタム型は Error を継承して name を設定し、文字列やプレーンオブジェクトは使いません。

modules → references/modules.md

• 型参照には import type / export type、または名前にインラインの type を使います。
• デフォルトエクスポートではなく名前付きエクスポートを使います。2つのモジュール間で循環インポートを作らず、プロジェクト全体のバレルファイルは作りません（機能ごとの index.ts は問題ありません）。

language-hygiene → references/language-hygiene.md

• === / !== のみを使います。例外は、null と undefined をまとめて判定する x == null です。
• 型変換を行うグローバル関数ではなく、Number.isNaN / Number.isFinite を使います。
• 原則として const を使い、再代入する場合に限り let を使います。var は使いません。関数の引数には再代入しません。
• 実際のビットフラグには、2の累乗を値とする const オブジェクトと、そこから導出した型を使います。文字列リテラルのユニオン型は使いません。

lint → references/lint.md

• typescript-eslint は strict-type-checked（または少なくとも recommended-type-checked）で実行し、no-floating-promises、no-explicit-any、 consistent-type-imports、switch-exhaustiveness-check を有効にします。
• Prettier でフォーマットするため、スタイルはレビューの対象になりません。

---

制限事項

このスキルの対象は、言語レベルの TypeScript です。以下は対象外です。

• アーキテクチャ、レイヤリング、状態管理、コンポーネント設計については、architecture-and-design を参照してください。
• フレームワークの API とパターンについては、react、angular、vue を参照してください。
• compiler-config の tsconfig の基本設定を超えるビルドツール、バンドラー、モノレポの設定については扱いません。
• 実行時スキーマライブラリ（Zod、Valibot）については、関連する箇所で名前を挙げるだけで、解説しません。

このスキルで決めるのは構文です。コードを読んでドメインを理解することの代わりにはなりません。

---

参考資料

このスキルは、以下と組み合わせて使用します。

• architecture-and-design — 設計レイヤーです。共通のトピック（判別可能なユニオン、ブランド化された ID）については、このスキルが構文を決め、こちらが設計を決めます。
• react / angular / vue — それぞれのフレームワーク固有の仕様をこのスキルに追加します。言語に関する見解が衝突する場合は、このスキルを優先します。