GantisStorm/essentials-claude-code

Claude Code의 내장 태스크 시스템 (Task System)을 활용한 루프 (Loops), 스웜 (swarms), 그리고 팀 (teams).

루프 (Loop), 스웜 (Swarm), 팀 (Team)은 세 가지 실행 모드입니다. 루프 (Loop)는 순차적으로 실행됩니다. 스웜 (Swarm)은 병렬로 서브 에이전트 (subagents)를 실행합니다. 팀 (Team)은 에이전트 팀 (Agent Teams)을 통해 공유된 계약 (contracts)을 가진 전체 Claude Code 인스턴스를 생성합니다. 이 모든 모드는 Claude의 네이티브 태스크 의존성 (task dependencies), ctrl+t 진행 상황 확인, 그리고 자동 지속성 (automatic persistence)을 사용합니다.

플랜 (Plans)은 종료 기준 (exit criteria)을 정의합니다. 루프 (Loops)는 테스트를 통과할 때까지 실행됩니다. '완료 (Done)'는 실제로 완료되었음을 의미합니다.

사용자: "인증 기능을 추가해줘"
AI: *코드를 작성함* "완료!"
사용자: *테스트 실행* — 3개 실패
...

# 옵션 A: 채팅에서 논의한 후 컨텍스트 (context)에서 실행
사용자: "이 인증 버그를 수정해야 해요..." [주고받는 논의]
사용자: /implement-loop 우리가 논의한 인증 버그를 수정해줘
...

# 설치
/plugin marketplace add GantisStorm/essentials-claude-code
/plugin install essentials@essentials-claude-code
...

외부 의존성 (external dependencies) 없음. 세 가지 모드 모두 종료 기준 (exit criteria)을 강제합니다. 스웜 (Swarm)은 기본적으로 3개의 동시 작업자 (concurrent workers)를 사용합니다. 팀 (Team)은 tmux와 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 설정이 필요합니다.

우리의 루프 (loop), 스웜 (swarm), 팀 (team) 명령어는 Claude Code의 내장 태스크 관리 시스템 (built-in Task Management System) (v2.1.19 이상)을 사용합니다.

Ralph TUI와 Beads가 원활하게 통합됩니다. 대시보드 시각화를 위해 Ralph TUI를 사용하세요. 세션 간 지속적인 태스크 추적을 위해 Beads를 사용하세요.

커뮤니티는 우회 방법을 통해 Ralph Wiggum 루프를 구축해 왔습니다:

중단 훅 (Stop hooks): 각 Claude 응답 후에 실행되는 셸 스크립트 (.sh 파일)로, 출력에서 "complete" 또는 "done"과 같은 키워드를 검색하여 루프를 계속할지 결정합니다.
외부 플랜 파일 (External plan files): Claude에 내장된 지속성 (persistence) 기능이 없었기 때문에 태스크 상태를 추적하던 마크다운 (Markdown) 파일입니다.
TodoWrite: 의존성 순서가 없는 평면적인 태스크 목록으로, 태스크가 순서와 상관없이 실행될 수 있었습니다.
새 세션 (Fresh sessions): 컨텍스트 부패 (context rot)에 대응하기 위해 새로운 대화를 시작하며, 매번 수동으로 상태를 재설정해야 했습니다.

Claude Code v2.1.19 이상은 이 모든 것을 대체하는 네이티브 도구들을 제공합니다:

기존의 임시 방편	네이티브 대체 도구	더 나은 이유
중단 후크 (shell scripts)	TaskUpdate({ status: "completed" })	외부 스크립트가 필요 없으며, 상태가 구조화된 데이터 (structured data)로 관리됨
상태 유지를 위한 외부 plan.md	~/.claude/tasks/ 저장소	컨텍스트 압축 (context compaction) 시에도 자동으로 유지됨
TodoWrite 평면 리스트	TaskUpdate({ addBlockedBy: [...] })	의존성 (dependencies)이 강제되어 작업이 순서대로 실행됨
수동 세션 조정	CLAUDE_CODE_TASK_LIST_ID 환경 변수	세션 간에 동일한 작업 목록을 유지함
단일 에이전트 (Single agent)	TaskList + 병렬 워커 (parallel workers)	여러 에이전트가 공유 상태를 통해 협업함

핵심 루프는 변하지 않습니다: 계획 (Plan) → 구현 (Implement) → 검증 (Verify) → 실패 시 루프 (Loop if fail) → 통과 시 완료 (Done when pass).

