@einja/dev-cli 0.1.6

package/scaffolds/steering/development-workflow.md

@@ -0,0 +1,429 @@
+# 開発ワークフロー
+
+このドキュメントでは、仕様書作成からタスク実行・レビュー・マージまでの開発フロー全体を説明します。
+
+## 概要
+
+本プロジェクトでは、Claude Codeを活用した自動化された開発ワークフローを採用しています。
+
+```
+仕様書作成（/spec-create）
+    ↓
+仕様書レビュー（Discord + Spec PR）
+    ↓
+タスク実行（pnpm task:loop）
+    ↓
+自己レビュー → PR作成（Vibe-Kanban）
+    ↓
+コードレビュー（GitHub PR）
+    ↓
+マージ → 次タスク自動開始
+```
+
+---
+
+## 開発フロー全体図
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ Phase A: 仕様書作成                                                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  /spec-create <タスク内容の説明またはAsanaタスクURL>                          │
+│      │                                                                       │
+│      ├── 1. （AsanaURLの場合）Asanaからタスク情報取得                         │
+│      ├── 2. GitHub Issue作成                                                 │
+│      ├── 3. requirements.md作成 → ユーザー承認 → コミット                      │
+│      ├── 4. design.md作成 → ユーザー承認 → コミット                           │
+│      ├── 5. GitHub Issueにタスク一覧記述 → ユーザー承認                        │
+│      ├── 6. issue/{番号}ブランチ作成                                         │
+│      ├── 7. 仕様書をブランチにプッシュ                                        │
+│      └── 8. Spec PR作成                                                     │
+│                                                                              │
+│  成果物:                                                                     │
+│  ├── docs/specs/issues/{カテゴリ}/issue{番号}-{機能名}/                       │
+│  │   ├── requirements.md                                                    │
+│  │   └── design.md                                                          │
+│  ├── GitHub Issue #{番号}（タスク一覧含む）                                    │
+│  └── Spec PR（仕様書レビュー用）                                              │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    ↓
+                      【Discordでスレッド作成・チームレビュー依頼】
+                                    ↓
+                          【人間が仕様書をレビュー・承認】
+                                    ↓
+                            Spec PRをマージ
+                                    ↓
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ Phase B: タスク実行（Vibe-Kanban + task:loop）                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  事前準備: npx vibe-kanban（別ターミナルで起動）                              │
+│                                                                              │
+│  pnpm task:loop <issue-number>                                              │
+│      │                                                                       │
+│      ├── 初期化: Issue取得、ブランチ作成、Vibe-Kanban接続                     │
+│      │                                                                       │
+│      └── ループ開始 ─────────────────────────────────────────┐               │
+│           │                                                   │               │
+│           ▼                                                   │               │
+│      ┌─────────────────────────────────────────────────────┐ │               │
+│      │ 着手可能なタスクグループを選定（依存関係考慮）        │ │               │
+│      └─────────────────────────────────────────────────────┘ │               │
+│           │                                                   │               │
+│           ▼                                                   │               │
+│      ┌─────────────────────────────────────────────────────┐ │               │
+│      │ Vibe-Kanbanにタスク作成 → start_task_attempt        │ │               │
+│      │ （Claude Codeが自動起動されて実装開始）              │ │               │
+│      └─────────────────────────────────────────────────────┘ │               │
+│           │                                                   │               │
+│           ▼                                                   │               │
+│      ┌─────────────────────────────────────────────────────┐ │               │
+│      │ Claude Code（自動実行）                             │ │               │
+│      │                                                      │ │               │
+│      │  task-executer: 実装                                 │ │               │
+│      │       ↓                                              │ │               │
+│      │  task-reviewer: 設計との整合性チェック（自動）        │←┤ 問題時ループ  │
+│      │       ↓                                              │ │               │
+│      │  task-qa: 動作確認（Playwright/curl）（自動）        │←┘               │
+│      │       ↓ 全テスト合格                                 │                 │
+│      │  ステータス → In Review                              │                 │
+│      └─────────────────────────────────────────────────────┘                 │
+│           │                                                                   │
+│           ▼                                                                   │
+│      【人間がVibe-Kanbanで確認】                                              │
+│      ├── 自己レビュー（実装内容確認）                                         │
+│      └── OKなら「Create PR」ボタンクリック                                    │
+│           │                                                                   │
+│           ▼                                                                   │
+│      【GitHubでPRレビュー】                                                   │
+│      ├── 担当者レビュー（動作確認 + コード確認）                               │
+│      └── 他エンジニアレビュー                                                 │
+│           │                                                                   │
+│           ▼ 承認                                                             │
+│      GitHub側でPRマージ（⚠️必ずGitHub側で操作）                               │
+│           │                                                                   │
+│           ▼                                                                   │
+│      Vibe-Kanbanがマージ検知 → タスク自動Done                                 │
+│           │                                                                   │
+│           ▼                                                                   │
+│      task:loopがDone検知 → GitHub Issueチェックボックス更新                   │
+│           │                                                                   │
+│           └──────────────────────────────────────────────────┘               │
+│                        次のタスクグループを自動開始                            │
+│                                                                              │
+│      全タスクグループ完了 → Issue Close                                       │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase A: 仕様書作成
+
+### コマンド
+
+```bash
+/spec-create <タスク内容の説明またはAsanaタスクURL>
+```
+
+### ステップ詳細
+
+| ステップ | 実行者                | 内容                                  |
+| -------- | --------------------- | ------------------------------------- |
+| 1        | Claude                | タスク情報取得（AsanaURLの場合）      |
+| 2        | Claude                | GitHub Issue作成                      |
+| 3        | Claude → **人間承認** | requirements.md作成 → 確認 → コミット |
+| 4        | Claude → **人間承認** | design.md作成 → 確認 → コミット       |
+| 5        | Claude → **人間承認** | GitHub Issueにタスク一覧記述          |
+| 6        | Claude                | `issue/{番号}`ブランチ作成            |
+| 7        | Claude                | 仕様書をブランチにプッシュ            |
+| 8        | Claude                | **Spec PR作成**                       |
+| 9        | **人間**              | Discordでチームにレビュー依頼         |
+| 10       | **人間**              | Spec PRレビュー・承認・マージ         |
+
+### 成果物
+
+```
+docs/specs/issues/{カテゴリ}/issue{番号}-{機能名}/
+├── requirements.md    # 要件定義書（ATDD形式）
+└── design.md          # 設計書（技術詳細）
+
+GitHub Issue #{番号}   # タスク一覧（Phase別チェックボックス形式）
+Spec PR                # 仕様書レビュー用
+```
+
+### 仕様書レビューの観点
+
+- **requirements.md**: 要件の妥当性、受け入れ基準の明確さ、スコープの適切さ
+- **design.md**: アーキテクチャの妥当性、既存設計との整合性、実装方針の適切さ
+- **タスク一覧**: タスク分解の粒度、依存関係の妥当性
+
+---
+
+## Phase B: タスク実行
+
+### コマンド
+
+```bash
+# 事前準備: Vibe-Kanbanを起動（別ターミナル）
+npx vibe-kanban
+
+# タスクループ開始
+pnpm task:loop <issue-number>
+```
+
+**例**:
+```bash
+pnpm task:loop 123                        # Issue #123 の全タスクを実行
+pnpm task:loop 123 --max-group 4          # Phase 4 まで実行
+pnpm task:loop 123 --max-group 4.2        # タスクグループ 4.2 まで実行
+pnpm task:loop 123 --branch develop       # develop ブランチベースで実行
+```
+
+### 実行後の流れ
+
+実行後、specで作成されたタスクが着手可能なものから自動で実行開始されます。
+
+1. **Vibe-Kanbanの画面を眺める** - タスクの進捗を確認
+2. **In Reviewになったら自己レビュー** - 実装内容を確認
+3. **OKなら「Create PR」ボタンをクリック** - PRが自動作成される
+4. **GitHubでチームレビュー** - コード確認・承認
+5. **GitHub側でPRをマージ** - ⚠️ 必ずGitHub側で操作
+6. **次のタスクが自動開始** - マージ検知で自動的に次へ（少しラグあり）
+
+### Vibe-Kanban画面での操作
+
+| 操作 | タイミング | 説明 |
+|------|-----------|------|
+| **タスク進捗確認** | 随時 | Todo → In Progress → In Review → Done の流れを確認 |
+| **Create PR** | In Review 時 | ボタンをクリックして PR を自動作成 |
+| **レビュー** | PR 作成後 | GitHub で PR の内容を確認 |
+| **マージ** | レビュー完了後 | GitHub で PR をマージ（⚠️ 必ず GitHub 側で操作） |
+
+### サブエージェントの役割
+
+| サブエージェント | 役割                           | 従来の開発フローとの対応   |
+| ---------------- | ------------------------------ | -------------------------- |
+| task-executer    | 実装                           | 実装者による実装           |
+| task-reviewer    | 設計との整合性チェック         | 実装者によるセルフレビュー |
+| task-qa          | 動作確認（Playwright/curl）    | 実装者による動作確認       |
+
+### 品質保証ループ
+
+`task-reviewer`または`task-qa`で問題が発見された場合、自動的に`task-executer`に戻って修正が行われます。
+
+```
+task-executer → task-reviewer → task-qa → In Review
+      ↑              │              │
+      └──────────────┴──────────────┘
+           問題発見時は自動ループ
+```
+
+### マージ後の自動処理
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  PR マージ（GitHub側で操作）                                │
+│      ↓                                                      │
+│  Vibe-Kanban: タスク → Done（自動検知）                    │
+│      ↓                                                      │
+│  task:loop: Done 検知（15秒ポーリング）                     │
+│      ↓                                                      │
+│  GitHub Issue: チェックボックス更新（自動）                 │
+│      ↓                                                      │
+│  次のタスクが自動開始                                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## PRの種類
+
+本ワークフローでは2種類のPRが作成されます。
+
+| PRの種類    | 作成タイミング       | 内容                       | レビュー観点                                   |
+| ----------- | -------------------- | -------------------------- | ---------------------------------------------- |
+| **Spec PR** | `/spec-create`完了時 | requirements.md, design.md | 要件の妥当性、設計の適切さ、スコープの確認     |
+| **実装PR**  | タスクグループ完了時（Vibe-KanbanでCreate PR） | ソースコード、テスト       | コード品質、設計書との整合性、テストカバレッジ |
+
+### なぜ2段階でPRを作成するのか
+
+1. **仕様書に問題があると、実装後に大きな手戻りが発生する**
+2. **実装前に他のエンジニアの視点で設計の妥当性を確認できる**
+3. **「Spec PR」と「実装PR」を分けることで、レビューの焦点が明確になる**
+
+---
+
+## 人間の関与ポイント
+
+### 仕様書作成フェーズ
+
+- **requirements.md承認**: 要件の過不足、受け入れ基準の明確性を確認
+- **design.md承認**: アーキテクチャの妥当性、実装方針を確認
+- **タスク一覧承認**: タスク分解の粒度、依存関係の妥当性を確認
+- **Discordレビュー依頼**: チームにスレッドを作成してレビュー依頼
+- **Spec PRレビュー**: 仕様書全体のレビュー・承認
+
+### タスク実行フェーズ
+
+- **自己レビュー**: Vibe-KanbanでIn Reviewになったタスクの実装内容確認
+- **Create PRクリック**: 自己レビューOKならPR作成
+- **実装PRレビュー**: 担当者レビュー → 他エンジニアレビュー → 承認 → マージ
+
+### Claudeのセルフチェックについて
+
+`task-reviewer`と`task-qa`は、従来の開発フローにおける「実装者によるセルフチェック」に相当します。
+
+| 従来（人間が実装） | 現在（Claudeが実装） |
+|------------------|-------------------|
+| 実装者がセルフチェック | `task-reviewer` + `task-qa` がセルフチェック |
+| セルフチェック後にPR作成 | セルフチェック後にIn Review → 人間がCreate PR |
+| 他のエンジニアがPRレビュー | 人間（担当者 + 他エンジニア）がPRレビュー |
+
+---
+
+## コマンドリファレンス
+
+### 仕様書作成
+
+```bash
+# タスク内容の説明から仕様書を作成
+/spec-create <タスク内容の説明>
+
+# AsanaタスクURLから仕様書を作成
+/spec-create <AsanaタスクURL>
+
+# 既存仕様書のパスを指定して修正
+/spec-create <タスク内容> <既存仕様書パス>
+```
+
+### タスク実行
+
+```bash
+# 自動ループ実行（推奨）
+pnpm task:loop <issue-number>
+
+# オプション指定
+pnpm task:loop <issue-number> --max-group <number> --branch <branch>
+
+# 例
+pnpm task:loop 123                        # Issue #123 の全タスクを実行
+pnpm task:loop 123 --max-group 4          # Phase 4 まで実行
+pnpm task:loop 123 --max-group 4.2        # タスクグループ 4.2 まで実行
+
+# 単一タスクグループ実行（品質重視・複雑な実装向け）
+/task-exec #<issue_number> <task_group_number>
+
+# 例
+/task-exec #123 1.1                 # Issue #123 のタスクグループ 1.1 を実行
+```
+
+### `/task-exec` と `pnpm task:loop` の使い分け
+
+| コマンド | 用途 | 品質保証 | 推奨シーン |
+|---------|------|---------|----------|
+| **`/task-exec`** | 重要タスクの確実な完了 | ✅ 合格まで自動ループ | 複雑な実装、品質重視 |
+| **`pnpm task:loop`** | 大量タスクの自動消化 | 並列実行・監視 | 定型作業、並行開発 |
+
+---
+
+## 関連ドキュメント
+
+- [タスク管理ガイドライン](task-management.md) - タスク階層、粒度基準、GitHub Issue管理
+- [task:loop詳細ガイド](../instructions/task-vibe-kanban-loop.md) - task:loopの詳細な使い方
+- [ブランチ戦略](branch-strategy.md) - ブランチ運用ルール
+- [コードレビューガイドライン](development/review-guidelines.md) - 品質基準とチェックリスト
+
+---
+
+## FAQ
+
+### Q: Spec PRをマージする前にタスク実行を開始できますか？
+
+**A: 推奨しません。** 仕様書に問題があると実装後に大きな手戻りが発生します。必ず仕様書レビューを完了してからタスク実行を開始してください。
+
+### Q: task-qaで行われる動作確認は何をチェックしていますか？
+
+**A:** requirements.mdの受け入れ条件に基づいて、Playwright MCP（画面テスト）やcurl（APIテスト）で実際に動作確認を行います。
+
+### Q: 人間によるQAテストは必要ですか？
+
+**A:** Claudeの`task-qa`がセルフチェックとして動作確認を行いますが、PRレビュー時に担当者が追加の動作確認を行うことを推奨します。特に重要な機能や複雑なUIについては、人間による確認が有効です。
+
+### Q: タスクグループの粒度はどのように決まりますか？
+
+**A:** [タスク管理ガイドライン](task-management.md)を参照してください。基本的には「1つの受け入れ条件を満たす」「1PR・1デプロイ・1QAテスト対象として適切（1-4時間）」が目安です。
+
+### Q: PRのマージはどこで行いますか？
+
+**A:** 必ず**GitHub側**でマージしてください。Vibe-Kanbanがマージを検知して自動的にタスクをDoneに変更し、task:loopが次のタスクを開始します。
+
+### Q: タスクがIn Reviewのまま進まない場合は？
+
+**A:**
+1. Vibe-Kanbanで「Create PR」をクリックしてPRを作成
+2. GitHubでPRをレビュー・マージ
+
+PRがマージされるとタスクは自動的にDoneになります。
+
+---
+
+## エージェント追加時のチェックリスト
+
+新しいサブエージェントを追加する際は、以下の項目を必ず確認すること。
+
+### 必須項目
+
+- [ ] **エージェント定義ファイル**（`.claude/agents/einja/{category}/{name}.md`）を作成
+  - [ ] `name`, `description`, `model`, `color` のメタデータを設定
+  - [ ] 役割・責務を明記
+  - [ ] 処理フローを記載
+  - [ ] **出力形式セクションを追加**（CLAUDE.mdの標準構造に準拠）
+
+- [ ] **出力形式の統一**
+  - [ ] `## [絵文字] [フェーズ名]完了` の形式でヘッダー
+  - [ ] `### タスク:` でタスク識別情報
+  - [ ] `### [メイン結果]:` でステータス（SUCCESS/FAILURE/PARTIAL）
+  - [ ] `### サマリー` で主要結果
+  - [ ] `### 次のステップ` で後続処理説明
+
+- [ ] **親エージェントとの連携**
+  - [ ] 呼び出し元（前提エージェント）を明記
+  - [ ] 後続エージェントを明記
+  - [ ] 差し戻し先（該当する場合）を明記
+
+### 推奨項目
+
+- [ ] **エラーハンドリング**
+  - [ ] 想定されるエラーパターンを列挙
+  - [ ] 各エラーに対する対処方法を記載
+
+- [ ] **AskUserQuestion使用箇所**
+  - [ ] ユーザー確認が必要な判断ポイントを明記
+
+### 出力形式テンプレート
+
+```markdown
+## 出力形式
+
+処理完了後、以下の形式で報告を出力すること：
+
+\`\`\`markdown
+## [絵文字] [フェーズ名]完了
+
+### タスク: [タスクID] - [タスク名]
+
+### [メイン結果]: [✅ SUCCESS / ❌ FAILURE / ⚠️ PARTIAL]
+
+### サマリー
+[主要な結果・数値]
+
+### 詳細
+[項目別の詳細情報]
+
+### 次のステップ
+[後続処理の説明]
+\`\`\`
+```