dmux-workflows

name	dmux-workflows
description	dmux(AI 에이전트용 tmux 창 관리자)를 사용한 다중 에이전트 오케스트레이션. Claude Code, Codex, OpenCode 및 기타 하네스 전반에 걸친 병렬 에이전트 워크플로우 패턴. 여러 에이전트 세션을 병렬로 실행하거나 다중 에이전트 개발 워크플로우를 조정할 때 사용하세요.
origin	ECC

dmux 워크플로우 (dmux Workflows)

에이전트 하네스용 tmux 창 관리자인 dmux를 사용하여 병렬 AI 에이전트 세션을 오케스트레이션합니다.

활성화 시점

• 여러 에이전트 세션을 병렬로 실행할 때
• Claude Code, Codex 및 기타 하네스 간의 작업을 조정할 때
• 분할 정복(divide-and-conquer) 방식의 병렬 처리가 도움이 되는 복잡한 작업 시
• 사용자가 "병렬로 실행해 줘", "이 작업을 나눠 줘", "dmux 사용해", 또는 "다중 에이전트"라고 말할 때

dmux란 무엇인가

dmux는 AI 에이전트 창(pane)을 관리하는 tmux 기반 오케스트레이션 도구입니다:

• n을 눌러 프롬프트와 함께 새 창 생성
• m을 눌러 창의 출력을 메인 세션으로 병합
• 지원: Claude Code, Codex, OpenCode, Cline, Gemini, Qwen

설치: 패키지 검토 후 해당 저장소에서 dmux를 설치하세요. github.com/standardagents/dmux 참조.

빠른 시작

# dmux 세션 시작
dmux

# 에이전트 창 생성 (dmux에서 'n'을 누른 후 프롬프트 입력)
# 창 1: "src/auth/에 인증 미들웨어를 구현해 줘"
# 창 2: "사용자 서비스용 테스트를 작성해 줘"
# 창 3: "API 문서를 업데이트해 줘"

# 각 창은 자체 에이전트 세션을 실행합니다.
# 'm'을 눌러 결과를 다시 병합합니다.

워크플로우 패턴

패턴 1: 조사 + 구현 (Research + Implement)

조사와 구현을 병렬 트랙으로 나눕니다:

창 1 (조사): "Node.js에서의 속도 제한(rate limiting) 모범 사례를 조사해 줘.
  현재 라이브러리들을 확인하고 방식을 비교해서 결과를
  /tmp/rate-limit-research.md에 작성해 줘."

창 2 (구현): "우리 Express API를 위한 속도 제한 미들웨어를 구현해 줘.
  기본적인 토큰 버킷 방식으로 시작해. 조사가 완료되면 세부 조정할 거야."

# 창 1이 완료된 후, 조사 결과를 창 2의 컨텍스트로 병합합니다.

패턴 2: 다중 파일 기능 (Multi-File Feature)

독립적인 파일들에 걸쳐 작업을 병렬화합니다:

창 1: "빌링 기능을 위한 데이터베이스 스키마와 마이그레이션을 생성해 줘"
창 2: "src/api/billing/에 빌링 API 엔드포인트를 구축해 줘"
창 3: "빌링 대시보드 UI 컴포넌트를 생성해 줘"

# 모두 병합한 다음, 메인 창에서 통합 작업을 수행합니다.

패턴 3: 테스트 + 수정 루프 (Test + Fix Loop)

한 창에서 테스트를 실행하고 다른 창에서 수정합니다:

창 1 (감시자): "테스트 스위트를 감시(watch) 모드로 실행해. 테스트가 실패하면
  실패 내용을 요약해 줘."

창 2 (수정자): "창 1의 에러 출력을 바탕으로 실패한 테스트를 수정해 줘"

패턴 4: 크로스 하네스 (Cross-Harness)

작업별로 다른 AI 도구를 사용합니다:

창 1 (Claude Code): "인증 모듈의 보안을 검토해 줘"
창 2 (Codex): "성능을 위해 유틸리티 함수들을 리팩터링해 줘"
창 3 (Claude Code): "결제 플로우를 위한 E2E 테스트를 작성해 줘"

패턴 5: 코드 리뷰 파이프라인 (Code Review Pipeline)

병렬 리뷰 관점:

창 1: "src/api/의 보안 취약점을 리뷰해 줘"
창 2: "src/api/의 성능 이슈를 리뷰해 줘"
창 3: "src/api/의 테스트 커버리지 부족을 리뷰해 줘"

# 모든 리뷰를 하나의 보고서로 병합합니다.

모범 사례

1. 독립적인 작업만 병렬화. 서로의 출력에 의존하는 작업은 병렬화하지 마세요.
2. 명확한 경계. 각 창은 서로 다른 파일이나 관심사를 다뤄야 합니다.
3. 전략적 병합. 충돌을 피하기 위해 병합 전에 창의 출력을 검토하세요.
4. git worktree 사용. 파일 충돌 가능성이 높은 작업의 경우 창마다 별도의 worktree를 사용하세요.
5. 리소스 인식. 각 창은 API 토큰을 사용하므로 전체 창 개수를 5~6개 이하로 유지하세요.

Git Worktree 통합

중복되는 파일을 건드리는 작업의 경우:

# 격리를 위해 worktree 생성
git worktree add -b feat/auth ../feature-auth HEAD
git worktree add -b feat/billing ../feature-billing HEAD

# 별도의 worktree에서 에이전트 실행
# 창 1: cd ../feature-auth && claude
# 창 2: cd ../feature-billing && claude

# 완료 후 브랜치 병합
git merge feat/auth
git merge feat/billing

보완 도구

도구	역할	사용 시기
dmux	에이전트용 tmux 창 관리	병렬 에이전트 세션
Superset	10개 이상의 병렬 에이전트를 위한 터미널 IDE	대규모 오케스트레이션
Claude Code Task 도구	프로세스 내 하위 에이전트 생성	세션 내 프로그램 방식의 병렬 처리
Codex 다중 에이전트	내장 에이전트 역할	Codex 전용 병렬 작업

ECC 헬퍼 (ECC Helper)

ECC는 이제 별도의 git worktree를 사용하는 외부 tmux 창 오케스트레이션을 위한 헬퍼를 포함합니다:

node scripts/orchestrate-worktrees.js plan.json --execute

plan.json 예시:

{
  "sessionName": "skill-audit",
  "baseRef": "HEAD",
  "launcherCommand": "codex exec --cwd {worktree_path} --task-file {task_file}",
  "workers": [
    { "name": "docs-a", "task": "기술 1~4번을 수정하고 핸드오프 노트를 작성해 줘." },
    { "name": "docs-b", "task": "기술 5~8번을 수정하고 핸드오프 노트를 작성해 줘." }
  ]
}

헬퍼의 역할:

• 작업자당 하나의 브랜치 기반 git worktree 생성
• 선택적으로 메인 체크아웃의 seedPaths를 각 작업자 worktree에 덮어씌움
• 작업자별 task.md, handoff.md, status.md 파일을 .orchestration/<session>/ 아래에 생성
• 작업자당 하나의 창이 있는 tmux 세션 시작
• 각 창에서 해당 작업자 명령어 실행
• 메인 창은 오케스트레이터를 위해 비워둠

작업자가 로컬 오케스트레이션 스크립트, 초안 계획 또는 문서와 같이 아직 HEAD에 포함되지 않은 수정되거나 추적되지 않은 로컬 파일에 액세스해야 할 때 seedPaths를 사용하세요:

{
  "sessionName": "workflow-e2e",
  "seedPaths": [
    "scripts/orchestrate-worktrees.js",
    "scripts/lib/tmux-worktree-orchestrator.js",
    ".claude/plan/workflow-e2e-test.json"
  ],
  "launcherCommand": "bash {repo_root}/scripts/orchestrate-codex-worker.sh {task_file} {handoff_file} {status_file}",
  "workers": [
    { "name": "seed-check", "task": "작업 시작 전에 시드된 파일들이 있는지 확인해 줘." }
  ]
}

문제 해결

• 창이 응답하지 않음: 해당 창으로 직접 전환하거나 tmux capture-pane -pt <session>:0.<pane-index>로 검사하세요.
• 병합 충돌: 창별 파일 변경 사항을 격리하기 위해 git worktree를 사용하세요.
• 높은 토큰 사용량: 병렬 창 개수를 줄이세요. 각 창은 전체 에이전트 세션입니다.
• tmux를 찾을 수 없음: brew install tmux(macOS) 또는 apt install tmux(Linux)로 설치하세요.