의존성 관리 (Dependency management): 작업 #3이 #1과 #2에 의해 차단(blocked)된 경우, 두 작업이 모두 완료될 때까지 실제로 시작할 수 없습니다.
시각적 진행 상황 (Visual progress): ctrl+t를 눌러 상태가 포함된 실시간 작업 트리 (task tree)를 확인하세요.
병렬 조정 (Parallel coordination): 여러 워커가 하나의 작업 목록을 공유하며 충돌이 발생하지 않습니다.
지속성 (Persistence): 컨텍스트 압축 (context compaction) 시에도 유지되며, ~/.claude/tasks/에 저장됩니다.

TaskList는 ID, 주제 (subject), 상태 (status), 그리고 차단 항목 (blockedBy)을 보여주지만, 설명 (description)은 보여주지 않습니다. 구현 세부 사항을 확인하려면 각 작업에 대해 개별적으로 TaskGet을 호출해야 합니다.

이것이 우리가 여전히 계획 파일 (plan files)을 사용하는 이유입니다. 작업 (Tasks)은 상태를 추적하고, 계획 (Plans)은 구현 세부 사항을 보유합니다.

계획 파일 (.claude/plans/) → 전체 구현 코드 (작업당 50-200+ 라인)
작업 시스템 (~/.claude/tasks/) → 상태 추적, 의존성, 병렬 조정

도구	목적
TaskCreate	주제 (subject), 설명 (description), 활성 양식 (activeForm)과 함께 작업 생성
TaskUpdate	상태 변경, 소유자 설정, blockedBy 의존성 추가
TaskGet	단 하나의 작업에 대한 전체 세부 정보 (설명 포함) 가져오기
TaskList	모든 작업 확인 (단, 주제, 상태, blockedBy만 표시)

의존성은 전체 파이프라인을 통해 흐릅니다:

계획 생성자 (Plan Creator) → 변환기 (Converter) → 실행자 (Executor)
┌──────────────┐ ┌─────────────────────────┐ ┌──────────────────────┐
│ 의존성 (Dependency) │ → │ dependsOn (prd.json) │ → │ addBlockedBy (task │
...

계획 생성자(Plan creators)는 ## Dependency Graph 테이블을 작성합니다. 컨버터(Converters)는 이를 읽어 dependsOn (prd.json) 또는 depends_on (beads)을 구축합니다. 루프/스웜(Loop/swarm) 명령은 ID 맵을 사용하여 이를 addBlockedBy로 변환합니다.

태스크 라이프사이클 (Task lifecycle): pending (대기) → (의존성이 완료될 때까지 차단됨) → in_progress (진행 중) → completed (완료)

blockedBy가 비어 있지 않은 태스크는 ctrl+t에서 차단됨 (blocked) 상태로 표시됩니다. 차단 중인 태스크가 completed로 표시되면, 차단 목록에서 자동으로 제거됩니다. blockedBy 목록이 비어 있게 되면 태스크는 준비됨 (ready) (실행 가능) 상태가 됩니다.

TaskCreate({ subject: "Set up database" }) // → task "1"
TaskCreate({ subject: "Create auth middleware" }) // → task "2"
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] }) // #2는 #1을 기다림

태스크 #2는 #1이 완료될 때까지 시작할 수 없습니다. 시스템이 이를 강제합니다.

Tasks (2 done, 1 in progress, 3 open)
✓ #1 Set up database schema
■ #2 Create auth middleware (Worker-1)
...

메인 에이전트(Main agent)는 백그라운드 에이전트(background agents)의 큐(queue)를 제어합니다:

Main: Mark #1-3 in_progress → Spawn Agent-1, Agent-2, Agent-3
↓
Main: Stop and wait — background agents notify on completion
...

각 에이전트는 하나의 태스크를 수행한 후 종료됩니다. 경합(racing)이나 무한 루프(stuck loops)는 발생하지 않습니다. 메인 에이전트는 생성 시 태스크를 in_progress로 표시하고, 반환 시 completed로 표시하며, 슬롯이 비면 큐를 다시 채웁니다.

태스크는 CLAUDE_CODE_TASK_LIST_ID를 통해 세션 간에 유지됩니다:

# 터미널 세션별
CLAUDE_CODE_TASK_LIST_ID="my-project" claude
# 또는 .claude/settings.json 내에
...

내일 새로운 세션을 시작하더라도 태스크 목록은 그대로 남아 있습니다.

워크플로우 (Workflow)	적합한 용도	컨버터 (Converter)	루프 (Loop)	스웜 (Swarm)	팀 (Team)
Simple	태스크의 80%	—	/implement-loop, /plan-loop	/implement-swarm, /plan-swarm	/implement-team, /plan-team
Tasks	prd.json 형식	/tasks-converter	/tasks-loop	/tasks-swarm	—
Beads	지속적 메모리 (Persistent memory)	/beads-converter	/beads-loop	/beads-swarm	—

**컨버터 (Converters)**는 계획을 실행 가능한 형식으로 변환합니다. /tasks-converter

