Teamwork 다중 에이전트 오케스트레이션 (/teamwork)
Teamwork는 전문적인 신규 컨텍스트 하위 에이전트들로 구성된 협업 팀을 조율하여 대규모 소프트웨어 엔지니어링 프로젝트, 다중 파일 마이그레이션, 시스템 시뮬레이션, 엄격한 문서 비평 및 수학적 증명을 수행합니다.
단일 대화 컨텍스트에 과부하를 주거나 구현 에이전트가 스스로 불완전한 작업을 인증하도록 허용하는 대신, Teamwork는 모든 실행을 두 가지 엄격한 단계로 나눕니다:
- 1단계: 작업 범위 지정 및 명세 (범위 지정 인터뷰) — 범위를 명확히 하고, 관찰 가능한 요구 사항(무엇을, 어떻게가 아닌)을 정의하며, 독립적인 프로그램 또는 루브릭 기반 검증을 설정하고, 단축 제한을 무결성 모드(
development,demo,benchmark)에 매핑하며, 프로젝트 작업 디렉터리를 설정하고, 사용자의 명시적 승인이 필요한 검토 가능한 프롬프트 아티팩트(prompt_draft.md)를 생성합니다. - 2단계: 자율 실행 (구조화된 핸드오프 및 적대적 게이트) — 승인되면 Project Sentinel이
ORIGINAL_REQUEST.md를 기록하고, 사전 점검 종속성 검사를 실행하며, 선택된 실행 경로에 맞는 전문화된 Orchestrator로 라우팅하고, 독점적인 파일 소유권 및 에이전트별 스크래치 격리를 갖춘 Explorer 및 Worker를 병렬로 조정하며, 모든 마일스톤에서 독립적인 검증 게이트(Critic, Challenger, Auditor)를 시행하고, 종단 간 Victory Auditor(VICTORY CONFIRMED)가 최종 완료를 승인할 때까지 차단합니다.
교차 하네스 위임 및 도구 매핑
Teamwork는 하네스에 구애받지 않습니다. 아래의 각 추상 작업을 현재 에이전트 하네스에서 사용 가능한 네이티브 도구에 매핑하십시오 (자세한 내용은 references/harness-delegation.md 참조):
| 추상 작업 | 네이티브/도구 하네스 | Claude Code / Cowork | Codex / ChatGPT Work | Cursor / omp / 기타 하네스 |
|---|---|---|---|---|
| 신규 하위 에이전트 생성 | invoke_subagent (TypeName, Role, Prompt 사용) | Agent (Task) 도구 | spawn_agent (fork_context: false 또는 fork_turns: "none") | 네이티브 task/하위 에이전트 도구(깨끗한 컨텍스트) |
| 사용자 정의 하위 에이전트 정의 | define_subagent (또는 agents/*.md) | ./skills/ 또는 agents/*.md | 범용 하위 에이전트가 agents/*.md를 읽음 | agents/*.md를 로드하거나 프롬프트에 페르소나 파일 경로 전달 |
| 하위 에이전트 메시지/깨우기 | send_message | 아티팩트 상태로 새 Agent 재개/디스패치 | send_message / wait | 업데이트된 아티팩트 상태를 새 하위 에이전트에 전달 |
| 구조화된 사용자 질문 | ask_question | AskUserQuestion (또는 일반 채팅) | 구조화된 질문 도구 (또는 일반 채팅) | 구조화된 질문 도구 또는 일반 텍스트 질문 |
| 주기적 진행 상황 확인 | schedule (CronExpression) | 마일스톤 디스패치 사이에 확인 | 마일스톤 디스패치 사이에 확인 | 마일스톤 디스패치 사이에 확인 |
하위 에이전트 페르소나 해결: 모든 Teamwork 하위 에이전트 페르소나는
agents/<persona-name>.md(이 스킬 디렉터리 기준 또는 플러그인 루트../../agents/<persona-name>.md기준)에 정의됩니다.
- 하네스가
agents/에서 명명된 하위 에이전트를 등록하는 경우, 프론트매터name으로 하위 에이전트를 호출하십시오 (예:teamwork-sentinel,teamwork-interviewer,teamwork-orchestrator,teamwork-swe-light,teamwork-doc-orchestrator,teamwork-proof-orchestrator,teamwork-colosseum,teamwork-explorer,teamwork-worker,teamwork-critic,teamwork-challenger,teamwork-auditor,teamwork-victory-auditor,teamwork-dependency-auditor).- 하네스가 명명된 하위 에이전트를 등록하지 않는 경우, 런타임에 동적으로 등록하거나(예:
define_subagent을 통해) 일반 목적의 신규 컨텍스트 하위 에이전트를 생성하고 작업을 시작하기 전에agents/<persona-name>.md를 시스템 페르소나로 읽도록 지시하십시오.- 하네스가 하위 에이전트 중첩(하위 에이전트가 하위 에이전트를 생성)을 지원하지 않는 경우, 기본 에이전트는 Sentinel과 Orchestrator 역할을 모두 수행하며, Explorer, Worker, Critic, Challenger, Auditor 및 Victory Auditor를 평면적인 깊이-1 하위 에이전트로 직접 디스패치하고 모든 아티팩트 핸드오프와 신규 컨텍스트 경계를 유지합니다.
실행 경로 및 라우팅 테이블
Teamwork는 승인된 프롬프트에 설명된 작업을 기반으로 팀 아키텍처, 검증 깊이 및 오케스트레이터 역할을 자동으로 선택합니다 (references/orchestration-patterns.md 참조):
| 실행 경로 | 오케스트레이터 페르소나 | 최적 대상 | 트리거/옵트인 신호 | 사전 점검 종속성 감사? | 최종 승리 감사 |
|---|---|---|---|---|---|
| 1. 프로젝트 패턴 (일반 분산 SWE) | teamwork-orchestrator (agents/teamwork-orchestrator.md) | 다중 파일 SWE, 대규모 리팩토링, 시스템 시뮬레이션, 그린필드 개발. | 기본값 (다중 구성 요소 또는 다중 파일 작업에 대해 자동 선택됨). | 예 (teamwork-dependency-auditor) | teamwork-victory-auditor |
| 2. SWE Light (순차적 개선) | teamwork-swe-light (agents/teamwork-swe-light.md) | 하나의 독립적인 변경 — 지역화된 버그 수정, 소규모 기능, 또는 포함된 리팩토링 (4가지 엄격한 규칙). | 명시적 프롬프트 신호 (예: "작게 유지해", "집중해서 유지해", "하나의 포함된 변경으로 실행해"). | 예 (teamwork-dependency-auditor) | teamwork-victory-auditor |
3. 문서 검토 (document_review) | teamwork-doc-orchestrator (agents/teamwork-doc-orchestrator.md) | 다각도 비평, RSA 검토 트리, 논문, RFC 및 설계 문서 종합. | 검토 요청 (예: "이 논문을 검토해", "이 설계 문서를 비평해"). | 아니요 | teamwork-victory-auditor (문서 검토 모드) |
4. 수학/증명 (proof) | teamwork-proof-orchestrator (agents/teamwork-proof-orchestrator.md) | 수학 문제 해결, 5단계 보조 정리 유도, 정리 증명. | 수학 프롬프트 (예: "정리 X를 증명해", "수학적 경계를 유도하고 검증해"). | 선택 사항 (CAS/Lean/Python이 필요한 경우) | 내장 파이프라인 증명 검증기 + teamwork-victory-auditor |
5. 수학/증명 — 대규모 팀 (colosseum) | teamwork-colosseum (agents/teamwork-colosseum.md) | 어려운 추측, 반례 검색, 조합 최적화를 위한 고규모 토너먼트 네트워크. | 명시적 규모 신호 (예: "매우 큰 에이전트 팀을 사용해"). | 선택 사항 (컴퓨팅 도구가 필요한 경우) | teamwork-victory-auditor (증명/Colosseum 모드) |
무결성 모드
Teamwork는 세 가지 내부 무결성 모드 중 하나를 적용하여 검증 엄격성을 프로젝트 요구 사항에 맞춥니다. 1단계 인터뷰 중에 사용자에게 어떤 단축키가 금지되어야 하는지 질문하고(질문에 내부 모드 이름을 노출하지 않고) 답변을 프롬프트 아티팩트의 해당 모드에 매핑하십시오:
| 무결성 모드 | 목적 | 허용되는 관행 | 운영 경계 / 금지된 단축키 | 감사자 집행 |
|---|---|---|---|---|
development (기본값) | 빠른 반복 | 코드 재사용, 타사 라이브러리, 사전 구축된 프레임워크 허용. | 출력 조작, 파사드/스텁 구현 반환, 테스트 통과 모의/위조. | 조작된 출력, 하드코딩/모의된 테스트 통과, 미구현 스텁을 플래그 지정합니다. |
demo | 재현 가능한 프레젠테이션 | 표준 라이브러리 및 일반 유틸리티 허용; 핵심 로직은 실제로 구현되어야 합니다. | 모든 development 금지 사항 추가로: 오픈 소스에서 핵심 로직 복사, 핵심 작업을 외부 도구/바이너리에 위임, 테스트 소스/오라클을 읽어 예상 동작을 역설계. | 가져오기, 하위 프로세스 호출, git/파일 액세스를 감사하여 핵심 로직이 독창적이고 테스트 오라클이 역설계되지 않았는지 확인합니다. |
benchmark | 철저한 평가 | 언어 표준 라이브러리만 사용하여 완전히 독립적인 처음부터 구현. | 모든 demo 금지 사항 추가로: 구현을 위해 타사 라이브러리 또는 외부 프레임워크 사용. | 최대 엄격성: 비표준 라이브러리 종속성, 외부 위임, 오라클 엿보기를 모두 거부하고 실제 실행 출력을 이진 거부권으로 검증합니다. |
1단계: 작업 범위 지정 및 명세 (범위 지정 인터뷰)
실행 팀을 생성하기 전에 무엇을 구축할지 그리고 독립적으로 어떻게 검증될지에 대해 사용자와 조정하십시오. 전체 내용과 엣지 케이스는 references/interview-protocol.md를 참조하십시오.
핵심 원칙: 목표와 관찰 가능한 불변량을 정의하고, 내부 메커니즘은 정의하지 마십시오
사용자가 명시적으로 요구하지 않는 한 프롬프트 아티팩트에 내부 클래스 계층, 파일 분할 또는 구현 알고리즘을 규정하지 마십시오. 어떻게를 지나치게 제한하면 Explorer와 Worker가 실제 코드베이스 제약 조건에 적응하는 것을 방해합니다. 검증을 불충분하게 지정하면 에이전트가 불완전한 작업을 스스로 인증할 수 있습니다.
9단계 범위 지정 프로토콜
- 1단계 — 접수 및 분류:
- 사용자의 초기
/teamwork요청과 작업 공간의 참조된 파일을 검사합니다. 2단계로 직접 건너뛰려면[skip-interview]매개변수를 지원합니다. 인식되지 않은 대괄호 매개변수는 무시된 것으로 기록합니다. - (a) 범위 및 목적, (b) 실행 경로 옵트인, (c) 운영 경계/무결성 모드, (d) 검증 및 승인 기준, (e) 작업 디렉터리 전반에서 무엇이 명확하고 무엇이 누락되었는지 식별합니다.
- 사용자 집중 존중: 필요한 모든 문의 사항을 단일 집중 질문지(또는 매우 다면적인 영역의 경우 최대 2개)로 일괄 처리하여 사용자 왕복을 최소화합니다. 선택 사항이 개별적인 경우
ask_question을 사용하거나 채팅에서 명확하게 번호가 매겨진 질문을 사용합니다.
- 사용자의 초기
- 2단계 — 범위, 목적 및 실행 경로 옵트인:
- 전달 가능한 항목의 목적을 명확히 합니다:
showcase/demo,production,eval/benchmark, 또는exploration/research. - 프롬프트 아티팩트의 시작 문장에 명시적 옵트인(예: "작게 유지하고 집중해" 또는 "매우 큰 에이전트 팀을 사용해")을 캡처합니다.
- 전달 가능한 항목의 목적을 명확히 합니다:
- 3단계 — 단축 제한 및 무결성 모드 매핑:
- 오픈 소스 복사, 외부 CLI 위임, 오라클 엿보기 및 타사 라이브러리에 대한 사용자 제약 조건을 도출합니다.
development,demo또는benchmark에 매핑합니다.
- 4단계 — 요구 사항 (
R1,R2, ...) :- 관찰 가능한 동작, 입력/출력, 불변량 및 제약 조건을 설명하는 모듈식 요구 사항 블록을 초안합니다. — 전달 가능한 항목이 무엇을 해야 하는지, 코딩 방법은 아닙니다.
- 5단계 — 독립적인 검증 및 이중 트랙 테스트:
- 자율 소프트웨어 에이전트는 실행 가능한 외부 검증이 부족할 때 성급하게 완료를 주장하는 경향이 있습니다. 안정적으로 실행되고 시뮬레이션된 통과에 저항하는 반복 가능한 자동화된 테스트에 기반한 명확한 승인 기준을 수립합니다.
- 일반 경로 SWE 프로젝트의 경우, 독립적인 테스트 스위트가 최소 계층 공식을 충족하는 이중 트랙 테스트 아키텍처가 필요합니다: $$\text{총 최소 테스트 수} \ge 11N + \max\left(5, \left\lfloor \frac{N}{2} \right\rfloor\right)$$
- 6단계 — 승인 기준:
- 검증 확인 사항을
## 승인 기준아래에 범주별로 그룹화된 확인 가능한- [ ]항목으로 변환합니다.
- 검증 확인 사항을
- 7단계 — 인프라 제약 조건 (조건부) :
- 샌드박스 또는 외부 작업 제약 조건을 처리할 때만 제어된 API/파일 시스템 경계를 지정합니다.
- 8단계 — 프로젝트 작업 디렉터리:
- 기존 코드베이스: 기존 디렉터리를 사용합니다(묻지 마십시오). 새 프로젝트: 묻고,
~/teamwork_projects/<project_name>을 기본값으로 합니다.
- 기존 코드베이스: 기존 디렉터리를 사용합니다(묻지 마십시오). 새 프로젝트: 묻고,
- 9단계 — 조립, 검증 및 승인 요청:
- 표준 스키마를 사용하여
prompt_draft.md를 작성하고 전체 텍스트를 채팅에서 사용자에게 직접 제시합니다. - 예상 경로 제시: "다중 마일스톤 일반 엔지니어링 경로를 통한 실행이 예상됩니다. 단일 경량 변경을 선호하는 경우 알려주십시오."
- 2단계를 시작하기 전에 중단하고 사용자의 명시적 승인을 기다리십시오.
- 표준 스키마를 사용하여
2단계: 자율 실행 (Sentinel 및 Orchestrator 프로토콜)
사용자가 프롬프트 아티팩트를 명시적으로 승인하면 즉시 PROJECT SENTINEL 모드로 전환합니다. references/orchestration-patterns.md, references/verification-gates.md 및 references/operational-protocols.md를 참조하십시오.
핵심 Sentinel 책임
Sentinel (agents/teamwork-sentinel.md)로서 귀하는 영구적인 최상위 프로젝트 관리자입니다. 생산 코드를 작성하거나, 구현 세부 사항을 디버깅하거나, 낮은 수준의 기술적 결정을 내려서는 안 됩니다 — 전체 프로젝트 수명 주기를 감독하기 위해 컨텍스트를 초경량으로 유지하십시오.
책임 1: 기준선 수집 및 요청 지속성
- 대상
작업 디렉터리가 존재하는지 확인합니다(예:mkdir -p <working_dir>/.teamwork/scratch). - 승인된 프롬프트 아티팩트를
<working_dir>/ORIGINAL_REQUEST.md에 그대로 기록합니다(변경할 수 없는 기준 진실). <working_dir>/BRIEFING.md를 초기화하여 활성 실행 경로, 하위 에이전트 ID, 현재 마일스톤 및 상태 불변량을 추적합니다.
책임 2: 자율 상태 및 진행 상황 모니터링
<working_dir>/PROGRESS.md를 스캔하고 활성 하트비트(마지막 방문: [타임스탬프])를 추적하기 위해schedule(또는 턴 전환)을 통해 비침습적인 주기적 모니터를 예약합니다.- 원시 로그를 채팅에 덤프하지 않고 간결하고 사실적인 진행 상황 요약을 사용자에게 제공합니다.
책임 3: 환경 감사 및 실행 경로 라우팅
- 실행 경로 및 라우팅 테이블에서 실행 경로를 선택합니다.
- 사전 점검 종속성 감사 (차단) :
- 로컬 도구 체인이 필요한 일반 SWE, SWE Light 또는 수학 실행의 경우,
teamwork-dependency-auditor(agents/teamwork-dependency-auditor.md)를 생성합니다. READY상태: 지정된 경로 Orchestrator를 생성합니다.MISSING상태
- 로컬 도구 체인이 필요한 일반 SWE, SWE Light 또는 수학 실행의 경우,