Issue実装フロー（自動ワークフロー）

概要

GitHub Issueを受け取り、計画→サブエージェントレビュー→実装を自動化するワークフロー。 usaconプロジェクトのルール（staging経由、クアドレビュー等）に準拠する。

注: プランモード（EnterPlanMode）はTaskツールが使えないため使用しない。 代わりに同等の計画フェーズを手動で実行し、サブエージェントレビューをシームレスに統合する。

フロー全体図

Issue番号を受け取る
  ↓
① Issue詳細を取得（gh issue view）
  ↓
② コードベース調査 → 実装計画を作成
  ↓
③ サブエージェントでプランレビュー（設計妥当性＋影響範囲）
  ↓
④ レビュー結果を反映 → ユーザーに提示・承認取得
  ↓
⑤ 実装開始（usaconルールに準拠）
  ↓
⑥ staging E2Eテスト成功 → Issueクローズ → main マージ

ステップ詳細

ステップ①: Issue詳細の取得

# Issue内容を取得
cd <プロジェクトディレクトリ>
gh issue view <issue番号> --json title,body,labels,assignees,milestone

# 関連PRの確認（既に作業中でないか）
gh pr list --search "linked:issue/<issue番号>"

# オープン中のPRとの修正ファイル重複確認
gh pr list --state open

取得する情報:

• タイトルと本文（要件の把握）
• ラベル（feature / bug / improvement の分類）
• マイルストーン（リリース計画）
• 関連PR（既存作業との重複チェック）

ステップ②: コードベース調査 → 実装計画の作成

必須: design-review-checklist スキルの Phase 1（設計前の既存コード調査）を実行すること。 Issue #723 で11回レビュー・41件指摘の73%が「既存コード調査不足」と「経路の網羅性不足」だった教訓に基づく。 特に以下を徹底する:

• 全データ更新経路（SSE・ポーリング・REST同期・確認必須）の洗い出し
• SSE/APIイベントの実際のペイロード構造をソースコードで確認
• 既存の TypeScript 型定義との整合性確認
• 既存CSSのグローバルルール（!important）との競合チェック
• モバイル/レスポンシブの既存分岐ロジック確認

Glob、Grep、Readツールを使ってコードベースを徹底調査し、実装計画を作成する。

調査すべき項目:

1. Issue要件に関連する既存ファイルの特定
2. 類似機能の実装パターンの確認
3. DB変更が必要かの判断
4. 影響を受ける既存機能の洗い出し
5. 全データ更新経路の洗い出し（SSE・ポーリング・REST等）
6. 既存の型定義・CSSルールとの競合確認
7. AIアシスタント経路の乖離チェック（該当時のみ）
8. フォールバック値でのDB保存の有無確認

計画の構成（この形式で記述）:

## 📋 実装プラン: Issue #XX - タイトル

### Issue概要
- Issue #XX: タイトル
- 分類: feature / fix / improvement
- 要件の要約

### 影響範囲分析
- **変更対象ファイル一覧**（パスと変更内容を列挙）
- **影響を受ける既存機能**
- **DB変更の有無**: あり/なし
  - マイグレーション内容
  - RLSポリシーの変更
  - 型再生成の必要性

### 実装方針
- アプローチの説明
- 選択した設計の理由
- 代替案と不採用理由（検討した場合）

### 実装ステップ
1. ステップ1: 具体的な作業内容
2. ステップ2: 具体的な作業内容
3. ...

### AIアシスタント経路チェック（該当する場合のみ）

> **Issue #1092/#1090教訓**: AIアシスタント経由の操作と通常UIの操作でデータ完全性に乖離が発生。通常UIが4テーブルから並列取得するのに対し、AIアシスタント用サービスが1テーブルのみクエリしていた。

AIアシスタントに関連する変更の場合、以下を確認:
- [ ] 通常UIの同等機能のデータフローを確認したか
- [ ] 通常UIが参照するテーブルを全て網羅しているか
- [ ] NOT NULL制約のあるカラムに対して、フォールバック値ではなく実データを保存しているか
- [ ] API呼び出し失敗時に「静かな劣化」ではなく「明示的なエラー」になっているか