dependsOn 배열이 포함된 prd.json 파일을 생성합니다. /beads-converter

epic $\rightarrow$ task 계층 구조와 depends_on을 가진 beads를 생성합니다. bd dep add를 통해 수행됩니다. 두 컨버터 모두 계획의 ## Dependency Graph 테이블을 읽어 병렬 실행 (parallel execution)을 극대화하는 의존성을 구축합니다.

**모든 방식은 Claude Code의 내장 태스크 시스템 (Task System)**을 사용하여 의존성 관리, ctrl+t 진행 상황 확인, 그리고 지속성 (persistence)을 처리합니다.

대안 실행기 (Alternative executor): Ralph TUI는 클래식한 Ralph Wiggum 루프 스타일로 Tasks/Beads를 실행합니다 (Claude Code에 네이티브 태스크 기능이 생기기 전의 커뮤니티 방식).

측면 (Aspect)	Loop	Swarm	Team
실행기 (Executor)	메인 에이전트 (포그라운드)	백그라운드 하위 에이전트 (subagents)	전체 Claude Code 인스턴스 (tmux pane)
동시성 (Concurrency)	한 번에 1개 태스크	최대 N개 태스크 (--workers)	모든 에이전트 병렬 실행
컨텍스트 (Context)	전체 대화 기록	각 에이전트는 태스크 설명만 수신	각 에이전트는 계약 (contracts) + 소유 범위 (ownership scope) 수신
통신 (Communication)	해당 없음 (단일 에이전트)	워커 (Workers) 간 격리됨	에이전트들이 리드 (lead)를 통해 서로 메시지 전달
리드 역할 (Lead role)	직접 구현	큐 관리자 (Queue manager)	계약 작성자 + 코디네이터 (코딩 없음)
사전 작업 (Pre-work)	계획 파싱, 태스크 생성	계획 파싱, 태스크 생성	계획 파싱, 계약 정의, 태스크 생성
가시성 (Visibility)	작업 실시간 확인	ctrl+t 또는 TaskList로 확인	각 에이전트가 tmux pane에서 확인 가능
최적 용도 (Best for)	순차적 태스크	독립적인 병렬 태스크	통합이 필요한 멀티 컴포넌트 빌드
태스크 시스템 (Task system)	동일	동일	동일
의존성 (Dependencies)	동일	동일	동일

세 방식 모두 의존성이 포함된 동일한 태스크 그래프를 사용합니다. Loop는 순차적으로 실행합니다. Swarm은 독립적인 병렬 작업을 위해 격리된 하위 에이전트 (subagents)를 생성합니다. Team은 사전에 통합 계약 (integration contracts)을 정의하고 서로 통신할 수 있는 전체 Claude Code 인스턴스를 생성합니다 — 컴포넌트 간에 인터페이스(프론트엔드 + 백엔드 + 데이터베이스) 합의가 필요한 경우에 사용합니다.

# 대화 컨텍스트로부터 (논의 후)
/implement-loop auth 버그 수정 # 순차적 (Sequential)
/implement-swarm API 핸들러 리팩토링 # 병렬 하위 에이전트 (Parallel subagents)
...

/plan-creator JWT 인증 (JWT authentication) 추가
/tasks-converter .claude/plans/jwt-auth-plan.md
# Claude Code의 작업 시스템 (Task System)으로 실행 (권장)
...

bd init
/plan-creator JWT 인증 (JWT authentication) 추가
/beads-converter .claude/plans/jwt-auth-plan.md
...

┌─────────────────┐
│ 소스 읽기 (Read Source) │
│ (계획/컨텍스트) (plan/context) │
│ ...

순차적 실행 (Sequential execution). 메인 에이전트가 의존성 순서에 따라 한 번에 하나의 작업을 처리합니다. 차단된 작업 (Blocked tasks)은 의존성이 완료될 때까지 대기합니다. 종료 기준 (Exit criteria)은 마지막에 검증됩니다. 모든 테스트를 통과할 때까지 루프를 반복합니다.

┌─────────────────┐
│ 소스 읽기 (Read Source) │
│ (계획/컨텍스트) (plan/context) │
│ ...

큐 기반 병렬 실행 (Queue-based parallel execution) (기본값: 3개의 워커 (workers)). 메인 에이전트가 작업을 진행 중 (in_progress)으로 표시하고 최대 N개의 백그라운드 에이전트를 생성합니다. 각 에이전트는 하나의 작업을 수행한 후 종료됩니다. 완료 알림이 오면, 메인 에이전트는 해당 작업을 완료 (completed)로 표시하고, 작업 목록 (TaskList)에서 새로 차단이 해제된 작업 (상태=pending, blockedBy가 비어 있음)을 확인하여 이를 진행 중 (in_progress)으로 표시하고 워커를 생성합니다. 의존성이 강제됩니다 — 차단된 작업은 모든 차단 요소 (blockers)가 완료될 때까지 대기합니다.

