team-composition-patterns

team-composition-patterns 스킬 개요

team-composition-patterns는 Claude Code Agent Teams에서 멀티 에이전트 팀을 설계하기 위한 의사결정 스킬로, 팀 규모 휴리스틱, 에이전트 타입 선택, 표시 모드 선택을 다룹니다. 팀 구성을 매번 즉흥적으로 “에이전트 몇 명 생성” 수준으로 처리하기보다, 리뷰·디버깅·기능 전달에 재사용 가능한 팀 셋업이 필요한 빌더에게 team-composition-patterns가 특히 잘 맞습니다.

team-composition-patterns 스킬이 결정해 주는 것

도입 시 막히는 세 가지를 해결합니다: 에이전트를 몇 명 쓸지, 각 역할에 맞는 subagent_type이 무엇인지, 환경에 맞는 표시 모드(tmux, iTerm2, in‑process)가 무엇인지입니다.

최적의 사용 시나리오와 기대 결과

코드 리뷰, 버그 조사, 기능 구현처럼 반복되는 작업에서 일관된 팀 구성이 필요할 때 쓰세요. 매번 역할을 다시 고민하지 않고, 재사용 가능한 프리셋 팀을 활용할 수 있습니다.

범용 프롬프트 대비 차별점

일반적인 “팀 만들어줘” 프롬프트와 달리, team-composition-patterns는 팀 규모 휴리스틱, 프리셋 구성, 에이전트 역량에 맞춘 subagent_type 결정 매트릭스를 제공합니다.

적합하지 않은 경우

Claude Code Agent Teams를 쓰지 않거나, 단일 어시스턴트로 충분한 단순 작업만 한다면 team-composition-patterns는 오히려 오버헤드가 됩니다.

team-composition-patterns 스킬 사용 방법

team-composition-patterns 설치 및 시작점

다음 명령으로 설치합니다: npx skills add https://github.com/wshobson/agents --skill team-composition-patterns. 핵심 가이드는 plugins/agent-teams/skills/team-composition-patterns/SKILL.md에 있습니다.

도입 판단을 위해 먼저 읽을 파일

SKILL.md를 먼저 읽고, subagent_type 결정 매트릭스는 references/agent-type-selection.md, готовые 팀 구성과 작업 템플릿은 references/preset-teams.md를 확인하세요.

스킬에 제공해야 할 입력

작업 유형(리뷰/디버그/기능/마이그레이션), 복잡도, 제약(CI vs 로컬), 에이전트의 쓰기 권한 필요 여부를 제공하세요. 이 정보가 팀 규모와 subagent_type 선택으로 직접 연결됩니다.

거친 목표를 강한 프롬프트로 바꾸기

약함: “spawn a team to review this PR.”
강함: “Review 6-file diff touching auth and caching; prioritize security and performance; local dev; need file:line findings and fixes.” 이렇게 하면 스킬이 리뷰 팀 프리셋과 리뷰어 차원을 정확히 선택할 수 있습니다.

과도/부족 생성 방지를 위한 팀 규모 휴리스틱

복잡도에 맞춰 팀 규모를 정하세요: 단순(1–2), 보통(2–3), 복잡(3–4+). 코드 분량이 큰 것보다, 보안+성능+아키텍처처럼 여러 차원이 동시에 중요한 경우에 큰 팀이 유리합니다.

에이전트 타입 결정 매트릭스 활용

references/agent-type-selection.md를 기준으로 subagent_type을 선택하세요. 예: 코드 리뷰 → agent-teams:team-reviewer; 버그 조사 → agent-teams:team-debugger; 수정 없는 아키텍처 탐색 → Plan 또는 Explore.

프리셋 팀 구성부터 적용

리뷰/디버그 프리셋 팀 정의가 가장 빠른 가치 경로입니다. 역할, 집중 영역, 구조화된 작업 템플릿이 포함되어 각 에이전트의 담당 차원과 출력 형식을 명확히 합니다.

환경에 맞는 표시 모드 선택

여러 동시 출력이 필요하고 터미널 패널을 다룰 수 있다면 tmux를 권장합니다. 가벼운 구성이라면 iTerm2 또는 in‑process 출력이 마찰을 줄입니다.

team-composition-patterns 사용을 위한 권장 워크플로

1. 작업 유형과 복잡도를 분류합니다.
2. 차원에 맞는 프리셋 팀 또는 커스텀 팀을 선택합니다.
3. 각 역할에 subagent_type을 할당합니다.
4. 환경에 맞는 표시 모드를 고릅니다.
5. 각 팀원에게 구조화된 작업 템플릿을 제공합니다.

team-composition-patterns 스킬 FAQ

team-composition-patterns 스킬은 Claude Code Agent Teams 전용인가요?

네. subagent_type과 표시 모드 같은 Agent Teams 개념을 전제로 설계됐습니다. 해당 환경이 없으면 가이드를 실행으로 옮기기 어렵습니다.

일반 “팀 만들어줘” 프롬프트와 무엇이 다른가요?

팀 규모 결정 규칙, 에이전트 타입 선택 매트릭스, 작업 템플릿이 포함된 구체적 프리셋 팀을 제공합니다. 범용 프롬프트에 없는 요소들입니다.

초보자에게도 쉬운가요?

프리셋 팀을 따르면 충분히 시작할 수 있습니다. 결정 매트릭스가 촘촘하게 느껴질 수 있지만, 탐색용 에이전트에 쓰기 권한을 주는 실수 같은 일반적인 오류를 예방합니다.

언제 피해야 하나요?

단발성·저위험 작업에서 일반 목적 단일 에이전트가 충분할 때는 피하세요. 조율 오버헤드가 이득을 넘을 수 있습니다.

마이그레이션이나 감사 같은 커스텀 워크플로도 지원하나요?

네. 비표준 워크플로도 명시적으로 다룹니다. 차원을 조합하고 적절한 subagent_type 역할을 선택해 커스텀 팀 구성을 만들면 됩니다.

team-composition-patterns 스킬 개선 방법

더 나은 팀 설계를 위한 작업 차원 명확화

리뷰 차원(보안, 성능, 아키텍처, 테스트)을 명확히 지정하세요. 차원이 분명할수록 프리셋 리뷰어 역할 매핑이 정확해지고 중복이 줄어듭니다.

흔한 실패 모드 피하기

실패 모드: 잘못된 subagent_type 선택(예: 수정이 필요한 작업에 Plan 지정). 해결책은 에이전트가 파일을 작성해야 하는지 명확히 적고, 결정 매트릭스를 따르는 것입니다.

더 강한 입력 컨텍스트로 출력 개선

“multi-file change”, “cross-cutting concern”, “CI-only environment” 같은 범위 संकेत를 포함하세요. 이 정보가 팀 규모와 표시 모드 추천을 바꿉니다.

첫 팀 제안 후 반복 개선

결과가 얕으면 누락된 차원(예: accessibility)을 추가하거나 팀 규모를 1명 늘리세요. 응답이 중복되면 팀 규모를 줄이거나 범위를 좁히세요.

조직용 재사용 템플릿 만들기

references/preset-teams.md의 작업 템플릿을 레포 관례(파일 경로, 출력 형식, 심각도 레벨)에 맞게 수정하세요. 그러면 team-composition-patterns 가이드를 안정적인 내부 워크플로로 만들 수 있습니다.

Agent Orchestration 결정에 team-composition-patterns 활용

여러 작업 스트림을 동시에 조율할 때 team-composition-patterns로 역할과 역량을 표준화해, 각 스트림에 reviewer, debugger, implementer, lead의 적절한 조합을 확보하세요.