開発フロー - rfdnxbro/trends-laravel GitHub Wiki

開発フロー

開発原則

DRY原則の適用

ドキュメント：

定義や説明の重複を避け、1つのドキュメントに集約
本ドキュメントに以下の内容を集約：
- テスト実行手順: 全テストフレームワークの実行方法
- 品質チェック: コードスタイル・静的解析の手順
- Claude Codeカスタムコマンド: 開発効率化ツールの詳細

コーディング：

コードの重複を避ける: 同じ処理を複数箇所で実装しない
共通ロジックの抽象化: 共通処理は適切にクラス・関数に抽象化
再利用性の重視: 汎用的な処理は共通化して再利用

他のドキュメントから重複する記述を削除し、本ドキュメントへの参照に統一しています。

基本的な開発フロー

1. ブランチの作成

開発はブランチを切って作業する

# 新しいブランチを作成
git checkout -b feature/new-feature

# または
git switch -c feature/new-feature

2. 開発作業

コードの実装
テストの作成・実行（必須）
- Unit Tests: ビジネスロジック・計算処理・バリデーション
- Feature Tests: API統合・HTTPエンドポイント・データベース連携
- E2E Tests: 新しいページ・機能に対するユーザージャーニー検証（新機能実装時は必須）
コードスタイルチェック
静的解析の実行

モデル作成時の必須要件

新しいモデルを作成する際は、以下を必ず含める：

Migration作成
- 適切なテーブル構造の定義
- 必要なインデックスと制約の設定
- コメントの追加
モデルクラス作成
- fillable属性の設定
- 適切な型キャスト（casts）の設定
- デフォルト値の設定（必要に応じて）
- リレーションの定義（必要に応じて）
ユニットテスト作成
- 基本的なモデル作成テスト
- 必須フィールドの検証テスト
- UNIQUE制約等の制約テスト
- デフォルト値の動作確認テスト
- fillable属性の確認テスト
- 型変換の確認テスト
- タイムスタンプの確認テスト
- リレーションのテスト（必要に応じて）

3. プルリクエストの作成

必ずプルリクエストを作成
適切なタイトルと説明を記述
レビュアーを指定

4. コードレビュー

必ずプルリクエストのレビューを通す
レビューでの指摘は修正する
承認後にmergeの準備が完了

5. マージ

その後GitHub上でmergeを行う
マージ後はローカルブランチを削除

ブランチ命名規則

推奨命名パターン

feature/機能名      # 新機能追加
bugfix/バグ修正名   # バグ修正
hotfix/緊急修正名   # 緊急修正
refactor/リファクタ名 # リファクタリング

例

feature/user-authentication
bugfix/login-error
hotfix/security-patch
refactor/database-queries

コミットメッセージ

フォーマット

種類: 概要

詳細説明（必要に応じて）

種類の例

feat: 新機能追加
fix: バグ修正
refactor: リファクタリング
test: テスト追加・修正
docs: ドキュメント更新

テスト戦略

テストピラミッドに基づく責務分離

このプロジェクトでは、効率的で保守性の高いテスト戦略としてテストピラミッドを採用し、各テストレベルの責務を明確に分離しています。

テストレベルと責務

           E2E Tests (少数・高価値)
          /                      \
     Feature Tests (適量・統合検証)
    /                              \
Unit Tests (多数・高速・詳細)

テストレベル	主要責務	検証対象	実行環境
Unit Tests	個別コンポーネントのロジック	バリデーション、計算処理、ビジネスロジック	モック・スタブ使用
Feature Tests	API統合・データフロー	HTTPエンドポイント、データベース連携、リクエスト/レスポンス	実際のHTTP + DB
E2E Tests	ユーザージャーニー	画面操作、ページ遷移、ワークフロー	ブラウザ自動化

テストの品質基準

境界値テスト: 異常系・エッジケースの網羅
エラーハンドリング: 各レベルで適切に検証
カバレッジ: 95%以上を維持

⚠️ E2Eテスト実装の必須要件

