URL: https://zenn.dev/neurostack_0001/articles/agent-teams-one-week-redefine-work

Agent Teams＋Skills로 에이전트 3명과 1주일 일해봤더니, ‘내 일’이 재정의됐다

「AI에게 지시하는 쪽」이라고 생각했는데, 병목은 나였다

Claude Code를 쓰기 시작한 지 반년. 나는 스스로를 “AI를 잘 다루는 쪽”이라고 생각했다. 프롬프트를 쓰고, 코드를 생성하게 하고, 리뷰하고, 머지한다. 효율은 분명 올라가 있었다.

그런데 어느 날 깨달았다. 매번 같은 리뷰 지적을 말로 전달하고 있는 나가 있다는 것에. AI에게 “리뷰해줘”라고 부탁해도 관점이 흔들린다. 테스트를 쓰게 해도 전략이 없다. 결국 모든 판단은 내가 내리고 있었고, AI는 “조금 똑똑한 코드 생성기” 수준에 머물러 있었다.

그래서 시도한 것이 Agent Teams와 Skills를 조합한 운용이다. 1주일 실무에 투입해 본 결론을 말하자면, 바뀐 것은 도구가 아니라 내 일의 정의였다.

Agent Teams란?

Agent Teams는 여러 Claude Code 인스턴스가 하나의 팀으로 협업하는 메커니즘이다. 기존 Claude Code는 하나의 세션에서 1명의 AI와 대화하는 스타일이었지만, Agent Teams에서는 “리드 + 여러 팀메이트” 구성으로, 각 멤버가 독립된 컨텍스트를 유지한 채 병렬로 작업한다.

아키텍처

핵심은 각 멤버가 독립된 컨텍스트 창을 가진다는 점이다. 사람 팀 개발과 마찬가지로, 구현 담당이 묵묵히 코드를 쓰는 동안 리뷰어는 다른 파일을 확인하고, 테스트 설계자는 테스트 전략을 고민한다──이것이 정말로 병렬로 진행된다.

서브 에이전트와의 차이

Claude Code에는 기존부터 “서브 에이전트”( .claude/agents/ 로 정의하는 커스텀 에이전트)가 있었지만, Agent Teams는 근본적으로 다른 구조다.

구분 기준:

• 서브 에이전트에 적합: 결과만 있으면 되는 정형 작업(파일 탐색, 단발 리뷰, 테스트 실행 등)
• Agent Teams에 적합: 멤버 간 논의·협업이 필요한 복잡 작업(기능 개발, 리팩터링, 병렬 리뷰 등)

이 글에서는 Agent Teams + Skills 조합에 집중해, 1주일 실험 결과를 공유한다.

실험 설계: 3명의 에이전트 팀

이번에는 아래 3명 구성으로 1주일 운영했다.

• Implementer(구현 담당): 코드를 작성하는 주력
• Reviewer(리뷰어): 보안·성능 관점 리뷰
• Tester(테스트 설계자): 테스트 전략 수립과 구현

단순히 “3인 팀을 만들어”라고 지시하는 게 아니라, Skills로 팀메이트의 판단 기준을 정비하고, Agent Teams로 자연어로 팀 구성을 지시한다──이 조합이 포인트다.

Step 1: Skills로 리뷰 기준과 테스트 전략을 정의

CLAUDE.md에 전부 쓰면 비대해지고, 팀메이트마다 필요한 지식도 다르다. Skills를 쓰면 필요한 지식만 정리해 공유할 수 있다. Skills는 Agent Teams의 팀메이트에도 상속되므로 팀 전체의 공통 자산이 된다.

.claude/skills/review-checklist/SKILL.md:

---
name: review-checklist
description: 코드 리뷰의 기준 체크리스트
user-invocable: false
---

## 리뷰 체크리스트

### 보안
- [ ] 사용자 입력 검증·새니타이즈
- [ ] SQL 인젝션 대책(파라미터 바인딩)
- [ ] XSS 대책(출력 이스케이프)
- [ ] 인증·인가 체크 누락
- [ ] 기밀 정보 하드코딩(API 키, 비밀번호)

### 성능
- [ ] N+1 쿼리 존재 여부
- [ ] 불필요한 리렌더링(React: useCallback/useMemo)
- [ ] 대량 데이터의 비효율 처리(메모리 내 정렬 등)
- [ ] 인덱스 없는 DB 쿼리

