voidlight00/deo-harness/deo-pipeline

deo-pipeline — Dynamic Effort Orchestration

목표 하나를 받아 task로 분해하고, task마다 작업 복잡도에 맞는 effort를 배정해 sub-agent(swarm)를 병렬 운용하는 오케스트레이터다. 솔로 개발자·연구자가 팀 규모 생산성을 내는 것이 목표다.

왜 effort 차등인가

effort는 Fable 5에서 지능·지연·비용을 조절하는 1차 손잡이다. DEO의 비용 제어는 모델 차등(경량 모델 분리)이 아니라 effort 차등으로 달성한다 — 모든 에이전트가 Fable 5에서 돌기 때문에 작업이 다른 모델로 빠져나가지 않고, Fable 5의 낮은 effort 설정은 이전 모델의 최고 설정 성능을 자주 능가하므로 품질 손실 없이 비용을 줄일 수 있다. 루틴 작업에 높은 effort를 쓰면 작업에 필요한 수준 이상으로 컨텍스트 수집과 숙고가 늘어난다 — 그래서 "전부 최고 설정"이 아니라 "작업에 맞는 레벨"이 원칙이다. [guide: Consider all effort levels]

Effort 매트릭스 (SSoT — 이 섹션이 유일한 정의)

이 표를 다른 파일(agents, CLAUDE.md 블록, README)에 복사하지 않는다. 두 곳에 있으면 한쪽만 갱신되어 드리프트가 생기고, 드리프트는 곧 오할당이다. 다른 파일은 이 섹션을 경로로 참조만 한다.

할당 기준

역할별 기준선: 오케스트레이터(이 스킬의 실행 주체)와 deo-planner는 high에서 시작한다. deo-executor는 task별 할당을 따른다. deo-verifier는 task 단위 검증을 high로 수행하고, 전체 워크플로우 최종 게이트 1회만 xhigh로 올린다 — 모든 검증을 최고 레벨로 돌리면 검증 비용이 검증 가치를 초과한다. [guide: Consider all effort levels]

판단이 어려우면 high에서 시작하고 두 신호로 조정한다: 작업이 완료되는데 필요 이상 오래 걸리면 한 단계 내리고, 복잡한 문제에서 추론이 얕으면 한 단계 올린다.

effort → 디스패치 문구 매핑 (구현 메커니즘)

Claude Code의 Agent 디스패치에는 effort 파라미터가 없다. 존재하지 않는 API 파라미터를 지시하는 대신, DEO의 effort는 두 가지로 구현한다:

1. 디스패치 프롬프트에 아래 문구를 주입 — 숙고 깊이와 작업 스타일을 조향한다.
2. 작업 범위·검증 깊이의 차등 — low는 자가 검증을 생략하고, xhigh는 fresh-context 교차 검증을 요구한다.

문구가 작업 의도와 깊이를 함께 전달하므로, executor는 별도 파라미터 없이도 레벨에 맞는 작업 스타일을 잡는다. [guide: Consider all effort levels] [guide: Give the reason, not only the request]

워크플로우 (6단계)

① 목표 입력

사용자 목표를 접수한다. 모호하면 최대 2문항(목적, 산출물 형태)만 묻고, 답이 없어도 합리적 기본값으로 진행한다 — 질문은 보강이지 차단이 아니다. run_id를 YYYYMMDD-HHMMSS-<슬러그>로 만들고 작업 디렉토리 ./.deo/<run_id>/를 생성한다.

② 계획 — deo-planner 디스패치 (high)

deo-planner에게 목표·작업 디렉토리·프로젝트 컨텍스트 경로를 주고 PLAN.json(task breakdown + effort 할당)을 생성시킨다. 스키마는 agents/deo-planner.md가 정의한다.

계획 수립 직후, 사용자 환경에 /graphify 스킬이 있으면 프로젝트 지식 그래프 갱신 단계로 호출할 수 있다 — 선택 단계이며, 없으면 건너뛰고 워크플로우에 영향을 주지 않는다.

③ 실행 — deo-executor 병렬 디스패치

depends_on이 비어 있거나 충족된 task를 같은 메시지에서 병렬로 디스패치한다. Fable 5는 병렬 서브에이전트 운용이 신뢰할 만하므로 독립 task를 직렬화할 이유가 없다 — 직렬화는 가장 느린 task에 전체가 묶이는 비용만 만든다. [guide: Parallel subagents]

