OpenSkillIndex← back to search
claude-codeautomation

Claude-skill-registry github-issue-state-management

GitHub Issueのラベルとメタデータを使用した環境状態管理。container-use/worktree/ホスト環境すべてからアクセス可能なSingle Source of Truth

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/github-issue-state-management" ~/.claude/skills/majiayu000-claude-skill-registry-github-issue-state-management && rm -rf "$T"
manifest: skills/data/github-issue-state-management/SKILL.md
tags
#github#issue-tracking#automation#metadata#cli#state-management
source content

GitHub Issue 状態管理

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

概要

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

課題（ローカルファイル）解決策（GitHub Issue）
container-use内からホストファイルにアクセス不可
gh
CLI はどこからでも使用可能
worktree間でファイル共有不可Issue は全環境で同一
並列実行時の競合リスクラベル操作は GitHub がアトミック処理
ローカルファイルのため可視性が低いGitHub UI で状態が一目瞭然

ラベル体系

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

ラベル説明色（推奨）
env:active
作業中
#0E8A16
(緑)
env:blocked
人間の介入が必要
#D93F0B
(赤)
env:pr-created
PR作成済み
#1D76DB
(青)
env:merged
マージ完了
#6F42C1
(紫)

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

ラベル説明
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 Body へのメタデータ埋め込み

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

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

フィールド定義

フィールド型必須説明
env_id
string✅container-use 環境ID または worktree 識別子
branch
string✅Git ブランチ名
env_type
string✅
container-use
/ 
worktree
/ 
host
worktree_path
stringworktree 使用時のパス
pr_number
stringPR作成後に設定（途中再開時の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 コメント形式

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

## Blocked: [reason_code]

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

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

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

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

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

Blocked Reason コード

Reason説明推奨アクション
design_ambiguity
設計書実現性チェックNG設計書修正
review_loop_exceeded
レビュー3回失敗設計書見直し
dependency_missing
依存Subtask未完了依存解決待ち
external_blocker
外部要因（API未提供等）人間エスカレーション
resource_limit
環境リソース不足Docker cleanup
ci_persistent_failure
CI 3回連続失敗手動調査必要

API 操作

主要関数（CLI ラッパー）

関数用途コマンド例
register_env
環境開始時に登録
issue-state.sh register 42 abc-123 feature/auth container-use
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 コマンド

# 環境登録（ラベル追加）
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)

トリガーアクションラベル操作
環境作成開始ラベル追加 + メタデータ埋め込み
+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:*
ラベルを削除

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

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": "container-use",
  "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責任
container-worker
作業完了後、自身で 
phase
ラベルを更新可能
Main agent (Sisyphus)複数 Issue を並列処理する場合、各 Issue を独立して管理

競合回避:

  • 同一 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 .opencode/skill/github-issue-state-management/scripts/issue-state.sh <command> [args...]
コマンド説明使用例
register
環境を登録
issue-state.sh register 42 abc-123 feature/auth container-use
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-171.0.0初版作成