新しいページや機能を実装する際は、以下のE2Eテストの実装が必須です：

新しいページの実装時
- ページの基本表示確認
- 主要な操作フローの検証
- レスポンシブデザインの動作確認
- エラー状態の処理確認
新しい機能の実装時
- 機能の基本動作確認
- ユーザーインタラクションの検証
- 関連ページとの遷移確認

実装例

// tests/e2e/new-feature.spec.ts
test.describe('新機能ページ', () => {
  test('基本表示が正常に動作する', async ({ page }) => {
    // ページアクセス・表示確認
  });
  
  test('主要操作フローが動作する', async ({ page }) => {
    // ユーザー操作・結果確認
  });
});

E2Eテストなしでの新機能PR作成は禁止 - レビュー時に必ずチェックし、不足している場合は実装を求めてください。

E2Eテストの実装詳細

E2EテストにはPlaywrightを使用し、実際のブラウザでユーザーの操作フローを検証します：

📁 テストファイル構成 詳細な構成は tests/e2e/ を参照してください。

実装済みE2Eテスト

tests/e2e/homepage.spec.ts: ホームページの基本機能テスト
tests/e2e/article-list.spec.ts: 記事一覧ページの総合テスト（10テストケース）
tests/e2e/company-list.spec.ts: 企業一覧ページの総合テスト（10テストケース）
tests/e2e/company-detail.spec.ts: 企業詳細ページの総合テスト（12テストケース）

🎯 E2Eテストの焦点

✅ ページの基本表示（React アプリケーションのマウント）
✅ ナビゲーション要素の存在確認
✅ レスポンシブデザインの動作確認
✅ JavaScriptエラーの検出
✅ アプリケーション状態管理の確認

🚀 E2Eテスト実行方法

# 基本実行
npx playwright test

# ヘッドレスモードで実行（ブラウザ画面表示）
npx playwright test --headed

# 特定のテストのみ実行
npx playwright test tests/e2e/homepage.spec.ts

# テストレポート表示
npx playwright show-report

⚡ 実行パフォーマンス

実行時間: 約2分（13テスト）
並列実行: 4ワーカーで同時実行
対象ブラウザ: Chrome（Chromium）
CI環境: PostgreSQL + Laravel開発サーバー
MCP統合: Claude Codeでテスト自動化サポート

テスト・品質チェック

テスト実行コマンド

開発作業中の必須実行コマンド

開発中は以下を定期的に実行してCIエラーを事前に防ぐ：

# PHPUnit テスト実行
php artisan test

# テストカバレッジ確認
php artisan test --coverage-html=coverage-html
# 注意: カバレッジレポートは必ず coverage-html ディレクトリに出力してください

# コードスタイルチェック（自動修正）
vendor/bin/pint

# 静的解析
vendor/bin/phpstan analyse --memory-limit=1G

# フロントエンドテスト実行
npm test

# フロントエンドビルド
npm run build

# E2Eテスト実行
npx playwright test

PR作成前の必須チェック

すべて実行し、エラーがないことを確認する：

# 包括的品質チェック（一括実行）
php artisan test && vendor/bin/pint --test && vendor/bin/phpstan analyse --memory-limit=1G && npm test && npm run build && npm run test:e2e

⚠️ メモリ制限について:

PHPUnit: phpunit.xmlで512Mに設定済み（メモリ不足エラー対策）
PHPStan: --memory-limit=1Gオプション必須
大量テスト実行時のメモリ不足を防止

⚠️ 新機能実装時の追加チェック：

新しいページ・機能のE2Eテストが実装されていることを確認
E2Eテストが正常に実行されることを確認
E2Eテストが適切なユーザージャーニーをカバーしていることを確認

個別テスト実行

PHPUnitテスト:

# 全テスト実行
php artisan test

# 特定のテスト実行
php artisan test --filter TestName

# 特定のテストファイル実行
php artisan test tests/Unit/ModelTest.php

コードスタイルチェック:

# スタイルチェック（自動修正）
vendor/bin/pint