### リスク・注意点
- 考慮すべきエッジケース
- 破壊的変更の有無
- 既存テストへの影響

ステップ③: サブエージェントによるプランレビュー（軽量・埋め込み方式）

計画作成後、Taskツールでサブエージェントを起動してレビューする。

トークン節約の原則:

• 計画内容と関連コードの抜粋をプロンプトに直接埋め込む
• サブエージェントが自らファイルを読みに行く必要がないようにする
• サブエージェントにはGlob/Grep/Readを使わせない（データは全てプロンプト内に含める）

レビュー起動方法:

Task tool (subagent_type: general-purpose):
  description: "実装プランレビュー"
  prompt: |
    以下の実装プランをレビューしてください。
    必要な情報はすべてこのプロンプト内に含まれています。
    コードベースの探索は不要です。

    【レビュー観点】
    1. アプローチはIssue要件を満たしているか
    2. 既存アーキテクチャと整合しているか
    3. 変更対象ファイルに漏れはないか
    4. オーバーエンジニアリングになっていないか
    5. DB変更がある場合: マイグレーション・RLS・型生成は適切か

    【出力形式】
    各観点: ✅問題なし / ⚠️要検討（提案付き） / ❌要修正（修正案付き）
    最後に「総合評価」を1行で記載。
    軽微なスタイル指摘は不要。

    <プラン内容>
    {ステップ②で作成した計画をここに埋め込む}
    </プラン内容>

    <関連コード抜粋>
    {メインエージェントがReadで取得した変更対象ファイルの該当部分を埋め込む}
    </関連コード抜粋>

メインエージェントの責務: ステップ②の調査時にReadで読んだコードの中から、 変更対象の関数・コンポーネントの該当箇所のみを抜粋してプロンプトに含める。 ファイル全体ではなく、変更に関係する部分だけを渡す。

ステップ③-escalated: 大規模変更時の多段レビュー（6+1構成）

教訓（Issue #1515→#1534）: 設計レビューと実装安全性レビューは異なる視点。設計レビュー（6エージェント）ではSDK互換性・仕様差異・設計漏れを検出できたが、実装安全性レビュー（Codex）で初めて「型変更の波及」「空配列truthyの罠」「文字列前提結合」が発覚した。2段構えで初めてA+判定に到達。

エスカレーション基準（以下のいずれかに該当する場合、多段レビューを実施）:

• 変更ファイルが6個以上
• 関数シグネチャ・戻り値の型変更を含む（波及箇所の網羅が必要）
• 複数のデータ経路（SSE・ポーリング・REST等）に跨る変更
• 外部SDK/APIの新規導入や大幅なバージョン変更

該当しない場合: 通常の1エージェントレビュー（上記ステップ③）で十分。

Phase 1: 設計レビュー（6エージェント並列）

各エージェントには計画内容 + 関連コード抜粋をプロンプトに埋め込む（差分埋め込み方式）。

Phase 2: 実装安全性レビュー（Codex 1エージェント）

Phase 1で得た全情報をプロンプトに含め、Codexに「この計画を実装して何が壊れるか」を検証させる。

• 変更する引数/戻り値の型が変わる場合、その値を使う全ファイルを網羅的に走査
• JavaScriptの || 短絡評価で空配列 [] がtruthy → フォールバックに到達しない問題
• 文字列前提で .concat() / テンプレートリテラルを使う箇所に配列が渡される問題

統合

• Phase 1の6エージェント結果をCRITICAL/BLOCKER/HIGH/MEDIUM/LOWで分類
• Phase 2のCodex結果を統合
• 全指摘をIssueコメントに投稿

実績（Issue #1515→#1534）: 総トークン557,894、ツール使用182回、検出12件（CRITICAL 3, BLOCKER 1, HIGH 4, MEDIUM 4）、所要時間約20分

ステップ③b: 計画投稿後のplannedラベル適用（必須）

実装計画をIssueコメントとして投稿した場合は、必ず planned ラベルを適用する:

gh issue edit <番号> --add-label planned

教訓#6: 計画投稿後にラベル適用を忘れると、issue-plannerが同じIssueを再度計画対象として処理してしまう。

ステップ④: レビュー結果の反映とユーザー承認