디스패치 프롬프트 구성 (순서 고정):

[맥락] 전체 목표는 <goal>이고, 이 task는 그 안에서 <역할>을 맡는다.
      산출물은 <후속 task 또는 사용자>가 <용도>로 쓴다.
[effort 권고: <레벨>] <위 매핑 표의 해당 문구>
[작업] <PLAN.json의 instructions + 산출물 절대경로>
[경계] <PLAN.json의 boundaries — 해도 되는 것 / 하면 안 되는 것>
[자율 진행] <references/autonomy-reminders.md의 리마인더 블록>

맥락을 먼저 주는 이유: Fable 5는 요청 뒤의 의도를 알 때 스스로 의도를 추측하는 대신 작업을 관련 정보와 직접 연결한다 [guide: Give the reason, not only the request]. 경계를 명시하는 이유: 요청하지 않은 행동(부탁 안 한 수정, 방어적 백업)을 막는 가장 싼 방법이 사전 선언이다 [guide: State the boundaries].

④ task 단위 검증 — deo-verifier (자동 진행)

매 task 완료 시 deo-verifier를 fresh-context로 디스패치한다: 작업 대화를 공유하지 않고 산출물 경로와 PLAN.json의 verify.criteria만 전달한다 (디스패치 패턴: references/fresh-context-verifier.md). 만든 쪽의 컨텍스트를 물려받은 검증자는 같은 맹점을 공유한다 — 분리된 fresh-context 검증자가 자기비평보다 잘 작동한다. [guide: Recommended scaffolding changes]

• PASS → 다음 task로 자동 진행한다. 사용자에게 허락을 구하지 않는다 — 되돌릴 수 있는 후속 작업은 원래 요청에서 따라 나온다. [guide: Rare cases of early stopping]
• FAIL → verifier의 결함 증거를 첨부해 executor를 같은 effort로 1회 재디스패치한다. 재실패하면 effort를 한 단계 올려 1회 더 시도한다. 그래도 실패하면 해당 task를 보류로 표시하고 독립적인 나머지 task를 계속 진행한다 — 한 task의 실패가 전체를 멈출 이유는 아니다.

⑤ 진행 보고 (3 task 주기)

task 3개가 완료될 때마다 send_to_user 도구(정의: references/send-to-user-tool.json)로 간단 보고를 보낸다. 도구 입력은 요약되지 않아 수치가 온전히 도착하고, 호출해도 턴이 끝나지 않아 작업이 계속된다. [guide: Create a send-to-user tool]

보고 내용은 사후 집계다:

• 완료 task 목록과 각각의 증거(산출물 경로, 실행 명령 exit code)
• 산출물 크기(파일 수·라인 수) — 토큰 사용 규모의 대리 지표
• task별 사용 effort 분포 (예: low 2, medium 3, high 1)

모든 주장은 이번 세션의 도구 실행 결과와 대조한 것만 적는다 — 증거 없는 "완료"는 보고하지 않고 "미검증"으로 표시한다 [guide: Ground progress claims during long runs]. 잔여 컨텍스트·예산 수치는 보고에 넣지 않는다 — 카운트다운 노출은 조기 세션 종료 행동을 유발한다 [guide: Rare cases of context-budget concern].

⑥ 완료 — 최종 게이트 + 마커

모든 task가 PASS(또는 보류 확정)되면 deo-verifier를 xhigh 문구로 1회 디스패치해 전체 산출물을 PLAN.json 전체 기준과 대조한다(최종 게이트 — 워크플로우에서 유일한 xhigh 사용 지점). 통과하면:

1. ✅ DEO 워크플로우 완료 마커를 출력한다.
2. 최종 요약을 쓴다 — 작업 과정을 전혀 못 본 독자를 위한 글이다. 결과부터, 완전한 문장으로, 작업 중 만든 약어·화살표 체인 없이 쓴다. [guide: Readability when communicating with the user]
3. 선택적 human review를 제안한다 — 결과에 영향이 큰 판단 지점이 있으면 1~3개를 짚어 "이 부분만 직접 확인해 주시면 좋습니다"로 안내한다. 없으면 제안하지 않는다.

보류 task가 있으면 마커 대신 보류 목록과 각 실패 증거를 보고하고 사용자 판단을 요청한다.

런타임 effort 변경

진행 중 사용자가 effort 변경: <대상> <레벨>이라고 말하면 즉시 적용한다:

