@einja/dev-cli 0.1.6

package/scaffolds/steering/development/review-guidelines.md

@@ -0,0 +1,365 @@
+# 実装レビューガイドライン
+
+このドキュメントは、task-reviewerエージェントおよび開発者が実装レビューを行う際の観点を定義します。
+
+## 🚨 レビュー前の必須確認事項
+
+すべての実装レビューでは、以下のドキュメントへの準拠を**必ず確認**してください：
+
+### フロントエンド実装（tsx, css ファイル）のレビュー時
+
+**📘 [フロントエンド開発ガイド](frontend-development.md) への準拠必須**
+
+レビュー時に確認すべき主要項目：
+- [ ] **Server Component / Client Componentの適切な使い分け**
+  - page.tsxでの`'use client'`使用は禁止
+  - インタラクティブ機能のみClient Component化
+  - `'use client'`境界が最小限に抑えられているか
+- [ ] **Tanstack Queryの正しい使用**
+  - useQuery / useMutationがClient Componentで使用されているか
+  - queryKeyが適切に設計されているか
+  - データ更新時のキャッシュ無効化が適切に実装されているか
+- [ ] **React Hook Formの正しい使用**
+  - Zodスキーマとの統合（zodResolver）
+  - フォームバリデーションの実装
+- [ ] **Hono Clientによる型安全なAPI呼び出し**
+  - エンドツーエンド型推論が機能しているか
+  - 適切なエラーハンドリング
+
+### バックエンド実装（API, ビジネスロジック）のレビュー時
+
+**📙 [バックエンドアーキテクチャ](backend-architecture.md) への準拠必須**
+
+レビュー時に確認すべき主要項目：
+- [ ] **4層レイヤードアーキテクチャの遵守**
+  - Presentation層: API Routes（Hono Router）
+  - Application層: UseCases（各アプリ内に配置）
+  - Domain層: エンティティ、Repository Interface
+  - Infrastructure層: Repository実装、Mapper
+- [ ] **Repositoryパターンの正しい実装**
+  - Domain層にインターフェース定義
+  - Infrastructure層に実装
+  - SearchCriteria型の設計（すべてオプショナル）
+- [ ] **Mapperパターンの使用**
+  - Prismaモデル ⇔ Domainエンティティの変換
+  - Infrastructure層に配置
+- [ ] **Result型パターンの使用**
+  - 例外を使わないエラーハンドリング
+  - `{ isSuccess: true/false, value/error }` の形式
+- [ ] **UseCase統合パターン**
+  - リソース単位で1ファイルに統合
+  - オブジェクトリテラル形式（クラスではない）
+- [ ] **パッケージエクスポート**
+  - index.ts不使用（直接ファイルパス指定）
+  - 絶対パスインポート（`@repo/server-core/...`）
+
+---
+
+## API開発ガイドへの準拠確認
+
+APIエンドポイントやアプリケーション機能の実装レビュー時は、必ず以下を確認：
+
+- [ ] **API開発ガイドの実装ルール遵守**
+  - UseCaseはオブジェクト形式で実装されているか（クラスではない）
+  - Repositoryの型変換でMapperが適切に使用されているか
+  - Zodスキーマによるバリデーションが全エンドポイントで実装されているか
+  - **🔗 Honoのメソッドチェーン形式が守られているか** - `new Hono().get().post().put().delete()`の形式で実装すること。個別呼び出し形式（`app.get(); app.post();`）では`typeof app`による型推論が損なわれ、Hono Clientでの型安全性が失われる（詳細: [API開発ガイド - メソッドチェーンパターン](./development/api-development.md#メソッドチェーンパターン)）
+  - **🔗 サブルート内で`.use()`を使っていないか** - ミドルウェアはメインアプリ側で適用すること。サブルート内で`.use()`を使うと型が`ClientRequest<{}>`になり型推論が壊れる（詳細: [API開発ガイド - ミドルウェアと型推論](./development/api-development.md#ミドルウェアと型推論の注意点)）
+  - エラーハンドリングがApplicationErrorで統一されているか
+  - loggerが使用され、console.logが使われていないか
+  - **相対パスの使用禁止** - import文、require文、ファイルパス指定で`../`や`./`などの相対パスが使用されていないか。必ずアプリ固有エイリアス（`@web/*`、`@admin/*`等）またはパッケージ名（`@repo/server-core`等）を使用すること
+
+## APIクライアント実装ガイドへの準拠確認
+
+フロントエンドのAPIクライアント実装レビュー時は、必ず以下を確認：
+
+- [ ] **APIクライアント実装ガイドの実装ルール遵守**
+  - Tanstack QueryとHonoクライアントを使用した型安全な実装になっているか
+  - Zodスキーマによるレスポンス検証が実装されているか
+  - apiClientsディレクトリ構成が守られているか（フェッチ関数とhooksの分離）
+  - useMutationでのキャッシュ無効化が適切に実装されているか
+  - エラーハンドリングが実装されているか
+  - 型定義の整合性が保たれているか（バックエンドとフロントエンド間）
+
+## 設計原則
+
+### 責務と凝集度・結合度
+
+- [ ] **単一責任の原則 (SRP)**: クラスやメソッドは一つの明確な責務を持つか
+- [ ] **高凝集・疎結合**: 関連性の高いコードがまとめられ、モジュール間の依存が最小限か
+- [ ] **適切なロジック配置**: ビジネスロジックやデータ操作が適切なクラスに配置されているか
+- [ ] **継承より委譲**: 安易な継承ではなく委譲を優先しているか
+- [ ] **関心の分離 (SoC)**: UI、ビジネスロジック、データアクセスが適切に分離されているか
+- [ ] **インターフェースと実装の分離**: 具象クラスへの直接依存を避けているか
+
+### SOLID原則
+
+- [ ] **単一責任の原則**: 一つのクラスに一つの変更理由のみ存在するか
+- [ ] **オープン/クローズドの原則**: 拡張に開き、修正に閉じた設計か
+- [ ] **リスコフの置換原則**: 派生クラスは基底クラスと置換可能か
+- [ ] **インターフェース分離の原則**: 使用しないメソッドへの依存を強制していないか
+- [ ] **依存性逆転の原則**: 高レベルモジュールが低レベルモジュールに依存していないか
+
+### シンプルさとYAGNI
+
+- [ ] **シンプルさ (KISS)**: 必要以上に複雑になっていないか
+- [ ] **YAGNI**: 現時点で不要な機能や汎用化を避けているか
+- [ ] **標準的な方法の利用**: より単純な標準的方法で実装可能か
+
+### 抽象化
+
+- [ ] **適切な抽象化レベル (SLAP)**: 同じルーチン内で抽象レベルが混在していないか
+- [ ] **重複ロジックの抽出**: 重複するロジックが適切に共通化されているか
+- [ ] **車輪の再発明の回避**: 標準ライブラリや既存ライブラリで実現可能か
+
+## コード品質
+
+### 可読性・理解可能性
+
+- [ ] **明確さと意図**: コードの意図が明確に伝わるか
+- [ ] **ネストの深さ**: 深いネストを避け、ガード節や早期リターンを活用しているか
+- [ ] **論理的な順序**: ステートメントが論理的な順序で記述されているか
+- [ ] **線形原理**: 処理の流れが上から下へ自然に読み進められるか
+
+### 命名
+
+#### 命名規則一覧
+
+プロジェクト全体で以下の命名規則を遵守すること：
+
+| 対象 | 命名規則 | 例 |
+|------|----------|-----|
+| Prismaモデル名 | PascalCase | `User`, `MagicLinkToken` |
+| Prismaカラム名 | camelCase | `userId`, `createdAt` |
+| データベーステーブル名 | snake_case | `users`, `magic_link_tokens` |
+| ファイル名 | kebab-case | `user-service.ts`, `magic-link.tsx` |
+| URLパス | kebab-case | `/api/magic-link`, `/user-profile` |
+| TSXコンポーネントファイル | PascalCase | `UserProfile.tsx`, `MagicLinkForm.tsx` |
+| 関数名 | camelCase | `getUserById`, `sendMagicLink` |
+| 変数名 | camelCase | `userData`, `magicLinkToken` |
+| クラス名 | PascalCase | `UserService`, `MagicLinkValidator` |
+| `as const`をつける定数名 | UPPER_SNAKE_CASE | `API_ENDPOINTS`, `DEFAULT_TIMEOUT` |
+
+#### 命名の品質チェック
+
+- [ ] **明確で具体的**: 変数、メソッド、クラス名が役割を正確に伝えているか
+- [ ] **一貫性**: 上記の命名規則や用語が一貫しているか
+- [ ] **副作用の明示**: 副作用のあるメソッドには動詞を使用しているか
+- [ ] **驚き最小の原則**: 名前から期待される動作と実際の動作が一致しているか
+
+### コードの重複回避 (DRY)
+
+- [ ] **ロジックの重複**: 同じコードが複数箇所に存在していないか
+- [ ] **設定や定数の重複**: 設定値や定数が一元管理されているか
+
+### 複雑性
+
+- [ ] **コードの単純さ**: 必要以上に複雑なロジックになっていないか
+- [ ] **早期最適化の回避**: 計測に基づかないパフォーマンスチューニングを避けているか
+
+### マジックナンバー/文字列
+
+- [ ] **定数化**: 意味のある数値や文字列が定数として定義されているか
+
+### 不要なコードの削除
+
+- [ ] **未使用コード**: 使用されていない変数、メソッド、クラスが存在しないか
+- [ ] **デッドコード**: 到達不能なコードが存在しないか
+- [ ] **コメントアウトされたコード**: 不要なコメントアウトコードが残っていないか
+
+### コメント
+
+- [ ] **「なぜ」を説明**: コードの意図や理由を説明しているか
+- [ ] **有益性**: 複雑なアルゴリズムやワークアラウンドを適切に説明しているか
+- [ ] **正確性と最新性**: コメントがコードと一致し最新の状態か
+- [ ] **自己文書化**: コード自体を分かりやすく書くことでコメントを減らしているか
+
+### スタイルとフォーマット
+
+- [ ] **スタイルガイド準拠**: プロジェクトのスタイルガイドに従っているか
+- [ ] **一貫性**: コーディングスタイルが一貫しているか
+- [ ] **視覚的構造**: インデントや空白行がコードの論理構造を表現しているか
+
+### エラーハンドリング
+
+- [ ] **予期せぬ入力への対応**: 不正な値に対する考慮がされているか
+- [ ] **適切な例外処理**: 例外を制御フローとして使用していないか
+- [ ] **エラー情報の記録**: 原因究明に必要な情報がログに記録されるか
+- [ ] **リソース解放**: エラー発生時もリソースが確実に解放されるか
+- [ ] **トランザクション管理**: データ更新処理が適切にトランザクション管理されているか
+
+### 防御的プログラミング
+
+- [ ] **入力値検証**: パラメータが期待される範囲や型であるか検証しているか
+- [ ] **安全原理**: エッジケースや潜在的なエラー条件を考慮しているか
+
+### データ型と構造
+
+- [ ] **適切なデータ型**: 格納するデータに適した型が選択されているか
+- [ ] **Enumの適切な利用**: Enumの値設定やバリデーションが適切か
+
+### パフォーマンス
+
+- [ ] **効率的なアルゴリズム**: 処理内容に対して効率的なアルゴリズムが選択されているか
+- [ ] **N+1問題**: ループ内での都度クエリ発行を避けているか
+- [ ] **不要なデータ取得**: 必要なデータのみを取得しているか
+- [ ] **インデックス**: 検索条件となるカラムにインデックスが設定されているか
+
+### APIクライアント実装
+
+- [ ] **キャッシュ無効化**: 関連するクエリキャッシュが適切に無効化されているか
+- [ ] **キャッシュ戦略の一貫性**: 統一されたキャッシュ無効化パターンが使用されているか
+- [ ] **エラーハンドリング**: APIエラー時の処理が適切に実装されているか
+- [ ] **型安全性**: Zodスキーマと TypeScriptの型が一貫しているか
+
+## コードスメル検出
+
+以下のコードスメル（改善が必要なコードの兆候）がないか確認します。
+
+### 肥大化 (Bloaters)
+
+- [ ] **長すぎるメソッド**: メソッドが50行を超えていないか
+  - 対策: 小さなメソッドに分割する
+- [ ] **巨大なクラス**: クラスが複数の責任を持っていないか
+  - 対策: 責任ごとにクラスを分割する
+- [ ] **長いパラメータリスト**: メソッドのパラメータが3-4個を超えていないか
+  - 対策: パラメータオブジェクトを導入する
+- [ ] **データの群れ**: 同じデータ群が複数箇所に出現していないか
+  - 対策: データクラスを作成する
+- [ ] **深いネスト**: if/for/while等のネストが3レベル以上になっていないか
+  - 対策1: 早期リターン（guard clause）で条件を反転させ平坦化する
+  - 対策2: 条件を名前付き変数やヘルパー関数に抽出する
+  - 対策3: 三項演算子で設定値を事前に決定し、共通処理をまとめる
+
+### 濫用 (Abusers)
+
+- [ ] **switch文の濫用**: 同じswitch文が複数箇所に存在しないか
+  - 対策: ポリモーフィズムで置き換える
+- [ ] **一時的フィールド**: 特定の状況でのみ使用されるフィールドがないか
+  - 対策: Null Objectパターンやクラス抽出を検討する
+- [ ] **拒否された遺贈**: サブクラスが親クラスのメソッドやプロパティを使用していないか
+  - 対策: 継承を委譲に置き換える
+
+### 変更の障害 (Change Preventers)
+
+- [ ] **発散的変更**: 一つのクラスが複数の理由で頻繁に変更されないか
+  - 対策: 単一責任の原則に従ってクラスを分割する
+- [ ] **散弾銃手術**: 一つの変更のために多くのクラスを修正する必要がないか
+  - 対策: メソッドやフィールドの移動で関連コードを集約する
+
+### 不要なもの (Dispensables)
+
+- [ ] **コメント過多**: コードの意図が分かりにくく、多くのコメントが必要になっていないか
+  - 対策: メソッド抽出やリネーミングでコードを自己文書化する
+- [ ] **重複コード**: 同じコードが複数箇所に存在しないか
+  - 対策: メソッド抽出や共通化を実施する
+- [ ] **怠惰なクラス**: ほとんど何もしないクラスが存在しないか
+  - 対策: 不要なクラスは削除または統合する
+- [ ] **推測的一般性**: 将来使うかもしれない機能が実装されていないか
+  - 対策: YAGNI原則に従い、現時点で不要な機能は削除する
+
+### カプセル化の欠如 (Couplers)
+
+- [ ] **不適切な親密さ**: クラスが他クラスの内部実装に依存していないか
+  - 対策: カプセル化を強化し、適切なインターフェースを提供する
+- [ ] **メッセージの連鎖**: `a.getB().getC().doSomething()` のような呼び出しがないか
+  - 対策: デメテルの法則に従い、中間オブジェクトを隠蔽する
+- [ ] **仲介人**: メソッドの大半が他のオブジェクトへの委譲になっていないか
+  - 対策: 不要な仲介クラスを削除する
+
+### 特有のスメル
+
+#### TypeScript/JavaScript特有
+
+- [ ] **型アサーション (`as`) の濫用**: 型の安全性を損なう使い方をしていないか
+- [ ] **any型の使用**: any型を避け、適切な型定義を使用しているか
+- [ ] **非同期処理の不適切な扱い**: Promise の適切なエラーハンドリングがされているか
+- [ ] **オプショナルチェーンの過度な使用**: データ構造設計の問題を示していないか
+
+#### React特有
+
+- [ ] **巨大なコンポーネント**: コンポーネントが複数の責任を持っていないか
+  - 対策: プレゼンテーショナルコンポーネントとコンテナコンポーネントに分離
+- [ ] **Prop Drilling**: プロパティを多階層で渡していないか
+  - 対策: Context API や状態管理ライブラリを検討
+- [ ] **useEffectの濫用**: 副作用が適切に管理されているか
+  - 対策: カスタムフックへの抽出や、副作用の最小化
+
+## テスト
+
+### テストケースの品質
+
+- [ ] **網羅性**: 正常系、異常系、境界値が適切にテストされているか
+- [ ] **独立性**: テストケースが他のテストに依存していないか
+- [ ] **安定性**: 実行ごとに結果が変わらないか
+- [ ] **正確なアサーション**: 適切で明確なアサーションが使われているか
+
+### テストコードの可読性
+
+- [ ] **構造化**: Arrange/Act/Assertの構造が明確か
+- [ ] **期待値の明確さ**: テストコード単体で期待値の根拠が分かるか
+- [ ] **不要なテストの排除**: フレームワークの標準機能自体をテストしていないか
+
+## ドキュメンテーション
+
+- [ ] **コードの意図の明確化**: 理解が難しいロジックに適切なコメントがあるか
+- [ ] **関連ドキュメントの更新**: コード変更に伴いドキュメントも更新されているか
+- [ ] **設計と実装の分離**: 設計書に実装コードを書いていないか
+
+## 並列レビュー観点
+
+task-reviewerエージェントは以下の4観点を**Taskツールで並列にサブエージェントを呼び出して**レビューします。
+
+> **注意**: 各観点は独立したExploreエージェントで並列実行されます。
+> task-reviewerは**1つのメッセージで4つのTask tool_use**を同時に呼び出してください。
+
+### 1. アーキテクチャ観点
+**対象セクション**: フロントエンド/バックエンド実装レビュー、設計原則、SOLID原則
+- フロントエンド: Server/Client Component使い分け、Tanstack Query、React Hook Form
+- バックエンド: 4層アーキテクチャ、Repositoryパターン、Result型パターン
+- 設計原則: SRP、高凝集・疎結合、関心の分離
+
+### 2. コード品質観点
+**対象セクション**: コード品質
+- 可読性・理解可能性
+- 命名規則
+- DRY、複雑性
+- エラーハンドリング、防御的プログラミング
+- パフォーマンス（N+1問題、インデックス）
+
+### 3. コードスメル観点
+**対象セクション**: コードスメル検出
+- 肥大化: 長いメソッド、巨大クラス、深いネスト
+- 濫用: switch文濫用、一時的フィールド
+- 変更の障害: 発散的変更、散弾銃手術
+- TypeScript/React特有のスメル
+
+### 4. テスト品質観点
+**対象セクション**: テスト
+- 網羅性（正常系、異常系、境界値）
+- 独立性、安定性
+- **Given-When-Then形式**（= Arrange/Act/Assert形式）での構造化
+
+---
+
+## レビュー時の注意事項
+
+### コミュニケーション
+
+- **敬意を持つ**: コードに対してコメントし、開発者を批判しない
+- **明確な指示**: 具体的な改善案や方向性を示す
+- **称賛**: 良いコードや改善は積極的に評価する
+
+### レビューの優先順位
+
+1. **設計上の問題**: アーキテクチャや責務分離の問題
+2. **機能の正確性**: バグや仕様違反
+3. **テストの品質**: テストカバレッジや品質
+4. **コードスメル**: 保守性を損なう兆候
+5. **命名やスタイル**: コーディング規約
+
+### 判断基準
+
+- **継続的改善**: 完璧ではなく、システム全体の健全性向上を重視
+- **好みと良し悪しの区別**: 客観的な改善提案と主観的な好みを明確に区別
+- **トレードオフの考慮**: パフォーマンス、可読性、保守性のバランスを考慮