reviewing-typescript-code

TypeScript コード品質パターン

概要

Saleor Configurator コードベース向けのプロジェクト固有のコード品質チェックリストです。このプロジェクト特有の型安全性の規約、エラーハンドリングのパターン、アーキテクチャ標準を扱います。

使用するタイミング

• エンティティ型、サービス、リポジトリ、コンパレーター、フォーマッターを追加するとき
• デプロイステージやブートストラップメソッドを実装するとき
• Zod スキーマやエラークラスを作成するとき
• コミットや PR マージの前にコードをレビューするとき

クイックリファレンス

規約	ルール
any の禁止	プロダクションコードのみ禁止、テストモックでは許可
ブランド型	ドメイン値には EntitySlug、EntityName を使用
エラークラス	エラーコードを付けて BaseError を継承
GraphQL エラー	GraphQLError.fromCombinedError() でラップ
Zod エラー	ZodValidationError.fromZodError() でラップ
関数	10〜50 行が理想、最大 ~100 行
スタイル	ループより関数型（map/filter/flatMap）

品質チェックリスト

型安全性

• プロダクションコードに any 型がない
• 安全でないアサーション（as unknown as T）がない
• 正当な理由のない非 null アサーション（!）がない
• ドメイン値にブランド型（EntitySlug、EntityName）を使用している
• 継承より判別可能なユニオンを使用している
• リテラルを保持した型検証に satisfies を使用している
• 不変データに readonly を使用している

クリーンコード

• 関数ごとに単一責任
• 関数は 50 行未満（理想的には）
• 意味のある宣言的な名前
• 真偽値の名前には is/has/should/can の接頭辞を使用
• マジックナンバーの代わりに名前付き定数
• 長い条件分岐にはレジストリ/ストラテジーパターン
• 一貫性のためにアロー関数

関数型パターン

• 配列やオブジェクトを直接変更していない
• for/forEach ループより map/filter/flatMap
• reduce でスプレッドを蓄積しない（Map を使用）

エラーハンドリング

• カスタムエラーはエラーコードを付けて BaseError を継承
• GraphQL エラー: GraphQLError.fromCombinedError()
• Zod エラー: ZodValidationError.fromZodError()
• エラーメッセージは復旧の提案を含む実行可能なもの
• エラーに関連するコンテキストが含まれている

レビュー出力フォーマット

指摘事項は次のように構成します。

重大な問題

マージ前に必ず修正が必要な項目。

重要な改善点

対応すべきだがブロッキングではない項目。

提案

今後検討する余地のある nice-to-have な改善。

ポジティブな所見

特筆に値する、うまく実装されたパターン。

プロジェクト固有の規約

• エンティティの識別: Slug ベース（categories、products）と Name ベース（productTypes、pageTypes）
• サービスのパターン: validator、repository、logger によるコンストラクター DI
• リポジトリのパターン: GraphQL 操作をカプセル化し、レスポンスをドメインモデルにマッピング
• テストのパターン: vi.fn() モックとスキーマ生成のテストデータ
• Zod ファースト: ロジックを実装する前にスキーマを定義し、型には z.infer<> を使用

よくある間違い

間違い	修正
プロダクションコードで any を使用	unknown + 型ガードを使用
サービスに GraphQL 型を公開	リポジトリでドメイン型にマッピング
GraphQL 呼び出しでエラーコンテキストが欠落	エラーに操作名を含める
長い if-else チェーン	レジストリ/ストラテジーパターンにリファクタリング
reduce でスプレッドを蓄積	Map または Object.fromEntries を使用
ループ内での変更（push）	map/filter/flatMap を使用

参考資料

スキル参照ファイル

• アンチパターン - よくあるアンチパターンのコード例と修正方法
• 型安全性の例 - ブランド型、型ガード、判別可能なユニオン

プロジェクトリソース

• docs/CODE_QUALITY.md - 完全なコーディング標準
• docs/ARCHITECTURE.md - サービスのパターン
• biome.json - リンティングルール

関連スキル

• 完全なエンティティワークフロー: アーキテクチャパターンについては adding-entity-types を参照してください
• Zod 標準: スキーマレビュー基準については designing-zod-schemas を参照してください
• プリコミットチェック: 品質ゲートコマンドについては validating-pre-commit を参照してください

クイックリファレンスルール

簡潔なクイックリファレンスについては、.claude/rules/code-quality.md を参照してください（src/**/*.ts ファイルの編集時に自動的に読み込まれます）。