polyphony

polyphony skill 개요

polyphony는 컨테이너로 분리된 워크스페이스에서 여러 에이전트 작업을 병렬로 돌리기 위한 멀티에이전트 오케스트레이션 skill입니다. 각 세션은 서로 다른 Docker 컨테이너와 git branch를 갖기 때문에, 브랜치 충돌, 공유 상태 버그, 복잡한 정리 작업 없이 동시에 실행해야 할 때 특히 유용합니다.

polyphony skill은 어떤 용도인가

작업이 하나의 프롬프트로 끝나기에는 크지만, 구조화된 위임의 이점을 여전히 크게 받는 경우에 polyphony skill을 사용하세요. 예를 들면 병렬 기능 작업, 격리된 검증, 이슈 분류, 또는 같은 codebase를 대상으로 여러 agent 경로를 동시에 돌려보는 상황이 그렇습니다. 깔끔한 실행, 재현 가능한 작업 라우팅, 더 안전한 멀티에이전트 조정을 중시하는 사용자에게 맞게 설계되었습니다.

polyphony skill이 눈에 띄는 이유

polyphony의 핵심 차별점은 격리 우선의 workflow 설계입니다. 에이전트에게 “전부 다 해라”라고 맡기지 않고, 작업 발견, 라우팅, 프로비저닝, 런타임, 검증을 분리해서 각 worker가 통제된 workspace에서 동작하게 만듭니다. 그래서 독립적인 테스트와 더 깔끔한 착지 behavior가 필요할 때, polyphony for Multi-Agent Systems 방식이 훨씬 실용적으로 느껴집니다.

가장 잘 맞는 경우와 tradeoff

환경에서 이미 Docker 또는 OrbStack을 지원하고, 일회성 프롬프트 패턴보다 기본 내장형 orchestration을 원한다면 polyphony가 가장 잘 맞습니다. 반대로 단순히 하나의 채팅 응답만 필요하거나, container를 돌릴 수 없거나, repository-aware workflow 없이 최소한의 설정만 원한다면 효용이 떨어집니다.

polyphony skill 사용 방법

polyphony 설치 및 로드

skills 디렉터리에 polyphony skill을 설치한 다음, skill loading을 지원하는 host workflow에서 불러오세요. repository 설명에 따르면 container isolation이 가능할 때 자동으로 로드되도록 의도되어 있으며, /spawn-team의 기본값이기도 합니다. 환경이 다르다면 skill에 의존하기 전에 Docker 접근, branch 생성, workspace mount가 가능한지 먼저 확인하세요.

올바른 파일부터 시작하기

polyphony를 사용할 때는 skills/polyphony/SKILL.md부터 읽고, skill이 내부적으로 사용하는 순서대로 연결되거나 언급된 맥락을 따라가세요: task lifecycle, architecture, prerequisites, configuration, 그리고 파일 안에 박혀 있는 repository-specific reference들입니다. 이 repo에는 helper script나 추가 reference 폴더가 없으므로 핵심 동작이 skill 파일 자체에 들어 있습니다. 그래서 꼼꼼히 읽는 것이 중요합니다.

대충 잡은 목표를 쓸모 있는 프롬프트로 바꾸기

좋은 polyphony 프롬프트에는 target repo, 원하는 병렬 agent 수, 각 agent가 맡을 작업 유형, branch 또는 PR 기대사항, 그리고 테스트·credentials·cleanup 관련 제약이 들어가야 합니다. 예를 들어 “이 프로젝트 고쳐줘”라고 하기보다, “이 이슈를 세 개의 분리된 agent 작업으로 나눠서 재현, 수정, 검증을 각각 맡기고, 별도의 Docker workspace를 사용하며 branch별 landing status를 보고해 달라”처럼 요청하는 편이 좋습니다.

더 좋은 출력을 위해 명시할 것