# ドライラン（確認のみ）
vendor/bin/pint --test

静的解析:

# 静的解析実行
vendor/bin/phpstan analyse --memory-limit=1G

フロントエンドテスト:

# フロントエンドテスト実行
npm test

# フロントエンドビルド
npm run build

E2Eテスト:

# E2Eテスト実行
npm run test:e2e

# E2Eテストレポート表示
npx playwright show-report

# E2Eテストをヘッドレスモードで実行
npm run test:e2e:headed

# デバッグモードで実行
npm run test:e2e:debug

# UIモードで実行
npm run test:e2e:ui

# 特定のテストファイルのみ実行
npx playwright test tests/e2e/homepage.spec.ts

✅ 自動実行される品質チェック（CI/CD）

PR作成時に並列自動実行されます：

品質チェックワークフロー（test.yml）:

PHPUnitテスト（667テスト）
フロントエンドテスト（189テスト、vitest）
Laravel Pintコードスタイルチェック
PHPStan静的解析（レベル4、警告ゼロ）
フロントエンドビルドテスト
スクレイピングサービステスト
環境: SQLite in-memory（高速・一貫性保証）
実行時間: 約2分

E2E専用CIワークフロー（e2e.yml）:

E2Eテスト（13テスト、Playwright）
PostgreSQLデータベース使用
4並列実行で高速化
Laravel開発サーバー起動
環境: PostgreSQL + ブラウザ自動化
実行時間: 約2分
MCP統合: Claude Code連携でテスト自動化

並列実行のメリット:

トータル実行時間: 約2分（並列実行で高速化）
テスト責務分離: ユニット・Featureテスト vs E2Eテスト
環境分離: SQLite vs PostgreSQL
CI統一化: ubuntu-latest + shivammathur/setup-php@v2

開発中の手動チェック（推奨）

開発中に以下を実行することで、CI/CDでのエラーを事前に防げます：

バックエンドテスト実行
```
php artisan test
```
フロントエンドテスト実行
```
npm test
```

コードスタイルチェック

vendor/bin/pint --test  # チェックのみ
vendor/bin/pint         # 自動修正

静的解析

vendor/bin/phpstan analyse --memory-limit=1G

フロントエンドビルド
```
npm run build
```

E2Eテスト実行

npx playwright test

# ヘッドレスモードで実行（ブラウザ画面表示）
npx playwright test --headed

# テストレポート表示
npx playwright show-report

# デバッグモードで実行
npx playwright test --debug

# UIモードで実行
npx playwright test --ui

テストでの日本語化Fakerの使用

テストでは日本語のダミーデータを生成するため、Fakerの日本語化を行っています。

実装の詳細は tests/TestCase.php を参照してください。

スクレイピング機能テスト

# キューワーカーの起動確認
php artisan queue:work --once

# スクレイピングJobの手動実行
php artisan tinker
dispatch(new App\Jobs\HatenaScrapingJob());

# Horizonでキューの状況確認
php artisan horizon:status

レビュー観点

コードレビューで確認すべき点

機能要件の実現
テストの妥当性
コードスタイルの統一
パフォーマンスの考慮
セキュリティの確保
可読性・保守性
E2Eテスト実装の確認
- 新しいページ・機能にE2Eテストが実装されているか
- E2Eテストが適切なユーザージャーニーをカバーしているか
- レスポンシブデザイン・エラー処理の検証が含まれているか
モデル関連の追加確認項目
- Migrationとモデルの整合性
- 適切なfillable属性の設定
- 型キャストの妥当性
- テストカバレッジの十分性（95%以上維持）
- 制約とバリデーションの適切性
スクレイピング関連の追加確認項目
- エラーハンドリングの実装
- リトライ機能の設定
- レート制限の考慮
- 外部サイトの利用規約遵守
- CompanyMatcherの適切な統合
- 企業マッチング精度の検証

wikiドキュメント更新の指示

更新タイミング

以下のような変更を行った際は、対応するwikiドキュメントの更新も検討してください：