┌─────────────────┐
│ 소스 읽기 (Read Source) │
│ (계획/컨텍스트) (plan/context) │
│ ...

계약 우선 병렬 실행 (Contract-first parallel execution). 리드 에이전트 (Lead agent)가 계획을 읽고 정확한 통합 계약 (integration contracts: API URL, JSON 형태, 상태 코드, SSE 형식)을 정의한 다음, 위임 모드 (Delegate Mode)를 통해 tmux 창에 전체 Claude Code 인스턴스를 생성합니다. 각 에이전트는 자신이 생성하는 계약, 소비하는 계약, 그리고 소유권 경계 (ownership boundaries)를 전달받습니다. 에이전트들은 계약 변경 사항에 대해 리드를 통해 통신합니다. 모든 에이전트가 완료되면, 리드는 계약 차이 (contract diff) 및 엔드 투 엔드 검증 (end-to-end validation)을 실행합니다.

스웜 (Swarms)과의 주요 차이점: 스웜 워커는 격리되어 있어 서로 통신할 수 없습니다. 팀 에이전트 (Team agents)는 계약을 공유하고 리드를 통해 통신하므로, 인터페이스가 일치해야 하는 다중 컴포넌트 빌드 (multi-component builds)에 이상적입니다.

명령어	용도
/plan-creator <feature>	새로운 기능 (brownfield development)
/bug-plan-creator <error> <desc>	버그 수정, 근본 원인 분석 (root cause analysis)
/code-quality-plan-creator <files>	리팩터링 (Refactoring), 데드 코드 (dead code), 보안

세 가지 명령어 모두 동일한 구조의 계획을 생성합니다: 파일별 구현 세부 사항, ## Dependency Graph (의존성 그래프) 테이블, 그리고 종료 기준 (exit criteria). 코드 맵 (code map), 설계 문서 (design doc), 또는 기타 참조 파일을 추가 컨텍스트 (context)로 전달하십시오. 생성된 모든 계획은 어떤 컨버터 (converter)로든 전달할 수 있으며, /plan-loop, /plan-swarm, 또는 /plan-team을 통해 직접 실행할 수 있습니다.

명령어	소스
/implement-loop <task>	대화 컨텍스트 (Conversation context)
/plan-loop <plan>	계획 파일 (필수)
/tasks-loop [prd.json]	prd.json
/beads-loop [--label]	Beads DB

모든 루프(loop) 취소: /cancel-loop

명령어	소스
/implement-swarm <task>	대화 컨텍스트 (Conversation context)
/plan-swarm <plan>	계획 파일 (필수)
/tasks-swarm [prd.json]	prd.json
/beads-swarm [--epic]	Beads DB

모든 스웜(swarm) 취소: /cancel-swarm

명령어	소스
/implement-team <task>	대화 컨텍스트 (Conversation context)
/plan-team <plan>	계획 파일 (필수)

모든 팀(team) 취소: /cancel-team

필수 사항: tmux + CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
리드 (Lead)가 통합 계약 (integration contracts)을 정의하고, 위임 모드 (Delegate Mode)를 통해 tmux 창(pane)에 전체 Claude Code 인스턴스를 생성합니다. 에이전트 (Agents)들은 리드를 통해 통신합니다. Cole Medin의 build-with-agent-team 패턴을 기반으로 합니다.

명령어	출력	의존성 소스
/tasks-converter <plan>	dependsOn 배열이 포함된 prd.json	계획의 ## Dependency Graph 테이블
/beads-converter <plan>	bd dep add가 포함된 Beads 이슈	계획의 ## Dependency Graph 테이블

컨버터 (Converters)는 계획의 ## Dependency Graph를 읽어 파일→태스크/bead ID 맵을 구축하고, 파일 의존성을 태스크 의존성으로 변환합니다. 의존성 그래프가 없는 이전 버전의 계획의 경우, 파일별 Dependencies / Provides를 사용합니다.

명령 (Command)	목적 (Purpose)
/plan-schema [validate <path>]	계획 파일 형식 (Plan file format) — 섹션, 파일별 형식, 의존성 그래프 (dependency graph) 규칙
/prd-schema [validate <path>]	prd.json 스키마 (schema) — 필수 필드, 거부된 필드, 예시
/beads-schema [validate]	Beads CLI — 이슈 유형 (issue types), 상태 (statuses), 우선순위 (priorities), 명령 (commands)

빠른 참조를 위해 인자 없이 호출하십시오. 기존 파일을 스키마 (schema)에 따라 검사하려면 validate와 함께 호출하십시오.