TypeScript ツールチェーン
適用義務
TypeScript と Python は、ライブラリと AI エージェントのエコシステムが最も充実しているため、AI 支援開発のデフォルト言語とする。
言語の優先順位:
- プロダクト開発やフルスタック開発では TypeScript をデフォルトとする。
- Python は Python ツールチェーン に示すケースに限り使う。
- Go と Rust は、性能が重要な処理やシステム領域に限って使う。導入には明確な理由とユーザーの承認が必要であり、プロジェクトの ADR に記録する。Go と Rust を参照。
フレームワークの選定については フロントエンドフレームワーク:Vite vs Next.js を参照。
バージョン方針
最新の安定版 TypeScript と Active LTS ラインの Node.js を使う。
2026-08 時点では、Active LTS ラインは Node.js 24(EOL 2028-04)である。Node.js 22 はメンテナンス期(EOL 2027-04)にあり、Node.js 26 は 2026-10 まで Current ラインである。Current ラインを対象にしてはならない。Node.js のメジャーバージョンは、新しい LTS ラインが定着してから更新する。
モデルは学習データに基づいてコードを生成する。そのため、AI 支援開発では主流で十分に検証されたバージョンのほうがエラーが起きにくい。わずかな性能向上よりも、これらのバージョンを優先する。この原則は 中核となるエンジニアリング原則 に定められている。
Node.js のバージョンはプロジェクトの mise 設定に固定し、TypeScript のバージョンは pnpm のロックファイルで固定する。いずれもグローバルにインストールされたバージョンに依存しない。
pnpm
pnpm を使う。この方針は、通常の Node.js プロジェクトと monorepo の両方に適用する。
mise.toml で pnpm のバージョンを固定する際は、最新バージョンを使い、mise(mise latest pnpm)で確認する。なお、npm 上の pnpm の latest は 11 だが、実際の最新バージョンは 12 である点に注意する。
外部ドキュメントに npm や yarn のコマンドが記載されている場合は、別のパッケージマネージャーを導入せず、pnpm 用のコマンドに読み替える。
プロジェクトのロックファイルは、pnpm と整合した状態を保たなければならない。
採用しない代替案
次のツールは使わない。
- npm
- yarn
oxlint
oxlint は TypeScript / JavaScript の標準リンターである。
フレームワーク、テンプレート、ライブラリが ESLint を推奨する場合は、次の手順で対応する。
- どの ESLint ルールやプラグインに依存しているかを特定する。
- 必要な機能が oxlint でサポートされているかを確認する。
- 可能な限り oxlint の対応する機能を使う。
- テンプレートが生成したというだけの理由で、ESLint を残してはならない。
具体的な互換性の問題がない限り、最新の安定版 oxlint を使う。
ルール設定
oxlint はデフォルトのままにせず、コードの実行環境に合わせてルールとプラグインを有効化する。テンプレートが有効にしていないという理由で、有用な推奨チェックを外したままにしないこと。
Node.js 上で動くコードでは、.oxlintrc.json で node プラグインを有効にし、旧来の CommonJS パターンを防ぐルールも含めて有効化する。一方で、プロジェクトの用途と合わない制限ルールは無効にする(たとえば、同期ファイルアクセスを意図的に使う CLI では no-sync を無効にする)。
型情報を使うリントと型チェック
プロジェクトに適している場合は、oxlint が公式にサポートする TypeScript の型情報を使ったリントと型チェックを有効にする。
最新の oxlint とともに oxlint-tsgolint をインストールし、ルートの .oxlintrc.json で options.typeAware と options.typeCheck を有効にする(typeCheck は 2026-08 時点で実験的機能)。
古いプロジェクトの設定をコピーせず最新の公式ドキュメントに従って設定し、oxlint で対応できる型情報を使うルールのために ESLint を追加しないこと。
採用しない代替案
デフォルトのリントシステムとして ESLint を使わない。
oxfmt
oxfmt は TypeScript / JavaScript プロジェクトの標準フォーマッターである。
具体的な互換性の問題がない限り、最新の安定版 oxfmt を使う。
同じソースファイルに対して、競合する複数のフォーマッターを実行しない。
採用しない代替案
Prettier を使わない。
tsconfig のベースライン
すべてのプロジェクトで、厳格な tsconfig ベースラインを起点にする。
"strict": true——厳格モードの基盤。ADR レベルの理由なく、個別の strict フラグを無効化しない。"noUncheckedIndexedAccess": true——インデックスアクセスがT | undefinedになり、未定義ケースの処理を強制する。"verbatimModuleSyntax": true——型だけのインポートにはimport typeを必須とし、誤ってランタイムのインポートが混入するのを防ぐ。"isolatedModules": true——各ファイルが独立してコンパイルできることを強制し、bundler やトランスパイラの実際の処理単位と一致させる。- ESM のみ。アプリケーションは
"module": "ESNext"と"moduleResolution": "Bundler"、Node.js 向けライブラリは"module": "NodeNext"と"moduleResolution": "NodeNext"を使う。 - アプリケーションでは tsc による出力を行わない。
"noEmit": trueを設定し、出力は bundler に任せる。
ベースラインの例:
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"verbatimModuleSyntax": true,
"isolatedModules": true,
"module": "ESNext",
"moduleResolution": "Bundler",
"target": "ES2022",
"lib": ["ES2022", "DOM"],
"noEmit": true,
},
}
言語の利用ルール
- 値の型がまだ不明な場合は
anyではなくunknownを使い、使用前に型を絞り込む。anyは本当に動的な相互運用が必要な場合に限り、理由をコメントで示す。 - 非 null アサーション演算子(
!)を使う場合は、その時点で値が null や undefined になり得ない理由をコメントで示す。 - エクスポートする関数には戻り値の型を明示する。
- 状態はブール値のグループではなく、判別可能なユニオン(discriminated union)でモデル化する。
- 設定オブジェクトは
satisfiesで検証する。定義時にエラーが表面化し、リテラル型も保持される。 - リテラルテーブルには
as constを適用し、要素型を狭く保つ。 enumの代わりにユニオン型またはconstオブジェクトを使う。- Promise を放置しない。
awaitするか、結果を意図的に破棄する場合はvoidと、その理由を示すコメントを付ける。 - 例外には
Errorのサブクラスだけを使い、文字列やプレーンオブジェクトを送出してはならない。
プロジェクト規約
- アプリケーションのソースは
src/に置き、エントリーポイントをpackage.json経由で公開する。 - ファイル名は kebab-case(
user-profile-card.tsx)、値は camelCase、型、コンポーネント、クラスは PascalCase とする。 - バレルファイル(
index.tsでディレクトリ全体を再エクスポートするファイル)は避け、定義元のモジュールから直接インポートする。バレルファイルは tree-shaking を阻害し、循環インポートを招きやすい。