技術的変更

新しいライブラリ・パッケージ追加 → 技術スタック.md
開発コマンド・環境設定変更 → 開発環境.md
CI/CDワークフロー変更 → CI-CD.md

データベース変更

migration追加・変更 → データベース設計.md
モデル追加・変更 → データベース設計.md

機能変更

新機能追加 → 機能仕様.md
既存機能の大幅変更 → 機能仕様.md

確認方法

変更後は以下を確認：

実装とwikiドキュメントの内容に矛盾がないか
新しい設定やコマンドがドキュメントに記載されているか
古い情報が残っていないか

Claude Codeカスタムコマンド

プロジェクトでは開発効率を向上させるため、以下のClaude Codeカスタムコマンドを提供しています：

利用可能なカスタムコマンド

`/think` - 開発方針の検討

開発前に技術的検討と実装計画を立てるためのコマンド

使用例：

/think ユーザー認証機能の実装

検討される内容：

技術的検討（技術スタック整合性、影響範囲、パフォーマンス・セキュリティ）
開発計画（実装手順、テストケース、課題・リスク）
出力形式（技術的判断、実装計画、注意点、テスト方針）

`/dev` - 開発実行

CLAUDE.mdの開発フローに従った実装を行うコマンド

使用例：

/dev 記事検索機能の実装

実行される内容：

ブランチ確認とGitHubイシュー管理
実装前テスト実行
段階的な実装と品質チェック
イシュー番号を含むコミット作成

`/test` - テスト実行

包括的な品質チェックを行うコマンド

使用例：

/test 記事検索機能

実行されるテスト：

PHPUnitテスト（単体・機能テスト）
コードスタイルチェック（Laravel Pint）
静的解析（PHPStan）
フロントエンドテスト（npm test）
フロントエンドビルド（npm run build）
E2Eテスト（Playwright）

`/pr` - プルリクエスト作成

完全なPRフローを実行するコマンド

使用例：

/pr 記事検索機能の実装

実行される内容：

ドキュメント更新チェック
品質チェック実行
Git操作（コミット、プッシュ、PR作成）
CI/CD確認

コマンドの特徴

Issue管理統合: 自動でGitHubイシューを作成・更新
品質チェック: 開発中に段階的な品質チェックを実行
ドキュメント連携: 関連ドキュメントの更新チェック
CI/CD統合: プルリクエスト後のCI/CD確認

使用方法

Claude Codeで対話中に/コマンド名引数で実行
各コマンドは引数として具体的な実装内容を受け取る
コマンドは自動的に適切な開発フローを実行

開発フロー - rfdnxbro/trends-laravel GitHub Wiki

開発フロー

開発原則

DRY原則の適用

基本的な開発フロー

1. ブランチの作成

2. 開発作業

モデル作成時の必須要件

3. プルリクエストの作成

4. コードレビュー

5. マージ

ブランチ命名規則

推奨命名パターン

例

コミットメッセージ

フォーマット

種類の例

テスト戦略

テストピラミッドに基づく責務分離

テストレベルと責務

テストの品質基準

⚠️ E2Eテスト実装の必須要件

E2Eテストの実装詳細

テスト・品質チェック

テスト実行コマンド

開発作業中の必須実行コマンド

PR作成前の必須チェック

個別テスト実行

✅ 自動実行される品質チェック（CI/CD）

開発中の手動チェック（推奨）

テストでの日本語化Fakerの使用

レビュー観点

コードレビューで確認すべき点

wikiドキュメント更新の指示

更新タイミング

技術的変更

データベース変更

機能変更

確認方法

Claude Codeカスタムコマンド

利用可能なカスタムコマンド

/think - 開発方針の検討

/dev - 開発実行

/test - テスト実行

/pr - プルリクエスト作成

コマンドの特徴

使用方法

関連ドキュメント

`/think` - 開発方針の検討

`/dev` - 開発実行

`/test` - テスト実行

`/pr` - プルリクエスト作成