Imported from majiayu000/claude-skill-registry (skills/workflow/environments-json-management/SKILL.md). Install upstream with npx skills add majiayu000/claude-skill-registry --skill environments-json-management. Copyright stays with the author.

environments.json 管理

Single Source of Truth: container-use環境の状態管理

概要

ALL container-use operations MUST update environments.json (project root) to track Issue/PR/Environment relationships.

ファイル構造

パス

environments.json  # プロジェクトルート直下

初期化

ファイルが存在しない場合、以下の構造で作成：

{
  "environments": []
}

データ構造

{
  "env_id": "abc-123-def",
  "branch": "feature/issue-42-user-auth",
  "issue_number": 42,
  "pr_number": null,
  "title": "User authentication feature",
  "status": "active",
  "phase": 4,
  "step": "tdd-green",
  "area": "backend",
  "blocked": null,
  "pending_issues": [],
  "created_at": "2026-01-03T10:00:00Z",
  "last_used_at": "2026-01-03T15:30:00Z"
}

フィールド定義

ステータス値

Phase & Step 定義（再開ポイント）

Blocked状態の構造

{
  "blocked": {
    "reason": "design_ambiguity",
    "description": "設計書に矛盾あり。ユーザーIDの型がintかuuidか不明確",
    "blocked_at": "2026-01-03T14:00:00Z",
    "suggested_action": "バックエンド設計書の「ユーザーID」定義を統一してください",
    "context": {
      "ambiguous_points": ["ID型定義不一致", "必須フィールド欠落"]
    }
  }
}

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

API

主要関数

その他の関数（必要時のみ参照）

データ構造

{
  "environments": [{
    "issue_number": 123,
    "env_id": "uuid",
    "branch": "feature/xxx",
    "status": "active|blocked|pr_created|merged|abandoned",
    "phase": 5,
    "step": "tdd-red",
    "created_at": "ISO8601",
    "last_used_at": "ISO8601",
    "pr_number": null,
    "blocked": null,
    "pending_issues": []
  }]
}

更新タイミング

セッション復旧

作業再開時、environments.json を最優先で参照：

# 1. Read environments.json (project root)
# 2. Find entry matching the Issue number or PR number
# 3. Use the stored env_id to reopen environment

復旧判定マトリクス

Phase-based 再開ロジック

def resume_from_checkpoint(env_id: str) -> ResumeAction:
    """環境の現在Phase/Stepから再開アクションを決定"""
    env = find_environment_by_id(env_id)
    if not env:
        return ResumeAction(action="create_new")
    
    if env["status"] == "blocked":
        return ResumeAction(
            action="notify_human",
            message=f"Blocked: {env['blocked']['description']}",
            suggested_action=env["blocked"]["suggested_action"]
        )
    
    phase = env.get("phase", 0)
    step = env.get("step", "branch-create")
    
    # Phase別の再開ポイント
    RESUME_POINTS = {
        (0, "branch-create"): "create_branch",
        (1, "env-create"): "open_environment",
        (2, "design-read"): "read_design",
        (3, "design-check"): "check_design_feasibility",
        (4, "tdd-red"): "write_tests",
        (5, "tdd-green"): "implement",
        (6, "tdd-refactor"): "refactor",
        (7, "review-request"): "request_review",
        (8, "review-fix"): "fix_review_issues",
        (9, "stress-test"): "run_stress_tests",
        (10, "approval-wait"): "wait_approval",
        (11, "pr-create"): "create_pr",
        (12, "ci-watch"): "watch_ci",
        (13, "merge-cleanup"): "merge_and_cleanup",
        (14, "parent-close"): "close_parent_issue",
    }
    
    return ResumeAction(
        action=RESUME_POINTS.get((phase, step), "open_environment"),
        env_id=env_id,
        phase=phase,
        step=step,
        pending_issues=env.get("pending_issues", [])
    )

Blocked状態の検出と通知

def check_and_report_blocked() -> list[BlockedEnvironment]:
    """Blocked状態の環境を検出して報告"""
    data = load_environments()
    blocked = []
    
    for env in data["environments"]:
        if env.get("status") == "blocked":
            blocked.append(BlockedEnvironment(
                env_id=env["env_id"],
                issue_number=env["issue_number"],
                reason=env["blocked"]["reason"],
                description=env["blocked"]["description"],
                suggested_action=env["blocked"]["suggested_action"],
                blocked_at=env["blocked"]["blocked_at"]
            ))
    
    if blocked:
        print("⚠️ === BLOCKED ENVIRONMENTS ===")
        for b in blocked:
            print(f"  Issue #{b.issue_number}: {b.description}")
            print(f"    Reason: {b.reason}")
            print(f"    Suggested: {b.suggested_action}")
            print(f"    Blocked since: {b.blocked_at}")
        print("Blocked環境を確認し、問題解決後に clear_blocked() を呼び出してください。")
    
    return blocked

クリーンアップポリシー

実行方法: 環境削除には delete-environment スキルを使用してください（コンテナ・ファイル・JSONを一括削除）。

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

並列実行時のルール

理由: 並列書き込みによる競合を回避

変数命名規則

# Writing
entry = {"issue_number": issue_id, ...}

# Reading
issue_id = entry["issue_number"]

CLIスクリプト

environments.json管理の自動化スクリプト：

bash .opencode/skill/environments-json-management/scripts/env-json.sh <command> [args...]

使用例：

bash .opencode/skill/environments-json-management/scripts/env-json.sh add abc-123 42 feature/auth "User authentication"
bash .opencode/skill/environments-json-management/scripts/env-json.sh list