phase-8-review

フェーズ 8：アーキテクチャ／規約のレビュー

コードベース全体の品質を検証します

目的

デプロイ前にコードベース全体をレビューします。アーキテクチャの一貫性、規約への準拠、潜在的な問題を特定します。

このフェーズで実施すること

1. アーキテクチャレビュー：構造の一貫性を確認します
2. 規約レビュー：ルールへの準拠を確認します
3. コード品質レビュー：重複、複雑さ、潜在的なバグを確認します
4. リファクタリング：発見した問題を修正します

成果物

docs/03-analysis/
├── architecture-review.md      # Architecture review
├── convention-review.md        # Convention review
└── refactoring-plan.md         # Refactoring plan

PDCA の適用

• Plan（計画）：レビューの範囲／基準を定義します
• Design（設計）：チェックリストを作成します
• Do（実行）：コードレビューを実施します
• Check（評価）：問題を分析します
• Act（改善）：リファクタリングを行い、フェーズ 9 に進みます

レベル別の適用

レベル	適用方法
Starter	省略可能です（シンプルなプロジェクト）
Dynamic	必須です
Enterprise	必須です＋セキュリティレビュー

---

フェーズ全体の検証マトリクス

フェーズ間の一貫性検証

フェーズ 8 では、すべてのフェーズの成果物とルールが一貫して適用されていることを検証します。

┌─────────────────────────────────────────────────────────────────┐
│                    Cross-Phase Dependency Flow                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Phase 1 (Schema/Terminology)                                   │
│       ↓ Glossary, entity definitions                             │
│   Phase 2 (Coding Convention)                                    │
│       ↓ Naming rules, environment variable conventions           │
│   Phase 3 (Mockup)                                               │
│       ↓ Component structure, Props design                        │
│   Phase 4 (API)                                                  │
│       ↓ RESTful principles, response format, error codes         │
│   Phase 5 (Design System)                                        │
│       ↓ Design tokens, component variants                        │
│   Phase 6 (UI Implementation)                                    │
│       ↓ API client, type sharing, error handling                 │
│   Phase 7 (SEO/Security)                                         │
│       ↓ Security rules, metadata                                 │
│   Phase 8 (Review) ← Current stage: Full verification            │
│       ↓                                                          │
│   Phase 9 (Deployment)                                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

フェーズ固有の検証チェックリスト

フェーズ 1 → 検証：用語／スキーマの一貫性

□ Are glossary.md terms consistently used in code?
  - Business terms → Code naming matching
  - Global standard terms → API response field names matching
□ Do entity definitions match actual types?
□ Do relationship definitions match actual implementation?

フェーズ 2 → 検証：規約への準拠

□ Naming rule compliance (PascalCase, camelCase, UPPER_SNAKE_CASE)
□ Folder structure rule compliance
□ Environment variable naming rule compliance (NEXT_PUBLIC_*, DB_*, API_*, etc.)
□ .env.example template completion
□ Environment variable validation logic (lib/env.ts) exists

フェーズ 4 → 検証：API の一貫性

□ RESTful principle compliance
  - Resource-based URLs (nouns, plural)
  - Correct HTTP method usage
  - Status code consistency
□ Response format consistency
  - Success: { data, meta? }
  - Error: { error: { code, message, details? } }
  - Pagination: { data, pagination }
□ Error code standardization (matches ERROR_CODES constant)

フェーズ 5 → 検証：デザインシステムの一貫性

□ Are design tokens defined? (CSS Variables / ThemeData)
□ Do components use tokens? (no hardcoded colors)
□ Are component variants consistent?
□ Dark mode support (if defined)

フェーズ 6 → 検証：UI と API の統合における一貫性

□ API client layer structure compliance
  - Components → hooks → services → apiClient
  - No direct fetch calls
□ Type consistency
  - Phase 4 API spec types = Phase 6 client types
□ Error handling consistency
  - Global error handler usage
  - Error code-specific handling logic
□ State management pattern consistency

フェーズ 7 → 検証：セキュリティ／SEO の適用

□ Authentication/authorization middleware applied
□ Input validation (server-side)
□ XSS, CSRF defense
□ No sensitive info exposed to client
□ SEO meta tags applied

フェーズ 9 → 検証：デプロイの準備状況

