javascript-conventions

JavaScript/TypeScript の規約

JavaScript、TypeScript、Node.js ツール、または package.json が主な作業対象の場合は、これらの規約を適用してください。

振り分け

$ARGUMENTS	アクション
Active（JS/TS が主な作業対象の場合に自動で呼び出されます）	以下のオペレーター契約を適用します
Empty	規約の概要と振り分けの指針を表示します
check	ツールの準拠状況のみを確認します

参照ファイル一覧

ファイル	目的	読み込むタイミング
references/tooling-contract.md	必須となるパッケージマネージャー、コマンド、CI、ワークスペース、パッケージルートの規則	パッケージコマンド、スクリプト、依存関係、ロックファイル、CI
references/redirection-boundaries.md	JS/TS の規約を Python、シェル、CI、フレームワーク固有のスキルに委ねるべき場合	複数言語が関わる作業、または判断が難しい作業
references/edge-cases.md	npm/yarn、Corepack、生成されたアプリ、移行に関する例外条件	pnpm の既定から逸脱する場合
references/typescript-patterns.md	TypeScript の設定、絞り込み、型ガード、ユニオン、型テストのパターン	TypeScript コード、または tsconfig.json
references/eslint-prettier.md	ESLint のフラット設定、型付きリント、Prettier の分離	リントやフォーマットの変更

オペレーター契約

Active

1. JS/TS ファイル、Node ツール、または package.json がタスクの主な対象である場合に限り、このスキルを適用します。
2. JS/TS と Python、シェル、CI、またはフレームワーク固有の作業が並行する場合は、references/redirection-boundaries.md を読み込みます。
3. パッケージ管理、パッケージルートの選択、コマンドの実行、ロックファイル、ワークスペース、CI でのインストールについて、references/tooling-contract.md の必須要件を適用します。
4. npm、yarn、グローバルパッケージマネージャー、Corepack の前提、またはロックファイルの移行を推奨する前に、references/edge-cases.md を確認します。
5. TypeScript の設定や型安全性に関する変更では、references/typescript-patterns.md を読み込みます。
6. リント、型付きリント、またはフォーマットの変更では、references/eslint-prettier.md を読み込みます。
7. 新しい作業を始める場合、またはリポジトリにより強いローカル規約がない場合に限り、推奨事項を参考にします。

Empty / Help

1. 必須要件をまとめます：pnpm、packageManager、pnpm-lock.yaml、pnpm install --frozen-lockfile、pnpm exec、pnpm dlx、tsc --noEmit、eslint、prettier。
2. 必須要件と推奨事項の違いを示します。
3. ツール、例外、TypeScript、リント／フォーマット、複数言語の振り分けについて、該当する参照ファイルを示します。

check

1. JS/TS ツールの準拠状況のみを確認します。ユーザーから求められない限り、実装に関する助言に話を広げません。
2. プロジェクトが想定されるパッケージルート、pnpm、packageManager、pnpm-lock.yaml、ワークスペース設定、スクリプト、tsconfig.json、ESLint のフラット設定、Prettier を使用しているかを報告します。
3. npm/yarn/Corepack/レガシーな構成からの逸脱を指摘し、その理由が references/edge-cases.md に合致していることを求めます。
4. 例外が文書化されていない限り、リポジトリで必須のツールを npm install、npx、または場当たり的なグローバルバイナリに置き換える推奨事項は認めません。

必須要件

• パッケージマネージャー：例外が文書化されていない限り、JS/TS のパッケージ操作には pnpm を使用します。
• パッケージマネージャーの固定：最も近い該当の package.json と、その packageManager フィールドに従います。
• ロックファイル：pnpm-lock.yaml をコミットします。移行計画なしに、同一のパッケージルートでロックファイルを混在させてはいけません。
• インストール：pnpm install を使用します。CI では pnpm install --frozen-lockfile を使用します。
• 依存関係：該当パッケージのルートから pnpm add <pkg> または pnpm add -D <pkg> を使用します。
• ローカルバイナリ：pnpm exec <cmd> を使用します。レジストリから一度だけ実行する場合に限り、pnpm dlx <pkg> を使用します。
• スクリプト：pnpm run <script> または pnpm --filter <pkg> run <script> を使用します。
• 型チェック：pnpm exec tsc --noEmit またはリポジトリのパッケージスクリプトを使用します。
• リント：新しい ESLint 設定では、ESLint のフラット設定を使用します。
• フォーマット：フォーマットには Prettier を、コード品質ルールには ESLint を使用します。

推奨設定

新しい JS/TS 作業を始める際、より強いローカルの制約がない場合は、これらのツールを優先してください。 これらはデフォルトであり、絶対的なルールではありません。既存のプロジェクトの選択を変更する前に、 references/edge-cases.md を確認してください。

目的	ツール	備考
パッケージマネージャー	pnpm	パッケージルートが package.json を所有する場合は、packageManager でバージョンを固定します
バンドラー	vite または esbuild	まずフレームワークが管理するビルダーを優先します
リント	eslint	新規セットアップではフラット設定を使用します
フォーマット	prettier	フォーマットとリントを分けます
テスト	vitest またはフレームワーク標準のランナー	既存のリポジトリスクリプトを優先します
型チェック	tsc --noEmit	pnpm exec またはパッケージスクリプト経由で実行します

