marketing-shibata50/github-research-tool
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: worktreeを活用した並行作業管理の詳細を追加

Browse source 
- worktreeの利点と推奨ワークフローを明確化
- 複数のIssueを同時に進める具体例を示す
- 機能追加とバグ修正の標準的なワークフローを詳細に記述
- コミット戦略やブランチ名の規則を整理
This commit is contained in:
marketing-shibata50 2025-07-31 12:04:18 +09:00
parent 41075cf116
commit 6310729265
1 changed files with 543 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

545
MEMO.md
View file

@ -278,7 +278,26 @@ Google スプレッドシートにエクスポート
## worktreeを使った並行作業の管理 ## worktreeを使った並行作業の管理
複数のIssueを同時に進める場合の具体例： ### 重要な原則：基本的にすべてのブランチ作成はworktreeで行う
**なぜworktreeを使うべきか：**
- 現在の作業を一切中断せずに新しいブランチで作業開始できる
- stashやcommitを強制されない
- 複数の作業を自然に並行して進められる
- 心理的な切り替えコストがゼロ
**推奨ワークフロー：**
```bash
# ブランチを作る時は常にworktree
git worktree add -b feature/新機能 ../新機能-work develop
# 例外：worktreeを使わない場合
# - リポジトリを初めてcloneした直後
# - README.mdのtypo修正などごく簡単な修正
```
### 複数のIssueを同時に進める場合の具体例
- Issue #11: ログイン機能を作っている途中 - Issue #11: ログイン機能を作っている途中
- Issue #12: 急にバグ修正が必要になった - Issue #12: 急にバグ修正が必要になった
- Issue #13: UIの改善アイデアが浮かんだ - Issue #13: UIの改善アイデアが浮かんだ
@ -295,4 +314,526 @@ cd ../bugfix-work # バグ修正に切り替え
cd ../login-work # ログイン機能に戻る cd ../login-work # ログイン機能に戻る
``` ```
それぞれの作業場は完全に独立しているので、コミットしていない変更があっても問題なく切り替えられます。 それぞれの作業場は完全に独立しているので、コミットしていない変更があっても問題なく切り替えられます。
# 機能追加ワークフロー 詳細設計書
## 概要
既存のプロジェクトに新しい機能を追加する際の標準的なワークフローです。これは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ルールの追加
- テストケースの充実
- コードレビューのチェックリスト更新
- ドキュメントの改善