1. サブエージェントのレビュー結果を受け取る
2. ❌（要修正） の指摘があれば計画を修正
3. 修正後、再度サブエージェントレビューが必要か判断
4. レビュー結果と最終計画をユーザーに提示

ユーザーへの報告形式:

📋 実装プラン: Issue #XX - タイトル

[計画の概要を簡潔に説明]

🔍 サブエージェントレビュー結果:
  設計の妥当性: ✅/⚠️/❌ [コメント]
  影響範囲:     ✅/⚠️/❌ [コメント]

⚠️ 要検討事項:（ある場合）
  - [指摘内容と対応方針]

承認いただければ実装を開始します。

ユーザーの応答に応じた対応:

• 承認: ステップ⑤へ進む
• 修正指示: 計画を修正し、必要に応じて再レビュー
• 却下: 理由を確認し、別アプローチを検討

ステップ⑤: 実装

ユーザー承認後、計画に沿って実装を開始する。

usaconプロジェクトの場合、以下に従う:

• ブランチ作成: feat/issue-XX-簡潔な説明 または fix/issue-XX-簡潔な説明
• staging経由のフロー（usacon SKILL.md参照）
• PR作成前の品質ゲート（以下を順次実行）:
  • Lintチェック（npm run lint && npm run type-check）
  • Codex final-check: codexスキルの「final-check」に従い、workspace-writeで軽微修正を自動適用。修正後にLint/型チェック再確認。タイムアウト・失敗時はスキップ
  • ビルド確認（cd frontend && npx vite build）
  • CLI変更を含む場合の追加ゲート:
    • グローバルビルド確認（npm run build）: app-core → api-client → usacon-cli の依存順でビルドが通ること
    • 実機起動確認（usacon <対象コマンド>）: ビルド後に実際のCLIコマンドが起動・実行できること
• 実装完了後のクアドレビュー（/sub-review + Codex差分レビュー + /code-review + CodeRabbit）
  • Phase 1（hard gate）: /sub-review（4エージェント + 信頼度スコアリング）+ Codex差分 = 5レーン
  • Phase 2（soft gate）: /code-review（公式プラグイン → GitHub PRコメント投稿）。失敗時はPhase 1のみで続行
  • CodeRabbitは自動起動。PRコメント内容を必ず確認
  • 詳細は usacon/references/quad-review.md 参照
• changelog.ts の更新（サブエージェントで自動化）
• E2Eテストの実施

UI入力欄修正時のE2Eテスト項目（必須）

UI入力欄（textarea / input）の修正を含むIssueの場合、以下をE2Eテスト項目に含めること:

• Shift+Enter改行: 改行が正しく挿入されるか（意図しないフォーム送信が起きないか）
• 2行目左端揃え: 改行後のテキストが左端から始まるか（不要なインデントが入らないか）
• IME動作: 日本語入力のIME確定時にEnterが送信トリガーにならないか

これらはブラウザ・OS依存のバグが発生しやすい箇所であり、目視確認だけでなくPlaywright操作での検証を推奨する。

ブランチ差異防止:

• Issue着手前チェック（main/staging差分確認）を必ず実施
• PRのベースブランチは原則 staging

worktree使用時の追加注意:

• worktreeを使用する場合、Issue着手前チェックに加えて、ベースブランチの最新化が必須
• EnterWorktree はHEADからworktreeを作成するため、別featureブランチにいると古いベースで作業してしまう
• 必ず git checkout $baseBranch && git pull origin $baseBranch してからworktreeを作成すること
• 詳細は git-worktree スキルの「単独worktree使用時の必須手順」セクション参照

ステップ⑥: E2Eテスト成功後のIssueクローズ

stagingデプロイ後のE2Eテストが成功したら、## E2E結果 コメントと ## クローズ根拠 コメントを投稿したうえで、Issueをクローズする。

# 1. E2E結果コメントを投稿
gh issue comment <issue番号> --body "$(cat <<'EOF'
## E2E結果

- 対象PR: #<PR番号>
- 実施環境: staging / preview
- テスト項目:
  - T1: PASS/FAIL - （確認内容）
  - T2: PASS/FAIL - （確認内容）

