cmux 세션 감독 프로토콜
메인 세션(감독자)이 cmux 워커 세션들에 작업을 배분하고 품질을 보장하기 위한 프로토콜.
핵심 문제: "무엇을 고쳐라"만 보내면 세션이 스킬 없이 코드 직접 수정에 돌입한다. 해결: 디스패치 시 방법론을 강제하고, 감독 루프로 이탈을 잡는다.
1. 디스패치 템플릿
cmux send로 작업을 보낼 때, 아래 6개 항목을 반드시 포함한다. 빠진 항목이 있으면 세션이 자의적으로 해석해서 스킬을 건너뛴다.
템플릿
목표: {한 줄로 뭘 해야 하는지}
방법: Skill("{스킬명}") 호출 후 진행. 스킬 없이 코드 수정 착수 금지.
판단 기준: {A면 이렇게, B면 저렇게. 판단 안 서면 A.}
검증: {완료 후 반드시 확인할 것. 실행 결과·로그·테스트 등 구체적 증거.}
보고: 완료 시 "DONE: {한 줄 결과}\n증거: {확인한 것}\n변경: {파일 목록}" 출력.
금지: 스킬 미호출 상태에서 코드 수정, "됐다" 선언 후 미검증.
예시: 파이프라인 에러 수정
목표: semiconductor_collect 파이프라인 JSONDecodeError 수정.
방법: Skill("pipeline-debug") 호출 → 진단 완료 후 Skill("error-resolve") 호출 → 수정.
판단 기준: shared 모듈 문제면 shared는 건드리지 말고 파이프라인 쪽에서 방어. 단순 파싱이면 직접 수정.
검증: python3 ~/.openclaw/workspace/scripts/pipeline/semiconductor_collect.py 실행해서 에러 없이 종료 확인.
보고: DONE 형식으로.
금지: 로그 안 보고 추측으로 수정, shared/llm.py 수정.
예시: 새 모듈 생성
목표: 채권 뉴스레터 Gmail→볼트 수집 파이프라인 신규 생성.
방법: Skill("pipeline-create") 호출 → 템플릿 따라 생성 → Skill("verification-before-completion") 호출.
판단 기준: Gmail MCP 사용 가능하면 MCP, 불가면 imaplib. shared/llm.py 호출 필요 시 기존 패턴 복사.
검증: 1회 수동 실행 → 볼트에 파일 생성 확인 → jobs.json 등록 확인.
보고: DONE 형식으로.
금지: shared 모듈 직접 수정, 검증 없이 jobs.json 등록.
예시: 버그 수정
목표: 브리핑 웹앱 스파크라인 데이터가 빈 배열로 오는 버그 수정.
방법: Skill("systematic-debugging") 호출 → 원인 특정 → 수정 → Skill("verification-before-completion") 호출.
판단 기준: API 응답 문제면 백엔드, 렌더링 문제면 프론트. 양쪽이면 API 먼저.
검증: 브라우저에서 스파크라인이 실제로 그려지는 것 확인 (스크린샷 또는 콘솔 데이터).
보고: DONE 형식으로.
금지: console.log 하나 찍고 "데이터 오는 것 확인" 수준으로 끝내기.
2. 방법론 매핑
작업 유형별로 어떤 스킬을 어떤 순서로 호출해야 하는지. 메인 세션은 디스패치 시 이 표에서 매칭해서 "방법" 필드에 넣는다.
| 작업 유형 | 1차 스킬 | 2차 스킬 | 3차 스킬 | 비고 |
|---|---|---|---|---|
| 버그/테스트 실패 | systematic-debugging | (수정 후) verification-before-completion | - | 원인 특정 없이 수정 착수 금지 |
| 파이프라인 에러 | pipeline-debug | error-resolve | verification-before-completion | 로그 먼저, 추측 수정 금지 |
| 크론/스케줄 문제 | infra-ops | error-resolve | - | jobs.json + LaunchAgent 양쪽 확인 |
| 새 모듈/파이프라인 | pipeline-create | verification-before-completion | - | 1회 수동 실행 필수 |
| 새 스킬 | skill-creator | writing-skills | verification-before-completion | 트리거 테스트 필수 |
| 코드 리뷰 | requesting-code-review | - | - | Codex review 병행 권장 |
| 복잡한 구현 (8단계+) | brainstorming | writing-plans | executing-plans | Plan Mode 강제 |
| 리팩토링 | requesting-code-review | simplify | verification-before-completion | 기존 테스트 통과 확인 |
| 투자 분석 | company-research | - | - | 4 analyst 병렬 자동 |
| 인프라 점검 | infra-ops | - | - | 읽기 전용 먼저 |
| 독립 작업 2개+ | dispatching-parallel-agents | - | verification-before-completion | 서브에이전트 병렬 |
복잡도 판단 기준
| 복잡도 | 단계 수 | 스킬 요구 | 예시 |
|---|---|---|---|
| 낮음 | 1~3 | 불필요 (바로 실행) | 오타 수정, 설정값 변경, 단일 파일 수정 |
| 중간 | 4~7 | 해당 유형 스킬 필수 | 버그 수정, 파이프라인 에러, 모듈 추가 |
| 높음 | 8+ | Plan Mode + 스킬 체인 | 아키텍처 변경, 다중 시스템 연동, 볼트 구조 개편 |
낮은 복잡도에 스킬을 강제하면 오버헤드만 늘어난다. 중간 이상에서만 스킬을 요구한다.
3. 감독 체크리스트
메인 세션이 3분 주기로 각 워커 세션 화면을 확인한다.
확인 방법
# 전체 세션 한 번에 확인 (토큰 절약)
for s in 1 2 3 4; do
echo "=== SESSION $s ==="
cmux read-screen $s 2>/dev/null | tail -30
echo ""
done
체크 항목
| # | 확인 대상 | 정상 신호 | 이상 신호 | 개입 기준 |
|---|---|---|---|---|
| 1 | 스킬 호출 | 화면에 Skill( 또는 스킬명 출현 |
바로 Edit(, Write(, Bash( 진입 |
즉시 개입 |
| 2 | 서브에이전트 | Agent 호출 또는 병렬 실행 흔적 |
단일 스레드로 순차 작업 | 4단계+ 작업만 개입 |
| 3 | 태스크 리스트 | TODO/체크리스트 사용 | 항목 없이 흐름대로 진행 | 3개+ 단계 작업만 개입 |
| 4 | 검증 단계 | verification-before-completion 호출 또는 실행 테스트 |
"수정 완료" 후 바로 DONE | 즉시 개입 |
| 5 | 텔레그램 보고 | telegram_send.py 호출 |
보고 없이 대기 | 완료 후 1분 미보고 시 |
| 6 | 스킬 체인 준수 | 매핑 테이블 순서대로 진행 | 1차 스킬 건너뛰고 2차부터 | 즉시 개입 |
| 7 | 진전 여부 | 새 파일 읽기/수정 발생 | 같은 파일 반복 수정 또는 멈춤 | 5분 정체 시 |
감시 주기 규칙 (토큰 절약)
- 작업 중: 3분 주기
- 대기 중: 10분 주기
- 전부 대기: 감시 중단
- 같은 세션 30초 내 재조회 금지
4. 실패 대응
세션이 방법론을 안 따를 때 메인 세션의 개입 절차.
4.1 스킬 미호출 (가장 빈번)
감지: 화면에 스킬 호출 없이 코드 수정 착수.
개입:
cmux send {session} "STOP. 코드 수정 전에 Skill(\"systematic-debugging\")부터 호출해. 스킬 없이 수정하면 롤백한다."
10초 후 read-screen으로 수신 확인. 미수신이면 escape 후 재전송.
4.2 검증 없이 완료 선언
감지: "DONE" 출력했지만 실행 테스트/스크린샷 없음.
개입:
cmux send {session} "증거 부족. 실제로 실행해서 에러 없는 것 확인하고 다시 보고해. verification-before-completion 스킬 호출."
4.3 같은 에러 반복 (2회)
감지: 같은 스택트레이스가 2번 출현.
개입: Codex 경량 투입.
cmux send {session} "같은 에러 2회. Codex 투입한다. codex exec '에러 설명' -m gpt-5.4-mini -s read-only --skip-git-repo-check --ephemeral -c 'mcp_servers={}' 실행해."
3회면 Codex 풀 모드, Codex도 실패하면 메인 세션이 직접 개입하거나 해리에게 보고.
4.4 진전 없이 5분 정체
감지: read-screen 결과가 이전과 동일.
개입:
cmux send {session} "5분 정체. 현재 막힌 지점을 한 줄로 보고해."
보고 후에도 해결 안 되면 작업 회수 후 다른 세션에 재배분.
4.5 cmux send 씹힘 (알려진 문제)
증상: OK 반환되지만 세션이 반응 없음.
대응:
cmux send {session} "" # escape 키 효과
sleep 2
cmux send {session} "{원래 메시지}"
sleep 10
cmux read-screen {session} | tail -5 # 수신 확인
3회 시도해도 미수신이면 세션 재시작 고려.
개입 단계 에스컬레이션
1단계: cmux send로 교정 지시 (스킬 호출 요구)
2단계: 구체적 명령어까지 포함해서 재전송
3단계: 작업 회수 → 다른 세션에 재배분
4단계: 메인 세션이 직접 수행
5단계: 해리에게 보고 (진전 없이 5단계 초과)
5. 완료 검증
세션이 "DONE"을 보고했을 때, 메인 세션이 실제로 확인할 증거 목록.
5.1 공통 증거 (모든 작업)
| # | 증거 | 확인 방법 |
|---|---|---|
| 1 | 스킬 호출 이력 | read-screen에서 Skill( 패턴 확인 |
| 2 | 실행 결과 | 에러 없이 종료하는 실행 로그 |
| 3 | 변경 파일 목록 | git diff 또는 DONE 보고의 "변경" 필드 |
| 4 | 텔레그램 보고 | telegram_send.py 호출 확인 |
5.2 유형별 추가 증거
| 작업 유형 | 필수 증거 |
|---|---|
| 버그 수정 | 재현 시나리오에서 버그가 사라진 것 확인 (실행 로그 or 스크린샷) |
| 파이프라인 에러 | 해당 파이프라인 1회 수동 실행 성공 로그 |
| 새 모듈 | 1회 실행 성공 + 출력 파일 존재 확인 + jobs.json 등록 (필요 시) |
| 크론 문제 | jobs.json 상태 + 다음 실행 시각 확인 |
| 웹앱 수정 | 브라우저에서 실제 화면 확인 (스크린샷 or 콘솔 데이터) |
| 코드 리뷰 | 리뷰 결과 보고서 (문제점 + 권장사항 목록) |
| 복잡한 구현 | Plan의 각 단계별 완료 확인 + 통합 테스트 |
5.3 검증 실행 순서
1. read-screen으로 DONE 보고 확인
2. 스킬 호출 이력 확인 (미호출이면 반려)
3. 변경 파일 존재 확인 (ls -la, git diff)
4. 실제 실행 테스트 (메인 세션에서 직접 실행)
5. 통과 → active-work.json에서 항목 제거
6. 실패 → 구체적 실패 이유와 함께 세션에 반려
5.4 반려 템플릿
cmux send {session} "반려. 이유: {구체적 문제}. 해결 후 재보고. verification-before-completion 스킬 호출 필수."
6. 세션 배분 전략
세션별 역할 고정 (권장)
| 세션 | 역할 | 적합 작업 |
|---|---|---|
| 1 (메인) | 감독 + 검증 | 디스패치, 감시, 최종 검증 |
| 2 | 코드 작업 | 버그 수정, 모듈 생성, 리팩토링 |
| 3 | 인프라/파이프라인 | 크론, 파이프라인, 시스템 운영 |
| 4 | 분석/리서치 | 투자 분석, 웹 조사, 볼트 작업 |
병렬 배분 규칙
- 독립 작업 2개 이상이면 서로 다른 세션에 동시 배분
- 의존 관계 있으면 순차 배분 (선행 작업 DONE 확인 후)
- 같은 파일을 건드리는 작업은 같은 세션에 배분 (충돌 방지)
- shared 모듈 수정이 필요한 작업은 단독 배분 (다른 세션과 겹치면 위험)
7. 하네스 교훈 반영
이 프로토콜은 harness-lessons.md의 실패 패턴에서 직접 도출됨.
| 실패 패턴 | 이 프로토콜의 대응 |
|---|---|
| cmux send 씹힘 | 4.5절: 10초 후 read-screen 확인, 3회 재시도 |
| "묻지 말고 해" 무시 | 템플릿에 판단 기준 필수 포함 |
| "이미 있어요" 피상 분석 | 비교 작업 시 5단계 프레임 포함 |
| superpowers 스킬 미사용 | 템플릿에 스킬명 명시 + 감시 체크리스트 #1 |
| 감시기 형식만 감시 | 체크리스트 7개 항목으로 확장 |
8. 빠른 참조: 디스패치 원라이너
자주 쓰는 패턴을 빠르게 복사해서 쓸 수 있도록 정리.
# 버그 수정
cmux send 2 "목표: {버그 설명}. 방법: Skill(\"systematic-debugging\") → 원인 특정 → 수정 → Skill(\"verification-before-completion\"). 검증: 실행해서 에러 없음 확인. 보고: DONE 형식. 금지: 스킬 없이 수정."
# 파이프라인 에러
cmux send 3 "목표: {파이프라인명} 에러 수정. 방법: Skill(\"pipeline-debug\") → Skill(\"error-resolve\"). 검증: 수동 1회 실행 성공. 보고: DONE 형식. 금지: 로그 안 보고 추측 수정."
# 새 모듈
cmux send 2 "목표: {모듈 설명} 신규 생성. 방법: Skill(\"pipeline-create\") → Skill(\"verification-before-completion\"). 검증: 1회 실행 + 출력 확인. 보고: DONE 형식. 금지: shared 모듈 수정."
# 인프라 점검
cmux send 3 "목표: {시스템} 상태 점검. 방법: Skill(\"infra-ops\"). 검증: 상태 보고서 출력. 보고: DONE 형식."
# 감시 루프 (3분 주기)
while true; do for s in 2 3 4; do echo "=== S$s ==="; cmux read-screen $s | tail -20; done; sleep 180; done