□ Environment variable Secrets registered (based on Phase 2 list)
□ Environment separation (dev/staging/prod)
□ Build successful
□ Environment variable validation script passes

---

クリーンアーキテクチャの検証

レイヤー分離の原則

┌─────────────────────────────────────────────────────────────┐
│                      Presentation Layer                      │
│         (pages, components, hooks - UI concerns)             │
├─────────────────────────────────────────────────────────────┤
│                      Application Layer                       │
│         (services, use-cases - business logic)               │
├─────────────────────────────────────────────────────────────┤
│                       Domain Layer                           │
│         (entities, types - core domain models)               │
├─────────────────────────────────────────────────────────────┤
│                    Infrastructure Layer                      │
│         (api client, db, external services)                  │
└─────────────────────────────────────────────────────────────┘

Dependency direction: Outside → Inside (Presentation → Domain)
Inner layers must not know about outer layers

レイヤー別の検証チェックリスト

プレゼンテーション層（UI）

□ Is there business logic in components?
□ Are there direct API calls? (should go through hooks)
□ Is state management properly separated?
□ Do components have single responsibility?

アプリケーション層（サービス）

□ Are domain logic and infrastructure logic separated?
□ Are external dependencies abstracted?
□ Is the structure testable?
□ Are use cases clearly defined?

ドメイン層（型／エンティティ）

□ Are there no external library dependencies?
□ Does it contain only pure business rules?
□ Do types match Phase 1 schema?

インフラストラクチャ層（API クライアント）

□ Are external service calls abstracted?
□ Is error handling consistent?
□ Is configuration managed via environment variables?

---

アーキテクチャレビューチェックリスト

構造

• フォルダー構造は規約に沿っていますか
• 関心事は適切に分離されていますか
• 依存関係の方向は正しいですか（外側 → 内側）

パターン

• 一貫したパターンが使用されていますか
• 不要な抽象化はありませんか
• 適切にカプセル化されていますか

規約レビューチェックリスト

命名

• フェーズ 2 で定義したルールに従っていますか
• 意味のある名前が使用されていますか
• 一貫性はありますか

コードスタイル

• インデント、引用符などは統一されていますか
• ファイルの長さは適切ですか
• 関数の長さは適切ですか

コード品質チェックリスト

• コードの重複はありませんか
• 複雑すぎる関数はありませんか
• エラー処理は適切ですか
• 型安全性は確保されていますか

AI を活用したレビュー

Request code review from Claude:

"Review this project's code.
- Does it follow CONVENTIONS.md rules
- Is there architecture consistency
- Are there potential bugs or improvements"

テンプレート

templates/pipeline/phase-8-review.template.md を参照してください

次のフェーズ

フェーズ 9：デプロイ → レビュー完了後、本番環境にデプロイします

---

6. 詳細なコード品質レビュー

6.1 重複コードの検出

検出方法

# 1. Search for similar function names
grep -r "function.*format" src/
grep -r "function.*calculate" src/
grep -r "function.*get.*By" src/

# 2. Search for similar patterns
grep -rn "reduce.*sum" src/
grep -rn "filter.*map" src/
grep -rn "useState.*useEffect" src/

重複の種類別の対処方法

種類	例	解決策
完全な重複	同じコードをコピー＆ペースト	関数に切り出す
構造上の類似	ロジックは同じで、データが異なる	パラメーター化する
概念上の類似	類似した目的に対する異なる実装	統合するか、インターフェースを作成する

重複コードのチェックリスト

□ Is the same logic in 2+ places?
□ Are there multiple functions with similar names?
□ Is the same data transformation repeated?
□ Are similar UI patterns repeated?
□ Is the same API call pattern repeated?
□ Is similar error handling repeated?

6.2 再利用性の評価

評価基準

スコア	基準	説明
⭐⭐⭐	高	他のプロジェクトでも使用できます
⭐⭐	中	同じプロジェクト内の複数箇所で使用できます
⭐	低	特定の機能でのみ使用されます

再利用性チェックリスト

Check for each function/component:
□ Is it tied to a specific domain?
□ Does it depend on external state?
□ Are parameters generic?
□ Is the return value predictable?
□ Are there side effects?

6.3 拡張性の評価

拡張性の確認

When new requirements come:
□ Can it be added without modifying existing code?
□ Can behavior be changed by configuration only?
□ Is adding new types/cases easy?
□ Can it be extended without adding conditionals?