task priority, dependencies, read-only 우선 여부, 어떤 환경을 프로비저닝해도 안전한지, 무엇을 검증으로 볼지 같은 구체적인 routing signal을 주세요. 이렇게 하면 orchestrator가 더 나은 RunSpecs를 고를 수 있고, 불필요한 container spin도 줄어듭니다. polyphony 가이드에서 가장 유용한 입력은 긴 설명문이 아니라, 더 또렷한 task boundary입니다.

polyphony skill FAQ

polyphony는 Docker 환경에서만 쓸 수 있나요?

실질적으로는 그렇습니다. polyphony skill은 container isolation이 가능하다는 전제를 깔고 있으므로, Docker 또는 OrbStack 지원이 도입의 주요 관문입니다. container를 프로비저닝할 수 없다면 workflow의 가치가 대부분 사라집니다.

polyphony는 일반 프롬프트와 다른가요?

네. 일반 프롬프트는 에이전트에게 무엇을 할지 요청하지만, polyphony는 여러 agent run이 어떻게 claim되고, routed되고, provision되고, verified되고, landed될지를 정의합니다. 독립된 branch와 깔끔한 실행이 속도보다 중요할 때, 바로 그 구조가 polyphony skill의 핵심입니다.

초보자도 polyphony를 사용할 수 있나요?

네, 이미 container를 실행할 수 있고 skill 파일을 읽을 줄 안다면 가능합니다. 가장 큰 학습 곡선은 프롬프트 작성이 아니라, polyphony가 task decomposition과 환경 준비 상태를 전제로 한다는 점을 이해하는 데 있습니다. 초보자는 작은 작업 하나와 명확한 검증 목표 하나로 시작할 때 보통 더 좋은 결과를 얻습니다.

언제 polyphony를 쓰지 말아야 하나요?

빠른 일회성 질문, 가벼운 수정, Docker가 없는 환경에는 polyphony를 쓰지 마세요. 또한 작업이 모호해서 각 agent가 무엇을 맡아야 할지 아직 정하지 못한 경우에도 적합하지 않습니다. 이때는 orchestration 오버헤드가 이점보다 커질 수 있습니다.

polyphony skill 개선 방법

router에 더 나은 task boundary를 주기

polyphony에서 품질이 가장 크게 좋아지는 지점은 task decomposition을 더 명확히 하는 것입니다. 어떤 작업이 탐색용인지, 어떤 작업이 code를 바꾸는지, 어떤 작업이 검증만 하는지 분명히 적으세요. 병렬성이 필요하다면, 시스템이 모호한 목표에서 알아서 추론하게 두지 말고 분할 방식을 명시해야 합니다.

workspace 동작에 영향을 주는 제약을 포함하기

branch naming 규칙, 네트워크 제한, test runtime 기대치, secrets나 mounted identity가 필요한지 여부를 알려 주세요. polyphony는 분리된 container와 독립 branch를 쓰므로, 이런 제약은 provisioning과 수동 개입 없이 run을 끝낼 수 있는지에 직접적인 영향을 줍니다.

구현만 하지 말고 검증도 요청하기

흔한 실패 패턴은 “코드가 바뀌었다”에서 멈추는 것입니다. 더 나은 polyphony 사용법은 각 agent 경로마다 재현 단계, test command, landing 기준까지 요청하는 것입니다. 여러 worker가 서로 다른 해법으로 수렴할 수 있는 상황에서는 특히 중요하며, 신뢰할 수 있는 merge 결정을 내려야 할 때 더 그렇습니다.

첫 실행 이후에는 다시 조정하기

첫 출력이 너무 넓다면 task를 더 좁히고 성공 기준 하나만 두고 다시 실행하세요. 결과가 너무 쪼개져 보인다면 병렬 agent 수를 줄이고 stage 간 dependency를 더 강하게 넣으세요. polyphony에서는 보통 더 긴 프롬프트보다 더 날카로운 orchestration 입력이 개선으로 이어집니다.