### 유지보수성
- [ ] 함수·변수 명명에 의도가 드러나는가
- [ ] 한 함수가 50줄을 넘지 않는가
- [ ] 매직 넘버 제거
- [ ] 중복 코드 존재 여부

.claude/skills/test-strategy/SKILL.md:

---
name: test-strategy
description: 테스트 설계의 방침과 기준
user-invocable: false
---

## 테스트 설계 방침

### 커버리지 목표
- 유닛 테스트: 80% 이상
- 통합 테스트: 주요 유스케이스를 모두 커버
- E2E 테스트: 크리티컬 패스만

### 우선해야 할 테스트 관점
1. 정상계 주요 플로우
2. 밸리데이션 에러(입력 경계값)
3. 인증·인가 경계(미로그인, 권한 부족)
4. 비동기 처리의 에러 핸들링
5. Race condition이 발생할 수 있는 지점

### 테스트 작성 방식
- Arrange-Act-Assert 패턴으로 통일
- 테스트 이름은 “무엇을 하면 무엇이 일어나는가”를 일본어로 작성
- 목은 최소한으로(외부 API·DB 연결만)

user-invocable: false로 한 것이 포인트다. 이는 사용자가 /review-checklist로 호출하는 것이 아니라, 에이전트에 자동 주입되는 전문 지식으로 사용한다. Agent Teams의 팀메이트에는 프로젝트 Skills로 상속된다.

Step 2: Agent Teams 활성화 후 실행

settings.json에서 Agent Teams를 활성화한다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

그리고 Agent Teams를 시작하는 프롬프트:

에이전트 팀을 생성해 인증 모듈 리팩터링에 착수해 주세요.

3명의 팀메이트를 생성:
- 구현 담당: src/auth/ 하위 리팩터링. JWT 처리 단순화와 에러 핸들링 통일을 담당
- 리뷰어: 시니어 코드 리뷰어처럼 행동. review-checklist Skill을 따르며 보안(OWASP Top 10)·성능(N+1, 메모리 누수)·유지보수성 3관점으로 리뷰. Critical / Warning / Suggestion 3단계로 보고할 것
- 테스트 설계자: 테스트 설계 전문가처럼 행동. test-strategy Skill을 따르며 유닛 테스트→통합 테스트→E2E 우선순위로 테스트 전략을 수립·구현

구현 담당 태스크를 아래로 분할:
1. JWT 검증 로직 공통화
2. 에러 응답 통일
3. 토큰 리프레시 처리 개선
4. 로그아웃 처리 단순화
5. 타입 정의 정리

각 멤버는 서로의 진행을 공유하고, 문제가 있으면 논의해 주세요.
리뷰어는 plan approval을 필수로 하고, 구현 전에 리뷰를 통과시키세요.

Day 1-3: 움직이기 시작하며 보인 Skills의 위력

Skills가 먹힌 순간

가장 “오” 싶었던 순간은, 리뷰어가 Skills 체크리스트에 따라 구조화된 리뷰를 돌려줬을 때였다.

## Critical
- src/auth/login.ts:42 - 비밀번호 해시 비교가 타이밍 공격에 취약
  → crypto.timingSafeEqual()을 사용하세요

## Warning
- src/auth/token.ts:15 - JWT 유효기간 24h는 너무 김
  → 액세스 토큰 15분, 리프레시 토큰 7일 권장

## Suggestion
- src/auth/middleware.ts:8 - 인증 미들웨어 함수명 `check`가 모호
  → `requireAuthentication`으로 변경 제안

Skills를 주입하지 않았을 때는 “전체적으로 좋아요. 몇 가지 개선점이 있어요” 같은 두루뭉술한 리뷰였는데, 체크리스트 하나만 있어도 구체성이 차원이 달라졌다.

Day 4-5: 팀워크 최적화

delegate mode로 사람은 “방향만 정한다”

에이전트끼리 논의가 활발해지면 사람이 전체를 파악하기가 어려워진다. 여기서 효과가 있었던 것이 delegate mode(Shift+Tab)다.

리드 에이전트는 조정 역할에 전념시키고, 사람은 Shift+Up/Down으로 멤버를 선택해 직접 지시한다. 이 운용으로 바꾼 뒤 “사람 = 태스크를 실행하는 사람”에서 “사람 = 방향을 정하고 품질을 판단하는 사람”으로 완전히 전환할 수 있었다.

