Github Issue State Management

GitHub Issue 状態管理

Single Source of Truth: GitHub Issue のラベルとメタデータによる環境状態管理

概要

なぜ GitHub Issue で管理するのか？

ラベル体系

ステータスラベル（排他: 1つのみ）

Phase ラベル（排他: 1つのみ）

領域ラベル（任意: 複数可）

メタデータ管理

Issue Body へのメタデータ埋め込み

Issue 作成時または環境開始時に、Issue body の末尾に以下のブロックを追加：

<!-- ENV_METADATA
env_id: abc-123-def
branch: feature/issue-42-user-auth
env_type: worktree
worktree_path: .worktrees/issue-42
created_at: 2026-01-17T10:00:00Z
last_updated_at: 2026-01-17T15:30:00Z
-->

フィールド定義

メタデータの抽出

# Issue body からメタデータを抽出
gh issue view 42 --json body -q '.body' | \
  grep -oP '(?<=<!-- ENV_METADATA)[\s\S]*?(?=-->)' | \
  grep -E '^[a-z_]+:' | \
  sed 's/^/  /'

Blocked 状態の詳細記録

Blocked コメント形式

Blocked 発生時は、ラベル変更と共に以下形式のコメントを追加：

## Blocked: [reason_code]

**Description**: [問題の詳細説明]

**Suggested Action**: [推奨される解決アクション]

**Context**:
- [関連情報1]
- [関連情報2]

**Blocked at**: 2026-01-17T14:00:00Z

---
> このコメントは `env:blocked` ラベルと連動しています。
> 問題解決後、ラベルを `env:active` に変更し、このコメントに「Resolved」と返信してください。

Blocked Reason コード

API 操作

主要関数（CLI ラッパー）

直接 gh コマンド

# 環境登録（ラベル追加）
gh issue edit 42 --add-label "env:active,phase:1-env,area:backend"

# Phase 更新（ラベル入れ替え）
gh issue edit 42 --remove-label "phase:4-red" --add-label "phase:5-green"

# Blocked 設定
gh issue edit 42 --remove-label "env:active" --add-label "env:blocked"
gh issue comment 42 --body "## Blocked: design_ambiguity..."

# PR作成済みに更新
gh issue edit 42 --remove-label "env:active" --add-label "env:pr-created"

# 状態取得（JSON）
gh issue view 42 --json number,title,labels,body,comments

# アクティブな環境一覧
gh issue list --label "env:active" --json number,title,labels

# Blocked な環境一覧
gh issue list --label "env:blocked" --json number,title,labels

必須更新ポイント (NON-NEGOTIABLE)

セッション復旧（途中再開）

resume コマンド（推奨）

# 復旧情報をJSON形式で取得
bash .opencode/skill/github-issue-state-management/scripts/issue-state.sh resume 42

出力例:

{
  "issue_number": 42,
  "status": "env:active",
  "phase": "5-green",
  "env_id": "abc-123-def",
  "branch": "feature/issue-42-user-auth",
  "env_type": "worktree",
  "action": "reopen_environment",
  "command": "environment_open with env_id=abc-123-def"
}

復旧判定マトリクス

手動復旧手順（参考）

# 1. アクティブな環境を検索
gh issue list --label "env:active" --json number,title,labels

# 2. 特定 Issue の復旧情報を取得
bash .opencode/skill/github-issue-state-management/scripts/issue-state.sh resume 42

# 3. 出力された action/command に従って再開

並列実行時のルール

競合回避:

• 同一 Issue への同時編集は避ける（既存ルールと同じ）
• ラベル操作は GitHub がアトミックに処理するため、ファイルベースより安全

ラベル初期設定

リポジトリに必要なラベルを一括作成：

# ステータスラベル
gh label create "env:active" --color "0E8A16" --description "作業中"
gh label create "env:blocked" --color "D93F0B" --description "人間の介入が必要"
gh label create "env:pr-created" --color "1D76DB" --description "PR作成済み"
gh label create "env:merged" --color "6F42C1" --description "マージ完了"

# Phase ラベル
gh label create "phase:0-branch" --color "FBCA04" --description "ブランチ作成"
gh label create "phase:1-env" --color "FBCA04" --description "環境構築"
gh label create "phase:2-design" --color "FBCA04" --description "設計書参照"
gh label create "phase:3-check" --color "FBCA04" --description "設計実現性チェック"
gh label create "phase:4-red" --color "FBCA04" --description "TDD Red"
gh label create "phase:5-green" --color "FBCA04" --description "TDD Green"
gh label create "phase:6-refactor" --color "FBCA04" --description "リファクタリング"
gh label create "phase:7-review" --color "FBCA04" --description "レビュー"
gh label create "phase:8-stress" --color "FBCA04" --description "ストレステスト"
gh label create "phase:9-approval" --color "FBCA04" --description "承認待ち"
gh label create "phase:10-pr" --color "FBCA04" --description "PR作成"
gh label create "phase:11-ci" --color "FBCA04" --description "CI監視"
gh label create "phase:12-merge" --color "FBCA04" --description "マージ完了"

# 領域ラベル
gh label create "area:backend" --color "C2E0C6" --description "バックエンド"
gh label create "area:frontend" --color "C2E0C6" --description "フロントエンド"
gh label create "area:infra" --color "C2E0C6" --description "インフラ"
gh label create "area:database" --color "C2E0C6" --description "データベース"

CLI スクリプト

使用方法:

bash .pi/skills/github-issue-state-management/scripts/issue-state.sh <command> [args...]

エラーリトライ

スクリプトはネットワークエラーやGitHub APIのレート制限に対して自動リトライを行います。

レート制限時: 60秒待機後にリトライ ネットワークエラー時: RETRY_DELAY秒待機後にリトライ

# カスタムリトライ設定
MAX_RETRIES=5 RETRY_DELAY=10 bash issue-state.sh phase 42 5-green

ハードブロック (違反禁止)

変更履歴