• 대상이 task ID(T3)면 해당 task만, swarm ID면 그 swarm의 미시작 task 전부, 전체면 default_effort를 바꾼다.
• PLAN.json의 해당 effort 필드를 갱신하고, 이후 디스패치부터 새 레벨의 문구를 주입한다.
• 이미 실행 중인 task는 현재 레벨로 끝까지 간다 — 중간 강제 종료는 산출물을 반쯤 만든 상태로 남긴다.
• 변경 내역은 STATE.md에 한 줄 기록한다 (resume 시 일관성 유지).

Swarm 일괄 지정

planner는 성격이 같은 task 묶음을 swarm으로 그룹화할 수 있다(PLAN.json swarms[]). swarm에 effort를 지정하면 소속 task에 일괄 적용된다. 우선순위: task 개별 지정 > swarm 지정 > default_effort(high). 사용자가 시작 시 "수집 swarm은 low로"처럼 말하면 planner 디스패치에 그대로 전달한다.

Handoff / Resume

장기 작업은 ./.deo/<run_id>/STATE.md에 상태 스냅샷을 유지한다 — 템플릿: state/STATE-template.md(하네스 배포본 기준 harness/state/, 설치 시 스킬 디렉토리 아래로 복사), 설계 원리: references/memory-system.md. ⑤ 보고 시점마다 갱신한다.

/deo resume <run_id> 요청 시 STATE.md와 PLAN.json만 읽고 미완료 task부터 재개한다 — 이전 대화 원문 없이도 재개 가능해야 스냅샷이 의미가 있다. 교훈(교정받은 내용, 확인된 접근법)은 run 디렉토리의 메모리 파일에 기록해 다음 run이 참조하게 한다. [guide: Construct a memory system]

에러 처리

• planner의 PLAN.json이 스키마에 안 맞으면(필수 필드 누락, JSON 파싱 실패) 결함 내용을 첨부해 1회 재디스패치하고, 재실패 시 무엇이 모호했는지 사용자에게 보고한다.
• executor가 산출물 경로 없이 완료를 주장하면 미검증으로 취급하고 verifier에 보내지 않는다 — 증거 없는 주장은 진행이 아니다. [guide: Ground progress claims during long runs]
• verifier가 INDETERMINATE(판정 불가 기준)를 반환하면 기준을 이진 판정 가능하게 고쳐 재검증한다. 기준의 결함이지 산출물의 결함이 아니므로 executor를 재디스패치하지 않는다.

사용법

비개발자를 위한 안내입니다.

1. 설치: README.md의 설치 방법대로 이 폴더를 ~/.claude/skills/와 ~/.claude/agents/에 복사합니다. 이미 설치돼 있으면 이 단계는 건너뜁니다.
2. 시작: Claude Code에서 /deo 리뷰 데이터 500건 정리하고 분석 리포트 만들어줘처럼 목표를 한 문장으로 적습니다. 개발 용어를 몰라도 됩니다 — 작업 분해와 effort 배정은 자동입니다.
3. 진행 중 조정: 진행이 답답하면 effort 변경: 전체 medium, 특정 작업만 더 꼼꼼히 하려면 effort 변경: T3 xhigh라고 입력하면 즉시 반영됩니다.
4. 이어하기: 세션이 끊겼으면 /deo resume <run_id>라고 입력합니다. run_id는 시작할 때와 진행 보고에 표시됩니다.
5. 바꿔도 되는 것: 'Effort 매트릭스'의 예시 열은 자기 업무에 맞게 수정해도 됩니다. 바꾸지 말아야 하는 것: effort 레벨 이름(low/medium/high/xhigh), "xhigh는 최종 게이트 1회만" 원칙, 그리고 매트릭스를 다른 파일로 복사하지 않는 SSoT 원칙 — 이걸 풀면 비용 제어와 일관성이 사라집니다.

참조 (병렬 산출물 — 경로로만 참조, 이 스킬이 내용을 복제하지 않음)

• references/memory-system.md — 메모리/상태 파일 설계
• references/send-to-user-tool.json — 진행 보고 도구 정의
• references/autonomy-reminders.md — 자율 실행 리마인더 문구
• references/fresh-context-verifier.md — 검증자 디스패치 패턴
• state/STATE-template.md — handoff/resume용 상태 스냅샷 템플릿
• 에이전트 정의: agents/deo-planner.md, agents/deo-executor.md, agents/deo-verifier.md (설치 후 ~/.claude/agents/)