| name | bp-typescript |
| description | Alt の TypeScript 規約を適用する。strict + noUncheckedIndexedAccess、境界では unknown、型ガード優先、satisfies、判別共用体の網羅性、Zod での境界バリデーション、起動時 env 検証の fail-fast、redirect パラメータの URL パース検証、connect-es エラーの numeric enum、wire スキーマの一本化を扱う。TypeScript のコードを書く・直す・レビューするときに使う。ユーザが「TypeScript」に触れなくても alt-frontend-sv / auth-token-manager / alt-perf の実装に入るなら使う。 |
| paths | ["**/*.ts","**/*.tsx"] |
TypeScript Best Practices
以下はタスク全体を通じて有効な規約であり、一度読んで終わる手順ではない。TypeScript コードを書くたびに適用する。
詳細な根拠とコード例が必要になった時点で docs/best_practices/typescript.md の該当セクションだけを Read する
（857 行あるため全文読み込みはしない）。
重要原則
- strict: true + noUncheckedIndexedAccess: 必須設定。弱めない
- 境界では unknown: 外部データ・API レスポンスは
unknown で受け、型ガードで narrowing。any は最小限
- 型ガード > 型アサーション:
as より type predicate (value is T) を優先。! 非 null アサーション禁止
- satisfies でリテラル推論保持:
Record<string, string> 等で型チェックしつつリテラル型を維持
- verbatimModuleSyntax:
import type { T } で型のみインポートを明示
- 判別共用体 + exhaustiveness: tagged union +
satisfies never で網羅性チェック
- Zod でランタイムバリデーション: API 境界は Zod スキーマで型とバリデーションを一元管理
- 起動時 env 検証で fail-fast: 必須 env（認証トークン等）欠落は Zod で throw。「認証なしで動き続ける」フォールバック禁止（→
.claude/rules/di-wiring.md）
- redirect パラメータは URL パースで検証: 文字列先頭チェックは
//evil.com で破られる
- connect-es エラーは numeric enum + ラップ前提:
ConnectError.code は数値 enum（string 比較は全エラーが default 行き）。native AbortError は ConnectError にラップされ err.name では捕まらない。エラーマッピングのテストは real ConnectError で書く
- wire スキーマは canonical 一本: producer/consumer での型再宣言は wire drift の温床。生成型 / 共有スキーマを両側で import。protojson は zero-value field を JSON から省略するので受信側は default 前提で読む
split(sep, limit) は残りを捨てる: Go の SplitN と非互換。= 区切りのトークン分解は indexOf + substring で書く
参照
完全なベストプラクティスは docs/best_practices/typescript.md を参照。
セクション: Strict Configuration, Type Safety, Discriminated Unions, Error Handling, Async Patterns, Zod Validation, Module Design