拡張性に関するアンチパターン

// ❌ Requires modification for each extension
function process(type: string) {
  if (type === 'a') { /* ... */ }
  else if (type === 'b') { /* ... */ }
  // Add else if for each new type...
}

// ❌ Hardcoded list
const ALLOWED_TYPES = ['a', 'b', 'c']

// ❌ Enumerated switch statements
switch (action.type) {
  case 'ADD': // ...
  case 'REMOVE': // ...
  // Add case for each new action...
}

拡張性に優れたパターン

// ✅ Registry pattern
const handlers: Record<string, Handler> = {}
function register(type: string, handler: Handler) {
  handlers[type] = handler
}
function process(type: string, data: unknown) {
  return handlers[type]?.(data)
}

// ✅ Configuration-based
const CONFIG = {
  types: ['a', 'b', 'c'],
  handlers: { ... }
}

// ✅ Plugin structure
interface Plugin { execute(data): Result }
const plugins: Plugin[] = []

6.4 オブジェクト指向の原則の確認

SOLID 原則チェックリスト

S - 単一責任の原則（SRP）

□ Does the class/function change for only one reason?
□ Does the name clearly explain the role?
□ Is "and" in the name? → Needs separation

O - オープン・クローズドの原則（OCP）

□ Is it open for extension? (new features can be added)
□ Is it closed for modification? (no existing code changes needed)
□ Are interfaces/abstractions used?

L - リスコフの置換原則（LSP）

□ Can subtypes replace parent types?
□ Do overridden methods keep the contract?

I - インターフェース分離の原則（ISP）

□ Is the interface too large?
□ Must unused methods be implemented?
□ Can the interface be split smaller?

D - 依存性逆転の原則（DIP）

□ Does it depend on abstractions instead of concrete classes?
□ Are dependencies injected? (DI)
□ Is the structure testable?

6.5 リファクタリングの優先順位

Urgent (Required before deployment):
1. Duplication that can cause bugs
2. Security vulnerabilities
3. Performance bottlenecks

High (As soon as possible):
4. Same logic duplicated in 3+ places
5. Files over 200 lines
6. Nesting deeper than 5 levels

Medium (Next sprint):
7. Structure lacking extensibility
8. Naming inconsistencies
9. Structure difficult to test

Low (Backlog):
10. Style inconsistencies
11. Excessive comments
12. Unused code

---

7. AI コードレビュー依頼テンプレート

Please review the code from these perspectives:

1. Duplicate Code
   - Are there similar functions/components?
   - Is there common logic that can be extracted?

2. Reusability
   - Can it be used generically?
   - Is it tied to a specific domain?

3. Extensibility
   - Can it flexibly respond to new requirements?
   - Are there hardcoded parts?

4. SOLID Principles
   - Does it follow single responsibility?
   - Is it open for extension and closed for modification?

5. Convention Compliance
   - Does it follow CONVENTIONS.md rules?
   - Is naming consistent?

Please identify parts that need refactoring and their priority.

---

8. ギャップ分析（設計と実装の比較）

ギャップ分析レポートのテンプレート

# Gap Analysis Report

## Analysis Target
- Design document: docs/02-design/{feature}.design.md
- Implementation path: src/features/{feature}/

## Results by Category

### API Endpoints
| Design | Implementation | Status |
|--------|----------------|--------|
| POST /api/users | POST /api/users | ✅ Match |
| GET /api/users/:id | - | ❌ Not implemented |
| - | DELETE /api/users/:id | ⚠️ Missing from design |

### Data Model
| Design Entity | Implementation | Status |
|---------------|----------------|--------|
| User | types/user.ts | ✅ Match |
| UserRole | - | ❌ Not implemented |

### Match Rate
- Total items: 10
- Matches: 7
- Not implemented: 2
- Missing from design: 1
- **Match Rate: 70%**

ギャップの種類と対応

ギャップの種類	意味	対応
✅ 一致	設計 = 実装	なし
❌ 未実装	設計にあるが、コードにない	実装するか、設計を更新する
⚠️ 設計に記載なし	コードにあるが、設計にない	設計書に追加する
🔄 相違	存在するが、内容が異なる	整合させる（コードを正とする）

ギャップ分析を実施するタイミング

• 機能の実装完了後
• デプロイ前
• 設計書の更新時
• コードレビュー中