neo-typescript

Neo TypeScript Expert Skill

このスキルは、厳格な型安全性、高い保守性、高度なメタプログラミングの柔軟性を備え、ESM/CJS の相互運用性に関する落とし穴などの実行時の問題を徹底的に防止するコードを AI エージェントが作成できるように支援します。

💡 注意点

• 書き込み可能な参照へのエイリアスは readonly を回避します：TypeScript では、readonly が制限するのはプロパティ自体への代入だけです。参照先のオブジェクトや配列の内部メンバーは引き続き変更できます。さらに、readonly オブジェクトを読み書き可能なエイリアスに代入できるため、コンパイラーの readonly チェックを完全に回避できます。
• 部分的な esModuleInterop 設定による致命的なクラッシュ：esModuleInterop を有効にせずに allowSyntheticDefaultImports を有効にすると、コンパイル時の型チェックは通過するものの、トランスパイル出力に __importDefault の出力ヘルパーがないため、実行時に即座にクラッシュします（TypeError: default is not a function）。
• ライブラリー作成者向けの二重 default の落とし穴：ライブラリーで export default を使用すると、Node.js の ESM 利用者はモジュールにアクセスするために .default() を呼び出さなければなりません。最善の方法は export default を完全に避け、代わりに export = または名前付きエクスポートを採用することです。

📋 静的コードと型安全性のレビュー手順

TypeScript コードの作成、変更、リファクタリング、またはレビューを依頼された場合は、次のワークフローを厳密に実行してください。

ステップ 1 — プロジェクト環境の把握（認識）

1. プロジェクトの tsconfig.json 設定を調べ、特に "strict": true、"strictNullChecks"、"strictFunctionTypes" の設定に注目します。
2. 対象となるモジュール形式と解決方式（"moduleResolution"）を特定します。

ステップ 2 — コア型の振り分け（推論）

タスクの具体的な技術領域に基づいて、スキル内の対応するリファレンスファイルを段階的に開示して読み込みます。コンテキストのトークンを節約するため、すべてのファイルを一度に読み込まないでください。

• 基礎、型の絞り込み、クラス、関数の設計 ➡️ type-system-basics.md を読み込みます
• ジェネリック制約、分散、型からの高度な型 ➡️ advanced-meta-types.md を読み込みます
• 構造的な互換性、デコレーター、ESM/CJS の相互運用性 ➡️ compatibility-and-interop.md を読み込みます

ステップ 3 — 正確なコード生成とレビュー（実行）

1. 生成または変更するコードが、読み込んだリファレンスのガイドラインに厳密に従っていることを確認します（例：オプションのコールバックパラメーターを宣言しない、型パラメーター間の相関を確立するため、ジェネリック型パラメーターを少なくとも 2 回登場させる）。
2. 高度な型を生成する場合は、evals の設定に基づいた明確な単体テストのアサーションを推奨します。

---

🛠️ 利用可能なリソース（相対パス）

• 型システムの基礎ガイド
• 高度なメタ型ガイド
• 互換性と相互運用性のガイド