병렬 리뷰를 Skill로 만들기

PR 리뷰가 특히 효과적이어서, 반복 사용 가능하도록 Skill로 만들었다.

.claude/skills/parallel-review/SKILL.md:

---
name: parallel-review
description: PR을 3가지 관점에서 병렬 리뷰하는 에이전트 팀을 실행
disable-model-invocation: true
---

PR을 리뷰하는 에이전트 팀을 생성해 주세요.

3명의 리뷰어를 생성:
- 보안 담당: OWASP Top 10 관점으로 리뷰
- 성능 담당: N+1 쿼리, 메모리 누수, 불필요한 리렌더링을 체크
- 테스트 담당: 테스트 커버리지 검증, 엣지 케이스 누락 지적

대상: $ARGUMENTS

각 리뷰어는 review-checklist Skill 기준에 따라 Critical / Warning / Suggestion 3단계로 보고할 것.
리뷰 완료 후, 리드가 3관점을 통합해 요약을 작성해 주세요.

이제 /parallel-review #142라고 치기만 하면 3관점 병렬 리뷰가 돈다. disable-model-invocation: true로 해 두었기 때문에, 내가 명시적으로 호출했을 때만 실행된다.

Agent Teams의 주요 제한 사항(작성 시점)

• 세션 재개 불가: in-process로 생성된 Teammates는 세션 종료 시 소멸한다. 중간부터 재개할 수 없다
• 1세션 1팀: 동시에 여러 팀을 생성·운용할 수 없다
• 중첩 불가: Teammates(멤버)가 스스로 팀을 만들 수 없다. 팀을 만들 수 있는 것은 리드뿐
• 리드 고정: 리드 에이전트의 승격·위임은 불가. 리드는 항상 팀을 만든 에이전트다
• VS Code Terminal 등에서의 페인 분할 미지원: Agent Teams UI는 Claude Code CLI 사용을 전제로 한다

Day 6-7: 회고 ── 사람이 해야 할 일은 무엇이었나

1주일 해 보니, 사람의 일이 명확히 바뀌었다.

특히 실감한 건 “많이 만드는 힘”에서 “어떤 미래를 선택할지 설계하는 힘”으로의 전환이다. AI가 3가지 구현안을 내준다. 사람은 “무엇을 선택할지”, “왜 그것을 선택할지”를 판단한다. 이 **‘선택하는 힘’**이야말로 에이전트 시대에 가장 가치 있는 스킬이라고 느꼈다.

내일부터 시작하는 2단계

Step 1: Skills로 판단 기준을 분리한다

CLAUDE.md에 전부 쓰는 것을 그만두고, Skills로 분리하자. 필요한 지식을 정리해 공유하면 팀메이트 출력의 질이 압도적으로 좋아진다.

.claude/
└── skills/
    ├── review-checklist/
    │   └── SKILL.md      # 리뷰 기준
    └── test-strategy/
        └── SKILL.md      # 테스트 방침

Step 2: Agent Teams로 병렬화한다

Skills가 안정되면 Agent Teams로 병렬화해 보자. 팀메이트는 프롬프트로 자연어로 역할을 지시해 동적으로 생성한다. Step 1에서 정비한 Skills는 팀메이트에도 상속되므로 그대로 활용할 수 있다. 반복해서 쓰는 패턴은 Skill화(/parallel-review 등)해 두면, 명령 한 번으로 실행할 수 있다.

정리

1주일 실험에서 배운 것은 단순하다.

• CLAUDE.md만 의존하지 말 것. .claude/skills/로 판단 기준을 분리하면, 팀메이트 전원이 같은 품질 기준으로 움직일 수 있다
• Agent Teams는 ‘사람이 선택하기’ 위한 구조다. 병렬로 움직이고, 사람은 결과를 보고 판단한다

바뀐 것은 도구가 아니라 “내 일의 정의”였다. 코드를 쓰는 사람에서 팀의 전문성을 설계하고, 결과를 선택하는 사람으로. 처음엔 당황하지만, 이 경험은 되돌릴 수 없다.

참고 링크

• Claude Code Agent Teams 공식 문서
• Skills 공식 문서