Menú
GitHub Issueのラベルとメタデータを使用した環境状態管理。worktree/ホスト環境すべてからアクセス可能なSingle Source of Truth
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | github-issue-state-management |
| description | GitHub Issueのラベルとメタデータを使用した環境状態管理。worktree/ホスト環境すべてからアクセス可能なSingle Source of Truth |
Single Source of Truth: GitHub Issue のラベルとメタデータによる環境状態管理
なぜ GitHub Issue で管理するのか？
| 課題（ローカルファイル） | 解決策（GitHub Issue） |
|---|---|
| worktree間でファイル共有不可 | Issue は全環境で同一 |
| 並列実行時の競合リスク | ラベル操作は GitHub がアトミック処理 |
| ローカルファイルのため可視性が低い | GitHub UI で状態が一目瞭然 |
| ラベル | 説明 | 色（推奨） |
|---|---|---|
env:active | 作業中 | #0E8A16 (緑) |
env:blocked | 人間の介入が必要 | #D93F0B (赤) |
env:pr-created | PR作成済み | #1D76DB (青) |
env:merged | マージ完了 | #6F42C1 (紫) |
| ラベル | 説明 |
|---|---|
phase:0-branch | ブランチ作成 |
phase:1-env | 環境構築 |
phase:2-design | 設計書参照 |
phase:3-check | 設計書実現性チェック |
phase:4-red | テスト作成（Red） |
phase:5-green | 実装（Green） |
phase:6-refactor | リファクタリング |
phase:7-review | レビュー依頼/修正 |
phase:8-stress | ストレステスト（任意） |
phase:9-approval | ユーザー承認待ち |
phase:10-pr | PR作成 |
phase:11-ci | CI監視 |
phase:12-merge | マージ & クリーンアップ |
| ラベル | 説明 |
|---|---|
area:backend | バックエンド |
area:frontend | フロントエンド |
area:infra | インフラ |
area:database | データベース |
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
-->
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
env_id | string | ✅ | worktree 識別子 |
branch | string | ✅ | Git ブランチ名 |
env_type | string | ✅ | worktree / host |
worktree_path | string | worktree 使用時のパス | |
pr_number | string | PR作成後に設定（途中再開時のCI監視に必要） | |
created_at | string | ✅ | 作成日時（ISO 8601） |
last_updated_at | string | ✅ | 最終更新日時（ISO 8601） |
# Issue body からメタデータを抽出
gh issue view 42 --json body -q '.body' | \
grep -oP '(?<=<!-- ENV_METADATA)[\s\S]*?(?=-->)' | \
grep -E '^[a-z_]+:' | \
sed 's/^/ /'
Blocked 発生時は、ラベル変更と共に以下形式のコメントを追加：
## Blocked: [reason_code]
**Description**: [問題の詳細説明]
**Suggested Action**: [推奨される解決アクション]
**Context**:
- [関連情報1]
- [関連情報2]
**Blocked at**: 2026-01-17T14:00:00Z
---
> このコメントは `env:blocked` ラベルと連動しています。
> 問題解決後、ラベルを `env:active` に変更し、このコメントに「Resolved」と返信してください。
| Reason | 説明 | 推奨アクション |
|---|---|---|
design_ambiguity | 設計書実現性チェックNG | 設計書修正 |
review_loop_exceeded | レビュー3回失敗 | 設計書見直し |
dependency_missing | 依存Subtask未完了 | 依存解決待ち |
external_blocker | 外部要因（API未提供等） | 人間エスカレーション |
ci_persistent_failure | CI 3回連続失敗 | 手動調査必要 |
| 関数 | 用途 | コマンド例 |
|---|---|---|
register_env | 環境開始時に登録 | issue-state.sh register 42 abc-123 feature/auth worktree |
update_phase | Phase更新 | issue-state.sh phase 42 5-green |
set_blocked | Blocked状態に設定 | issue-state.sh block 42 design_ambiguity "設計に矛盾" |
clear_blocked | Blocked解除 | issue-state.sh unblock 42 |
get_state | 現在の状態取得 | issue-state.sh get 42 |
list_active | アクティブな環境一覧 | issue-state.sh list |
# 環境登録（ラベル追加）
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
| トリガー | アクション | ラベル操作 |
|---|---|---|
| 環境作成開始 | ラベル追加 + メタデータ埋め込み | +env:active, +phase:1-env |
| Phase 遷移 | ラベル入れ替え | -phase:X, +phase:Y |
| Blocked 発生 | ラベル変更 + コメント追加 | -env:active, +env:blocked |
| Blocked 解除 | ラベル変更 | -env:blocked, +env:active |
| PR 作成 | ラベル変更 | -env:active, +env:pr-created, +phase:10-pr |
| PR マージ | ラベル変更 | -env:pr-created, +env:merged, +phase:12-merge |
| 環境削除 | ラベル削除 | 全 env:*, phase:* ラベルを削除 |
# 復旧情報を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"
}
| ステータス | Phase | アクション | 具体的な操作 |
|---|---|---|---|
env:active | 0-branch | 環境作成 | environment_create(from_git_ref=branch) |
env:active | 1-env〜6-refactor | 環境再開 | environment_open(env_id=...) |
env:active | 7-review〜8-stress | レビュー再開 | 環境を開いてレビューループを継続 |
env:active | 9-approval | 承認待ち | ユーザーに承認ゲートを提示 |
env:active | 10-pr〜11-ci | CI監視 | gh pr checks <pr_number> |
env:blocked | - | 人間の介入 | Blockedコメント確認 → 解決 → unblock |
env:pr-created | - | PR確認 | gh pr view で状態確認 |
env:merged | - | クリーンアップ | 環境削除（残っている場合） |
| (なし) | - | 初期化 | register で環境を登録 |
# 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 に従って再開
| Actor | 責任 |
|---|---|
Sisyphus | 作業完了後、自身で phase ラベルを更新可能 |
| Main agent (Sisyphus) | 複数 Issue を並列処理する場合、各 Issue を独立して管理 |
競合回避:
リポジトリに必要なラベルを一括作成：
# ステータスラベル
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 "データベース"
使用方法:
bash .pi/skills/github-issue-state-management/scripts/issue-state.sh <command> [args...]
| コマンド | 説明 | 使用例 |
|---|---|---|
register | 環境を登録 | issue-state.sh register 42 abc-123 feature/auth worktree |
phase | Phase を更新 | issue-state.sh phase 42 5-green |
block | Blocked 状態に設定 | issue-state.sh block 42 design_ambiguity "説明" |
unblock | Blocked を解除 | issue-state.sh unblock 42 |
pr-created | PR作成済みに更新 | issue-state.sh pr-created 42 25 |
merged | マージ完了に更新 | issue-state.sh merged 42 |
get | 状態を取得 | issue-state.sh get 42 |
list | アクティブ一覧 | issue-state.sh list |
resume | 途中再開情報を取得 | issue-state.sh resume 42 |
init-labels | ラベル一括作成 | issue-state.sh init-labels |
スクリプトはネットワークエラーやGitHub APIのレート制限に対して自動リトライを行います。
| 設定 | 環境変数 | デフォルト |
|---|---|---|
| 最大リトライ回数 | MAX_RETRIES | 3 |
| リトライ間隔（秒） | RETRY_DELAY | 5 |
レート制限時: 60秒待機後にリトライ
ネットワークエラー時: RETRY_DELAY秒待機後にリトライ
# カスタムリトライ設定
MAX_RETRIES=5 RETRY_DELAY=10 bash issue-state.sh phase 42 5-green
| 違反 | 結果 |
|---|---|
| 環境開始時にラベル未追加 | FORBIDDEN - 復旧不可 |
| Phase 遷移時にラベル未更新 | FORBIDDEN - 状態不整合 |
| Blocked 時にコメント未追加 | FORBIDDEN - 理由が不明 |
| 日付 | バージョン | 変更内容 |
|---|---|---|
| 2026-01-17 | 1.0.0 | 初版作成 |
PR作成後のCI監視、失敗時の分類と対応、自動マージまでの完全なワークフローを定義
GitHub Issue間の依存関係（Is blocking / Blocked by）を設定・取得するためのAPI操作を提供
PRの作成からマージ、クリーンアップ、ロールバックまでの標準フローを定義
バージョン整合性チェック→提案→承認→GitHub Release作成までの標準リリースフロー（マルチエコシステム対応）
Git worktree を作成し、並行開発用の独立したブランチ環境を構築する。プラットフォーム固有コード開発時に使用。
GitHub REST APIのSub-issue関連バグを回避するためのGraphQL API共通処理（Sub-issue登録、エラーハンドリング）を提供