diff --git a/MEMO.md b/MEMO.md index e9ca1fe..f68ae2e 100644 --- a/MEMO.md +++ b/MEMO.md @@ -278,7 +278,26 @@ Google スプレッドシートにエクスポート ## worktreeを使った並行作業の管理 -複数のIssueを同時に進める場合の具体例: +### 重要な原則:基本的にすべてのブランチ作成はworktreeで行う + +**なぜworktreeを使うべきか:** +- 現在の作業を一切中断せずに新しいブランチで作業開始できる +- stashやcommitを強制されない +- 複数の作業を自然に並行して進められる +- 心理的な切り替えコストがゼロ + +**推奨ワークフロー:** +```bash +# ブランチを作る時は常にworktree +git worktree add -b feature/新機能 ../新機能-work develop + +# 例外:worktreeを使わない場合 +# - リポジトリを初めてcloneした直後 +# - README.mdのtypo修正などごく簡単な修正 +``` + +### 複数のIssueを同時に進める場合の具体例 + - Issue #11: ログイン機能を作っている途中 - Issue #12: 急にバグ修正が必要になった - Issue #13: UIの改善アイデアが浮かんだ @@ -295,4 +314,526 @@ cd ../bugfix-work # バグ修正に切り替え cd ../login-work # ログイン機能に戻る ``` -それぞれの作業場は完全に独立しているので、コミットしていない変更があっても問題なく切り替えられます。 \ No newline at end of file +それぞれの作業場は完全に独立しているので、コミットしていない変更があっても問題なく切り替えられます。 + +# 機能追加ワークフロー 詳細設計書 + +## 概要 +既存のプロジェクトに新しい機能を追加する際の標準的なワークフローです。これはgit worktreeの真価が最も発揮される場面で、複数の機能開発を並行して進めながら、高品質なコードを維持できます。 + +## 1. 計画フェーズ:アイデアを具体的なタスクに変換 + +### 概要 +新機能のアイデアや要望を、実装可能な具体的なタスクとして定義し、GitHubのIssueとして記録します。 + +### 流れ + +1. **機能要件の明確化**: + - 何を作るのか(What):ユーザーが実現したいこと + - なぜ必要なのか(Why):ビジネス価値や問題解決 + - どのように使われるのか(How):ユーザーストーリー + +2. **Issueの作成**: + ```markdown + タイトル: [Feature] コメント機能の実装 + + ## 概要 + 記事にコメントを投稿できる機能を追加する + + ## 要件 + - [ ] コメント投稿フォーム + - [ ] コメント一覧表示 + - [ ] コメントの削除機能(投稿者のみ) + + ## 技術的な検討事項 + - DBスキーマの追加(commentsテーブル) + - APIエンドポイント(POST /api/comments, GET /api/posts/:id/comments) + - フロントエンドコンポーネント + + ## 受け入れ条件 + - ユーザーがコメントを投稿できる + - 投稿されたコメントが即座に表示される + - 自分のコメントは削除できる + ``` + +3. **ラベルとプロジェクトボードへの追加**: + - `feature` ラベルを付ける + - 優先度(`priority: high/medium/low`)を設定 + - GitHub Projectsの「Todo」カラムに配置 + +4. **タスクの分解**(必要に応じて): + - 大きな機能は、サブタスクとして別のIssueに分割 + - 例:「コメントUI実装 #25」「コメントAPI実装 #26」 + +## 2. 開発フェーズ:効率的な実装とコミット戦略 + +### 概要 +worktreeを活用して、他の作業を妨げることなく新機能の開発に集中します。 + +### 流れ + +1. **最新のdevelopブランチを取得**: + ```bash + # メイン作業場でdevelopを最新に + cd ../my-project + git checkout develop + git pull origin develop + ``` + +2. **機能用の作業場を作成**: + ```bash + # Issue #24 のコメント機能用 + git worktree add -b feature/24-comment ../comment-work develop + cd ../comment-work + ``` + +3. **開発の進め方**: + - **小さなコミットを重ねる**:機能的な単位でこまめにコミット + - **コミットメッセージの規則**: + ```bash + # 機能追加 + git commit -m "feat: コメント投稿フォームのUIを作成 #24" + + # リファクタリング + git commit -m "refactor: コメント投稿処理を関数に切り出し #24" + + # テスト追加 + git commit -m "test: コメント投稿APIのテストを追加 #24" + ``` + +4. **定期的なプッシュ**: + ```bash + # 作業の区切りでリモートにプッシュ(バックアップ兼進捗共有) + git push origin feature/24-comment + ``` + +5. **他の作業への切り替え**(必要に応じて): + ```bash + # 急なバグ修正が必要になったら + cd ../my-project + git worktree add -b hotfix/25-urgent ../hotfix-work develop + cd ../hotfix-work + # バグ修正... + + # コメント機能に戻る + cd ../comment-work + # 作業継続(何も失われていない!) + ``` + +## 3. レビュー&テストフェーズ:品質保証と知識共有 + +### 概要 +プルリクエストを通じて、コードの品質を保証し、チーム内での知識共有を促進します。 + +### 流れ + +1. **セルフレビュー**(PR作成前): + ```bash + # 自分の変更を確認 + git diff develop...HEAD + + # 不要なデバッグコードやコメントを削除 + # コードフォーマットを整える + ``` + +2. **プルリクエストの作成**: + ```markdown + タイトル: feat: コメント機能を実装 #24 + + ## 概要 + 記事にコメントを投稿・表示する機能を実装しました。 + + ## 変更内容 + - コメント投稿フォームコンポーネント + - コメント一覧表示コンポーネント + - コメントAPI(POST/GET/DELETE) + - DBマイグレーション(commentsテーブル) + + ## テスト方法 + 1. 記事詳細ページを開く + 2. コメントフォームに入力して投稿 + 3. コメントが表示されることを確認 + 4. 自分のコメントの削除ボタンで削除できることを確認 + + ## スクリーンショット + [コメント機能のスクリーンショット] + + Closes #24 + ``` + +3. **自動テストとCI/CD**: + - GitHub Actionsが自動で起動 + - ユニットテスト、統合テスト、Lintが実行される + - テスト結果がPRに表示される + +4. **コードレビューのポイント**: + - **設計の妥当性**:アーキテクチャに沿っているか + - **コードの可読性**:他の人が理解しやすいか + - **テストの充実度**:エッジケースがカバーされているか + - **パフォーマンス**:N+1問題などがないか + - **セキュリティ**:SQLインジェクション対策など + +5. **フィードバック対応**: + ```bash + # レビューコメントに基づいて修正 + cd ../comment-work + # 修正作業... + + git commit -m "fix: レビュー指摘事項を修正(変数名を明確化) #24" + git push origin feature/24-comment + ``` + +## 4. マージ&デプロイフェーズ:安全な統合と後処理 + +### 概要 +承認された変更を安全にdevelopブランチに統合し、作業環境をクリーンアップします。 + +### 流れ + +1. **最終確認**: + - すべてのテストがパスしている + - レビューで「Approved」を得ている + - コンフリクトが解決されている + +2. **マージ戦略の選択**: + - **Squash and merge**:コミット履歴をきれいにしたい場合 + - **Create a merge commit**:詳細な履歴を残したい場合 + - **Rebase and merge**:直線的な履歴にしたい場合(上級者向け) + +3. **マージ実行**: + - GitHubのPRページで「Merge pull request」をクリック + - Issue #24 が自動的にクローズされる + +4. **作業場のクリーンアップ**: + ```bash + # メイン作業場に戻る + cd ../my-project + + # developを最新に更新 + git checkout develop + git pull origin develop + + # 不要になった作業場を削除 + git worktree remove ../comment-work + + # ローカルブランチを削除 + git branch -d feature/24-comment + + # リモートブランチを削除(任意) + git push origin --delete feature/24-comment + ``` + +5. **次のタスクへ**: + - GitHub Projectsで次のIssueを選択 + - 新しいworktreeで作業開始 + +## ベストプラクティス + +### コミット戦略 +- **頻度**:30分〜1時間に1回はコミット +- **粒度**:1つのコミットは1つの変更 +- **メッセージ**:何を変更したか、なぜ変更したかを明確に + +### ブランチ名の規則 +```bash +feature/{issue番号}-{簡潔な説明} +# 例:feature/24-comment +# feature/25-user-profile +# feature/26-search-api +``` + +### worktreeの整理 +```bash +# 現在のworktreeを確認 +git worktree list + +# 使わなくなったworktreeを定期的に削除 +git worktree prune +``` + +### 並行作業のコツ +- 各worktreeのターミナルタブに分かりやすい名前を付ける +- VSCodeなどのエディタで各worktreeを別ウィンドウで開く +- 作業中のIssue番号をプロンプトに表示する + +# バグ修正ワークフロー 詳細設計書 + +## 概要 +本番環境や開発中に発見されたバグを迅速かつ安全に修正するワークフローです。git worktreeを活用することで、現在の作業を中断することなく、緊急のバグ修正に対応できます。 + +## バグの分類と対応戦略 + +### バグの緊急度による分類 +1. **Critical(緊急)**: 本番環境でサービスが停止、データ損失の危険性 + - 対応:mainブランチから直接hotfixブランチを作成 + - 目標修正時間:即座〜数時間以内 + +2. **High(高)**: 主要機能が動作しない、多くのユーザーに影響 + - 対応:developブランチからbugfixブランチを作成 + - 目標修正時間:24時間以内 + +3. **Medium(中)**: 特定の条件下でのみ発生、回避策あり + - 対応:developブランチからbugfixブランチを作成 + - 目標修正時間:次のリリースまで + +4. **Low(低)**: UIの小さな不具合、影響が限定的 + - 対応:通常の機能追加と同じ扱い + - 目標修正時間:バックログで管理 + +## 1. 計画フェーズ:バグの記録と分析 + +### 概要 +バグを正確に記録し、再現可能な形で文書化します。これにより、修正の効率と品質が大幅に向上します。 + +### 流れ + +1. **バグの報告を受ける**: + - ユーザーからの報告 + - 監視システムからのアラート + - 開発中の発見 + +2. **Issueの作成**: + ```markdown + タイトル: [Bug] ログイン時に特定条件でエラーが発生する + + ## バグの概要 + メールアドレスに「+」記号が含まれる場合、ログインできない + + ## 再現手順 + 1. ログインページにアクセス + 2. メールアドレス「user+test@example.com」を入力 + 3. 正しいパスワードを入力 + 4. ログインボタンをクリック + + ## 期待される動作 + 正常にログインでき、ダッシュボードが表示される + + ## 実際の動作 + 「Invalid email format」エラーが表示される + + ## 環境 + - ブラウザ: Chrome 120.0 + - OS: Windows 11 + - 発生環境: 本番環境 + + ## エラーログ + ``` + Error: Email validation failed + at validateEmail (auth.js:45) + at login (auth.js:123) + ``` + + ## 影響範囲 + - 影響を受けるユーザー数: 約100名(推定) + - 業務への影響: ログインできないため、サービスが利用不可 + + ## 優先度 + High - 多くのユーザーがログインできない + ``` + +3. **ラベルとアサイン**: + - `bug` ラベルを付ける + - 優先度ラベル(`priority: critical/high/medium/low`) + - 必要に応じて担当者をアサイン + +4. **原因の初期分析**: + - エラーログの確認 + - 関連するコードの特定 + - 最近の変更履歴の確認 + +## 2. 開発フェーズ:迅速な修正と検証 + +### 概要 +worktreeを使って現在の作業を保持したまま、バグ修正に集中します。 + +### 流れ + +1. **修正用の作業場を作成**: + ```bash + # 通常のバグ(developから分岐) + cd ../my-project + git worktree add -b bugfix/27-login-validation ../bugfix-login develop + cd ../bugfix-login + + # 緊急のバグ(mainから分岐) + git worktree add -b hotfix/28-critical-auth ../hotfix-auth main + cd ../hotfix-auth + ``` + +2. **バグの再現**: + ```bash + # テスト環境でバグを再現 + # 自動テストを書いて、バグの存在を確認 + npm test -- --grep "email with plus sign" # 失敗することを確認 + ``` + +3. **修正の実装**: + - **最小限の変更**: バグ修正に必要な最小限の変更に留める + - **テストファースト**: まず失敗するテストを書き、それをパスするように修正 + ```bash + # テストを追加 + git add test/auth.test.js + git commit -m "test: メールアドレスに+記号を含む場合のテストを追加 #27" + + # バグを修正 + git add src/auth.js + git commit -m "fix: メールアドレスの+記号を正しく処理するように修正 #27" + ``` + +4. **修正の検証**: + ```bash + # すべてのテストが通ることを確認 + npm test + + # 手動でも動作確認 + npm run dev + # ブラウザで実際に「user+test@example.com」でログインを試す + ``` + +5. **関連する箇所の確認**: + ```bash + # 同じバグが他の箇所にないか確認 + grep -r "validateEmail" src/ + + # 影響範囲の確認 + git diff develop...HEAD + ``` + +## 3. レビュー&テストフェーズ:品質保証と再発防止 + +### 概要 +バグ修正の品質を保証し、同様のバグの再発を防ぐための対策を実施します。 + +### 流れ + +1. **プルリクエストの作成**: + ```markdown + タイトル: fix: メールアドレスの+記号を正しく処理 #27 + + ## 修正内容 + メールアドレスに「+」記号が含まれる場合にログインできない問題を修正しました。 + + ## 原因 + メールバリデーションの正規表現が「+」記号を許可していなかった + + ## 修正方法 + - 正規表現を修正し、RFC 5322準拠のメールアドレスを受け入れるように変更 + - 該当するテストケースを追加 + + ## テスト + - [x] ユニットテストを追加(+記号を含むメールアドレス) + - [x] 手動テスト完了 + - [x] 既存のテストがすべてパス + + ## 確認項目 + - [x] user+test@example.com でログインできる + - [x] 通常のメールアドレスでも引き続きログインできる + - [x] 不正なメールアドレスは適切に拒否される + + Fixes #27 + ``` + +2. **緊急度に応じたレビュープロセス**: + - **Critical**: 最小限のレビュー後、即座にマージ + - **High**: 通常のレビュープロセス(ただし優先的に) + - **Medium/Low**: 通常のレビュープロセス + +3. **回帰テストの実施**: + ```bash + # 影響を受ける可能性のある機能のテスト + npm test -- --grep "authentication" + npm test -- --grep "user registration" + ``` + +4. **根本原因分析**(RCA): + - なぜこのバグが発生したか + - なぜテストで検出できなかったか + - 今後の予防策は何か + +## 4. マージ&デプロイフェーズ:安全なリリースと事後対応 + +### 概要 +修正を本番環境に安全にデプロイし、問題が解決されたことを確認します。 + +### 流れ + +1. **マージ戦略**: + ```bash + # 通常のバグ修正(develop → main) + # 1. developにマージ + # 2. 次回リリース時にmainへ + + # 緊急のバグ修正(hotfix → main & develop) + # 1. mainに直接マージ + # 2. 即座にdevelopにもマージ(同期を保つ) + ``` + +2. **デプロイ前の最終確認**: + - ステージング環境でのテスト + - ロールバック計画の確認 + - 関係者への通知 + +3. **デプロイ実行**: + ```bash + # タグを作成(緊急修正の場合) + git tag -a v1.2.1 -m "Hotfix: Email validation fix" + git push origin v1.2.1 + + # デプロイ(CI/CDまたは手動) + ``` + +4. **デプロイ後の確認**: + - 本番環境での動作確認 + - エラーログの監視 + - ユーザーからのフィードバック確認 + +5. **作業場のクリーンアップ**: + ```bash + # メイン作業場に戻る + cd ../my-project + + # ブランチを最新に + git checkout develop + git pull origin develop + + # 作業場を削除 + git worktree remove ../bugfix-login + + # ブランチを削除 + git branch -d bugfix/27-login-validation + git push origin --delete bugfix/27-login-validation + ``` + +6. **事後対応**: + - 影響を受けたユーザーへの通知 + - ポストモーテム(重大なバグの場合) + - 再発防止策の実装 + +## ベストプラクティス + +### バグ修正の原則 +- **修正は最小限に**: バグ修正時にリファクタリングしない +- **テストファースト**: 必ずテストを書いてからバグを修正 +- **根本原因を修正**: 症状ではなく原因を修正する + +### コミットメッセージ +```bash +# バグ修正 +git commit -m "fix: [影響範囲] 具体的な修正内容 #issue番号" + +# 例 +git commit -m "fix: ログイン時のメールバリデーションエラーを修正 #27" +git commit -m "fix: APIレスポンスのnullチェックを追加 #28" +``` + +### 緊急対応時の心得 +1. **パニックにならない**: worktreeがあるので現在の作業は安全 +2. **手順を守る**: 緊急時こそ手順が重要 +3. **コミュニケーション**: 進捗を適時共有 +4. **記録を残す**: 後で振り返れるように + +### バグの再発防止 +- 同じパターンのバグを自動検出するlintルールの追加 +- テストケースの充実 +- コードレビューのチェックリスト更新 +- ドキュメントの改善 \ No newline at end of file