### 自信ゲート（テスト品質チェック）
| # | チェック項目 | 結果 | 詳細 |
|---|------------|------|------|
| C1 | 修正対象の機能を直接操作したか？ | ✅/❌ | （具体的な操作内容） |
| C2 | ユーザーとしてこのアプリを渡されて使えるか？ | ✅/❌ | （確認した操作フロー） |
| C3 | テスト計画の全項目にPASS/FAIL/SKIPが記入されているか？ | ✅/❌ | （例: T1〜T5全てPASS） |
| C4 | 「ビルド成功」「テスト通過」だけで判断していないか？ | ✅/❌ | （実動作で確認した内容） |
| C5 | 修正前に壊れていた操作が修正後に正しく動くことを確認したか？ | ✅/❌ | （修正前→後の差分） |
EOF
)"

# 2. クローズ根拠コメントを投稿
gh issue comment <issue番号> --body "$(cat <<'EOF'
## クローズ根拠

- 対象PR: #<PR番号>
- E2E PASS確認: stagingで全項目PASS
- 環境での動作確認サマリ: （画面/操作/主要確認結果）
EOF
)"

# 3. 上記コメント投稿後にIssueをクローズ
gh issue close <issue番号> --comment "$(cat <<'EOF'
✅ `## E2E結果` と `## クローズ根拠` を投稿済み。preview環境（staging）で動作確認済み。PR #<PR番号>
EOF
)"

重要: 自信ゲートに1つでも❌がある場合、追加テストを実施してからクローズすること。

注意: Issueクローズはstaging E2E成功後、main マージ前に行う。 コミットメッセージの Closes #XX による自動クローズは使用しない（E2E確認前にクローズされるのを防ぐため）。

完了条件（implementedラベル付与の前提）

implemented ラベルの付与だけで完了扱いにしてはならない。以下をすべて満たすこと:

1. E2E結果コメント: Issueコメントに ## E2E結果 セクションが存在し、テスト項目・PASS/FAIL・自信ゲート回答が記載されていること
2. クローズ根拠コメント: Issueコメントに ## クローズ根拠 セクションが存在し、PR番号・E2E PASS確認・環境での動作確認サマリが記載されていること
3. ラベル状態: implementing -> implemented のラベル遷移が完了していること
4. Issueクローズ: gh issue close が上記1-3完了後に実行されていること

注意: ラベル遷移とIssueクローズは、E2E結果・クローズ根拠のコメント投稿が完了してから行うこと。

注意事項

• Issue番号が未指定の場合: ユーザーにIssue番号を確認する
• 複数Issueの同時実施: 1つずつ順番に実施する
• レビューで❌が見つかった場合: 計画を修正してから実装に進む（再レビューは修正規模に応じて判断）
• usaconプロジェクト以外: usacon固有チェック（staging経由、Stripe連携等）をスキップし、汎用的な設計レビューのみ実施

⚠️ 無関係なPRのマージ禁止（Issue #925教訓）

Issue実装中に、別Issueに属するPRをコンテキスト確認なしにマージしてはならない。 Issue #925作業中に無関係なIssue #729のPRを一括マージし、ビルドエラーが発生した教訓に基づく。

• PRマージ指示を受けた場合、そのPRが現在作業中のIssueに関連しているかを必ず確認する
• 無関係なPRの場合:

  「このPR #XXX はIssue #YYY のPRですが、現在のIssue #ZZZ とは別件です。マージしてよいですか？」

  とユーザーに確認してから進める
• CodeRabbitレビュー通過 ≠ マージ承認（静的解析の結果であり、作業コンテキストの妥当性は判断していない）
• 異なるIssueのPRを一括マージしない（各PRは独自のE2Eテストサイクルを経ること）

関連スキル

• usacon - プロジェクト全体のガイド（staging運用、実装チェックリスト）
• pr-flow - PR作成からマージまでの完全フロー
• codex - Codex差分レビュー（クアドレビューの一環）
• codex-autopilot - Codex自動運転モード（ユーザー承認をCodexに委任）
• /autopilot-issue - 自律Issue実装コマンド（サブエージェントでコンテキスト分離 + Codex自動運転）
• github-cli - GitHub CLI操作
• issue-planner - 全オープンIssueの一括実装計画作成

改訂履歴