TypeScript の型安全性

1. any より unknown を優先し、コードをコンパイルするために既存の厳格さを弱めないでください。
2. オブジェクトの形状には interface を、ユニオン、インターセクション、マップ型には type を優先してください。
3. ステートマシンやタグ付きバリアントには判別可能なユニオンを使用してください。
4. 安全でないアサーションを使わずにリテラル推論を維持するには、as const と satisfies を使用してください。
5. 型アサーション（as）は避け、型ガード、アサーション関数、境界でのスキーマ検証を優先してください。
6. 新しい TypeScript プロジェクトでは strict を有効にし、リポジトリが対応できる場合はさらに厳格なオプションを追加してください。
7. 型の契約が公開されている場合は、@ts-expect-error または型テストツールで負の型動作をテストしてください。
8. TSConfig、モジュール解決、型の絞り込みパターンについては、references/typescript-patterns.md を参照してください。

重要なルール

1. references/edge-cases.md に npm、yarn、または別のマネージャーを使う正当な理由が記載されていない限り、JS/TS の依存関係を変更する際は pnpm を必須とします。
2. パッケージコマンドを実行する前に、そのパッケージを所有するルートを特定してください。リポジトリのルートがすべての JS/TS ファイルを所有すると決めつけないでください。
3. 専用の移行作業を除き、同じパッケージルート内で pnpm-lock.yaml、package-lock.json、yarn.lock を混在させないでください。
4. pnpm-lock.yaml がある場合、CI でのインストールには pnpm install --frozen-lockfile を実行してください。
5. ローカルのバイナリには pnpm exec を使用し、レジストリから取得した単発のパッケージに限り pnpm dlx を使用してください。
6. 現在の Node.js ランタイムに Corepack が同梱されていると決めつけないでください。Corepack のセットアップを推奨する前に references/edge-cases.md を確認してください。
7. フォーマットは Prettier が担当し、コード品質ルールは ESLint が担当するようにしてください。
8. 混在言語の作業や JS が主ではない作業は、このスキルをタスク全体に無理に適用せず、references/redirection-boundaries.md に従って振り分けてください。

規模に応じた方針

• JS/TS が主ではないタスクに含まれる付随的な JS/TS ファイル：JS/TS が所有する範囲に関わる必須要件のみ適用し、混在ワークフローに関する質問は references/redirection-boundaries.md に従って振り分けます。
• JS/TS が主となる機能開発またはリファクタリング作業：関連する場合は、ツール、TypeScript、リント、フォーマット、テストのガイダンスを含む運用契約全体を適用します。
• リポジトリ全体の JS/TS ツール整備または移行作業：check、references/tooling-contract.md、references/edge-cases.md を使用し、必須の違反事項と、文書化された移行手順を区別します。

段階的な情報開示

• デフォルトですべてのリファレンスを読み込まないでください。
• コマンド、依存関係、パッケージルート、ワークスペース、ロックファイル、または CI に関する質問では、まず references/tooling-contract.md を読んでください。
• リクエストに Python、シェル、CI、インフラ、またはフレームワーク固有の作業が混在する場合は、references/redirection-boundaries.md を読んでください。
• npm、yarn、Corepack のセットアップ、生成されたアプリのスキャフォールディング、またはロックファイル移行の例外が必要と思われる場合に限り、references/edge-cases.md を読んでください。
• TypeScript コード、tsconfig.json、公開型、または型テストが対象となる場合に限り、references/typescript-patterns.md を読んでください。
• リント、型付きリント、またはフォーマットが対象となる場合に限り、references/eslint-prettier.md を読んでください。

適用範囲の境界

対象： JS/TS のツールに関する規約、Node のパッケージコマンド、依存関係管理のルール、TypeScript の型安全性に関するデフォルト、lint／format／test コマンドの指針、例外を考慮したリポジトリの指針です。

対象外： Python の規約、シェルの規約、CI パイプラインの設計、フレームワークのアーキテクチャ、バックエンド専用の実装方針、または広範なフロントエンド UX／デザインの指針です。

標準用語（以下の表記を厳守してください）：

• pnpm -- JS/TS パッケージ操作で必須のパッケージマネージャー
• package root -- コマンドまたは依存関係を管理する package.json がある最も近いディレクトリ
• packageManager -- パッケージマネージャーとバージョンを固定する package.json のフィールド
• pnpm-lock.yaml -- pnpm のパッケージルートで使用する標準の JS/TS ロックファイル
• workspace -- pnpm-workspace.yaml で宣言された pnpm ワークスペース
• frozen-lockfile -- ロックファイルの変更を防ぐ CI のインストールモード
• pnpm exec -- ローカルプロジェクトのバイナリ実行
• pnpm dlx -- レジストリからの単発パッケージ実行

検証条件

変更を完了と宣言する前に、このスキルディレクトリから実行してください：

python scripts/check.py
git diff --check

完了条件：

1. scripts/check.py が 0 で終了すること。
2. git diff --check が 0 で終了すること。
3. このスキルディレクトリ内に portable-CLI 違反が残っていないこと。

スキル定義、公開用の説明、参照ファイル、または評価の動作を変更した後は、利用可能な場合 docs-steward を呼び出してください。