Claude Agent Teams는 잘 돌아가기 시작하는 순간과 혼란스러워지는 순간이 같습니다.

팀원 몇 명을 띄우고 작업이 병렬로 움직이기 시작하면… 다음 질문에 간단히 답할 수 없다는 걸 깨닫게 됩니다.

• 누가 무엇을 하고 있지?
• 누가 나를 기다리고 있지?
• 다음 메시지는 어디로 보내야 하지?

이걸 해결하지 않으면 팀은 지렛대가 아니라 스크롤처럼 느껴집니다.

이 가이드는 Claude Agent Teams를 명확하고 예측 가능하게 만드는 워크플로를 다룹니다. 명확한 라우팅, 예측 가능한 체크인, 그리고 촘촘한 "주의 루프"입니다.

요약

1. Claude Agent Teams를 트랜스크립트 문제가 아니라 메시지 라우팅 문제로 다룹니다.
2. 세 가지 "대상"을 기억합니다:
   • Lead(기본)
   • 특정 팀원
   • Broadcast(팀 전체에 메시지 하나)
3. 메시지가 어디로 갔는지 추측하지 마세요. 라우팅된 전송을 명시적으로 만드세요.
4. 휴대폰에서 팀원을 모니터링하고 라우팅된 메시지를 보내고 싶다면 Happier가 선택지 중 하나입니다. "Send to" 수신자 칩(Lead / Broadcast / 팀원)과 전용 Agents 목록을 제공합니다.

문제

Claude Teams가 어려운 건 Claude가 일을 못 해서가 아닙니다.

사람이 놓치기 때문입니다.

팀원이 여럿이 되면:

• Lead 트랜스크립트가 더 이상 전체 이야기가 아님
• 막혀 있는 팀원 하나를 놓칠 수 있음
• "빠르게 수정 사항 보내기"가 모호해짐(누구에게?)

그래서 진짜 풀어야 할 문제는 주의와 라우팅입니다.

일반적인 방법과 트레이드오프

• Lead와만 대화: 안전하지만 팀원의 이점 대부분을 잃습니다.
• 위로 스크롤해 해당 팀원의 출력 찾기: 되지만 규모가 커지면 안 됩니다.
• 팀원마다 창/탭 따로 쓰기: 낫지만 여전히 다음 지시를 엉뚱한 곳에 보내기 쉽습니다.

Happier가 처음이라면

Happier를 처음 본다면: 코딩 세션을 위한 오픈 소스 컴패니언 앱(모바일/웹/데스크톱)입니다.

이 가이드에서 관련 있는 부분은 간단합니다. Claude Agent Teams용 UI가 있어서:

• 팀원이 목록("Agents")으로 보임
• 작성기에 "Send to" 수신자 칩(Lead / Broadcast / 팀원)이 있음
• 라우팅된 전송이 카드로 표시됨(어디로 보냈는지 볼 수 있음)

설정하기:

• 휴대폰에서 Happier 사용하는 방법
• GitHub: https://github.com/happier-dev/happier
• 설치/다운로드: https://github.com/happier-dev/happier#how-it-works
• Discord (커뮤니티 + 지원): https://discord.gg/W6Pb8KuHfg

명확함을 유지하는 Claude Teams 사고 모델

Lead

Lead는 기본 대화입니다.

라우팅 없이 메시지를 보내면 Lead로 갑니다.

팀원

팀원은 Claude 팀의 특정 구성원입니다. 팀원에게 보내는 메시지는 명시적이어야 합니다.

Broadcast

Broadcast는 "팀 전체에 알리기" 채널입니다.

Happier 구현에서 Broadcast는 Claude 팀 ID에서 만들어지며, 팀이 있을 때 라우팅 대상으로 나타납니다.

실제로 쓸 수 있는 워크플로

1) 매번 재사용할 팀원 "역할" 2~3개 고르기

팀원이 매번 일회성이면 팀이 지저분해집니다.

재사용 가능한 역할 몇 개를 두고 매번 같은 프롬프트를 쓰세요.

합리적인 기본값:

• 리뷰어(diff 중심, 보수적)
• 테스터(테스트를 실행하고 가정을 깨 보려 함)
• 리팩터러(기계적인 코드 이동 담당)

역할은 더 추가할 수 있지만(문서, 분류, 릴리스 노트), 작게 시작하면 팀을 관리하기 쉽습니다.

2) 복사/붙여넣기 프롬프트로 팀원 만들기 (동작을 예측 가능하게)

팀원을 띄울 때 다음을 주세요.

• 역할
• 범위
• 멈춤 규칙
• 체크포인트 형식

재사용해도 잘 버티는 프롬프트입니다.

팀원 프롬프트: 리뷰어

너는 내 리뷰어야. 위험과 불일치를 찾는 게 네 일이야.

규칙:

• 변경하지 마. 리뷰만 해.
• 항상 목표가 무엇이라고 생각하는지 요약하며 시작해.
• 그다음 (1) 위험, (2) 빠진 테스트, (3) diff 개선 제안을 나열해.
• 확실하지 않으면 확인 질문을 하나 해.

팀원 프롬프트: 테스터

너는 내 테스터야.

규칙:

• 리팩터링하지 마. 실패 유형에 집중해.
• 먼저 최소한의 테스트 계획을 제안해.
• 그다음 계획을 실행해(또는 무엇을 실행할지 정확히 설명해).
• 실패하면 실패한 명령과 오류를 그대로 붙여 넣어.

팀원 프롬프트: 리팩터러

너는 내 리팩터러야.

규칙:

• 무엇이든 바꾸기 전에 3단계 계획을 제안해.
• 각 단계 후에 무엇이 바뀌었는지 요약해.
• 내가 명시적으로 말하지 않는 한 마이그레이션이나 인증은 건드리지 마.
• 위험한 변경이 필요하면 멈추고 물어봐.

3) 전체 제약에는 Broadcast 사용 (메시지 하나, 모두가 들음)

Broadcast는 팀 전체에 적용되어야 하는 제약에 잘 맞습니다.

• "마이그레이션은 건드리지 마."
• "다음 단계 후에 멈추고 요약해."
• "설치를 실행하려면 먼저 물어봐."

Broadcast는 세부 작업("파일 X를 바꾸고, 그다음 Y")에는 맞지 않습니다. 책임이 섞이기 때문입니다.

4) 세부 작업은 한 번에 팀원 하나에게 라우팅

팀원에게 특정 일을 시키고 싶으면 그 팀원에게 직접 보내세요.

도움이 되는 작은 습관: 메시지 끝에 확인 응답을 요구하세요.

예:

확인 응답: 지금 하는 일 + 다음에 할 일.

메시지가 엉뚱한 대상에 갔다면 바로 드러납니다.

5) Agents 사이드바를 팀 목록으로 쓰기 (이게 핵심)

Claude Teams를 관리하기 쉽게 만드는 Happier 고유의 부분입니다.

Claude 팀 세션에서 Happier는 세션 UI에 Agents 목록을 보여 줍니다.

여기서:

• Launch(새 팀원 띄우기)
• Active(현재 실행 중)
• Recent(완료/유휴)

그리고 각 에이전트 항목은 트랜스크립트의 한 줄이 아니라 실제로 "열 수 있는 것"입니다.

즉, 워크플로가 스크롤이 아니라 목록에서 시작합니다.

습관: 세션을 열면 먼저 Agents 사이드바/창을 엽니다.

6) 팀원을 열어 무엇을 하는지 보기 (맥락을 잃지 않고)

Agents 목록에서:

• 팀원을 탭/클릭

Happier가 그 팀원의 화면을 열어 다음을 볼 수 있습니다.

• 트랜스크립트
• 도구 활동
• 나를 기다리는지 여부

이게 Claude Teams가 "긴 스크롤 기록에서 맞는 메시지 찾기"로 변하는 걸 막아 줍니다.

7) 특정 팀원에게 메시지 보내기 (Lead가 아니라)

메시지 작성기에 Send to 수신자 칩이 있습니다.

다음 메시지를 보낼 곳을 고를 수 있습니다.

• Lead(기본)
• 특정 팀원
• Broadcast(팀 전체)

팀원을 고르면 메시지는 그 팀원에게 갑니다.

이게 Happier의 팀 UX에서 큰 장점입니다. 라우팅이 명시적입니다.

8) "2분 체크인" 루프 쓰기 (특히 휴대폰에서)

휴대폰에서 통하는 워크플로는 일부러 단순합니다.

1. 세션을 엽니다.
2. Agents 목록을 엽니다.
3. 주의가 필요한 것을 찾습니다.
4. 메시지 하나를 라우팅합니다(또는 제약 하나를 Broadcast).
5. 앱을 닫습니다.

휴대폰에서 그 이상을 하려 하면 결정의 질이 떨어집니다.

9) 보낸 뒤 라우팅을 확인하는 법 익히기

메시지가 어디로 갔는지 증명할 수 있어야 합니다.

Happier에서 라우팅된 전송은 수신자 라벨이 분명한 메시지 카드로 표시됩니다(예: "To: Lead", "To: Broadcast …", "To: reviewer").

이 작은 UI 디테일이 "리뷰어한테 말한 것 같은데…" 하는 혼란을 막아 줍니다.

문제 해결

팀원이 조용함

흔한 원인:

• 아직 작업 중(체크포인트 요청)
• 권한/입력을 기다리며 막혀 있음
• 깊이 빠져들었음(멈추고 요약하라고 보내기)

좋은 구조 메시지:

멈춰. 한 일, 다음에 하려던 일, 나에게 필요한 걸 요약해.

두 팀원이 같은 일을 하고 있음

보통 다음 경우에 생깁니다.

• 작업을 대상 지정 라우팅 대신 Broadcast로 보냄
• Lead가 작업을 모호하게 전달함

해결:

• 담당자를 하나로 정하기("리뷰는 리뷰어, 편집은 리팩터러")
• 그 담당 규칙을 한 번 Broadcast

Broadcast가 시끄럽게 느껴짐

Broadcast는 제약과 조율용이지 작업 배정용이 아닙니다.

"X를 해"를 Broadcast에 넣고 있다면, 대상 지정 팀원 메시지로 되돌리세요.

FAQ

항상 팀원 셋을 써야 하나요?

아니요. 하나로 시작하세요.

가치의 대부분은 다음에서 나옵니다.

• 위험을 잡아내는 리뷰어 팀원 하나, 또는
• 깨지기 쉬운 변경을 막는 테스터 팀원 하나.

Lead는 무엇을 해야 하나요?

Lead에 맞는 일:

• 조율
• 팀원 출력 간의 충돌 해결
• 메인 구현 스레드를 위한 최종 "이렇게 해" 지시 작성

흔한 실수

• 대상이 정해진 작업을 Broadcast로 보내기
• 전체 제약을 팀원 하나에게만 보내기
• 체크포인트 요약을 한 번도 요청하지 않기

관련 가이드

• Claude Code, Codex, OpenCode 중 어떤 세션이 멈췄는지 구분하는 방법(터미널 10개를 확인하지 않고)