클로드 코드 에이전트 팀 사용법, 역할별 AI 팀으로 개발 자동화하기

개발 테크

2시간 전

조회수

클로드 코드 에이전트 팀은 클로드 코드를 사용할 때 여러 개의 AI 에이전트를 역할별로 구성해 하나의 작업을 협업 형태로 수행하도록 설계하는 개발 방식입니다.

각 에이전트가 맡은 업무를 병렬적으로 수행하도록 구성할 수 있어, 복잡한 기능 개발, 반복적인 코드 수정, 테스트 검증, 문서 정리처럼 여러 단계가 필요한 작업에서 유용합니다.

미리 역할과 규칙을 정의해두면 에이전트가 임의로 움직이는 것을 줄이고, 더 일관된 흐름으로 결과물을 만들 수 있습니다.

이 글에서는 클로드 코드 에이전트 팀이 어떤 구조로 이루어져있고, 어떻게 구성하면 좋은지, 그리고 실제 개발 환경에서 어떻게 활용할 수 있는지를 중심으로 정리해보겠습니다.

클로드 코드 에이전트 팀 사용법 핵심 요약

에이전트 팀은 단일 에이전트의 한계를 보완합니다. 하나의 에이전트가 모든 작업을 처리하는 대신, 역할별 에이전트가 기획·구현·검증을 나누어 더 세밀한 결과를 만들 수 있습니다.
에이전트 팀은 활성화만으로 완성되지 않습니다. Agent Teams를 켠 뒤 역할을 구성하고 /agents에서 역할별 에이전트를 생성해야 작업 배정 오류를 줄일 수 있습니다.
하네스 엔지니어링이 결과 품질을 좌우합니다. 하네스엔지니어링으로 역할, 금지 작업, 산출물 형식, 검증 기준을 정의하면 에이전트가 일관된 기준으로 움직일 수 있습니다.
에이전트 팀은 복잡한 작업에 적합합니다. 간단한 수정에는 단일 에이전트가 더 효율적일 수 있으며, 에이전트 팀은 비용 증가와 최종 검토 필요성을 함께 고려해야 합니다.

클로드 코드 에이전트 팀이란?

클로드 코드 에이전트 팀(Claude Code Agent Teams)은 사전에 정의된 규칙과 도구를 바탕으로 여러 에이전트가 스스로 판단하고 협업하는 자율형 AI 시스템입니다. 코딩, 리서치, 테스트 등 복잡한 업무를 자동화하는 데 최적화되어 있습니다.

역할별 에이전트를 구성해 팀 리드와 여러 팀원 에이전트가 각자의 업무를 나누어 진행하는 구조입로 단일 에이전트만으로 진행했을 때 놓치기 쉬운 부분을 보완할 수 있습니다.

각 에이전트가 자신의 영역에 집중하고, 팀 리드가 결과물을 조율하기 때문에 사용자 요구에 더 세밀하게 맞춘 결과물을 만들 수 있습니다.

즉, 에이전트 팀은 단순히 AI를 여러 개 사용하는 방식이 아니라, 단일 에이전트가 놓치기 쉬운 디테일과 검증 과정을 역할 분담과 병렬 구조로 보완하는 방식입니다.

클로드 코드 에이전트 팀의 구성요소

클로드 코드 에이전트 팀은 여러 Claude Code 세션을 팀처럼 구성해 복잡한 작업을 역할별로 나누어 처리하는 구조로 팀 리드와 팀원 에이전트가 함께 움직이며 공유 작업 목록, 메시징, 실행 도구를 통해 협업합니다.

1. 팀 리드 에이전트

팀 리드 에이전트는 사용자의 명령을 이해하고 전체 작업 방향을 조율하는 중심 역할을 합니다. “신규 앱을 기획해줘”, “기능 구현과 테스트까지 진행해줘”처럼 요청하면 작업을 어떤 순서로 나눌지 판단하고, 각 팀원 에이전트에게 역할을 배정합니다. 쉽게 말해 Claude Code Agent Teams 안에서 프로젝트 매니저처럼 전체 흐름을 관리하는 역할입니다.

2. 팀원 에이전트

팀원 에이전트는 팀 리드가 배정한 역할에 따라 각자 독립된 컨텍스트에서 작업을 수행합니다. 예를 들어 시장 분석가, 기능 기획자, 프론트엔드 개발자, 백엔드 개발자, QA 담당자처럼 역할을 나눌 수 있습니다.

각 팀원은 자신의 작업 공간에서 파일을 분석하고 결과물을 만든 뒤, 팀 리드나 다른 팀원에게 작업 내용을 전달합니다.

3. 프로젝트 코드베이스와 실행 도구

Agent Teams의 각 에이전트는 프로젝트 폴더를 기준으로 파일 구조와 코드 흐름을 확인합니다. 또한 파일 읽기, 코드 수정, 터미널 명령 실행 같은 도구를 활용해 실제 작업을 진행할 수 있습니다.

예를 들어 프론트엔드 에이전트는 화면 관련 파일을 수정하고, QA 에이전트는 테스트 명령을 실행해 결과를 확인하는 방식으로 역할을 나눌 수 있습니다.

4. 하네스 엔지니어링

하네스 엔지니어링은 에이전트가 어떤 기준으로 판단하고 움직일지 미리 설계하는 과정을 말합니다. 에이전트가 임의로 판단해 엉뚱한 방향으로 작업하는 것을 줄이고, 여러 에이전트가 일관된 기준으로 결과물을 만들 수 있도록 돕는 핵심 장치 역할을 합니다.

예를 들어 CLAUDE.md에는 프로젝트 목표, 에이전트의 역할, 사용할 도구, 출력 형식, 작업 순서, 검증 기준 등을 구체적으로 정의해둘 수 있습니다. 필요하다면 agent.md 같은 별도 마크다운 파일을 만들어 팀 리드와 팀원 에이전트의 역할, 파일 소유권, 릴레이 순서까지 더 자세히 정리할 수 있습니다.

5. 확장 기능

작업이 복잡해질 때는 Subagent, Skills, MCP 같은 확장 기능을 함께 활용할 수 있습니다. Subagent는 단일 Claude Code 세션 안에서 특정 작업을 맡아 격리된 컨텍스트로 처리하고 요약을 반환하는 보조 기능입니다.

Skills는 특정 작업을 반복적으로 수행하기 위한 재사용 가능한 지식과 워크플로우를 추가하는 기능이고, MCP는 Claude Code를 외부 도구나 데이터 소스와 연결하는 확장 방식입니다. 이 기능들을 함께 활용하면 에이전트 팀의 자동화 범위를 더 넓힐 수 있습니다.

클로드 코드 에이전트 팀은 어떻게 실행할까?

에이전트 팀 실행 5단계

클로드 코드 에이전트 팀은 어떻게 실행되는 단계를 5단계로 나눠서 정리했습니다.

클로드 코드 에이전트 팀을 효율적으로 활용하려면 에이전트 팀이 실행되는 5단계 흐름을 먼저 이해해야 합니다. 이 흐름을 제대로 잡아야 역할이 섞이거나 잘못된 에이전트에게 작업이 배정되는 문제를 줄일 수 있습니다.

1. Agent Teams 기능을 활성화합니다

에이전트 팀을 실행하려면 먼저 Claude Code에서 Agent Teams 기능을 활성화해야 합니다. 이 단계는 여러 에이전트를 팀처럼 운영할 수 있는 환경을 여는 과정입니다.

2. 에이전트 역할을 구성합니다

다음으로 어떤 역할의 에이전트가 필요한지 정리합니다. 사용자의 목적에 맞게 팀 리드, 시장 분석가, 기능 기획자, 개발자, QA 담당자, PPT 작성자처럼 역할을 나눌 수 있습니다. 이때 각 역할이 맡을 업무와 맡지 않을 업무까지 함께 정리해두는 것이 좋습니다.

3. 역할별 에이전트를 생성합니다

역할 구성이 끝나면 /agents에서 실제 역할별 에이전트를 생성합니다. 각 역할에 맞는 전담 에이전트를 만들어두면 작업이 general-purpose로 넘어가거나, 다른 에이전트에게 잘못 배정되는 문제를 줄일 수 있습니다.

4. 하네스 엔지니어링으로 규칙을 정의합니다

역할별 에이전트를 만든 뒤에는 각 에이전트가 어떤 기준으로 움직일지 정리해야 합니다. 이 과정을 하네스 엔지니어링이라고 합니다. CLAUDE.md에 에이전트의 역할, 작업 범위, 금지 작업, 산출물 형식, 작업 순서, 검증 기준을 정의해두면 에이전트가 임의로 판단해 엉뚱한 방향으로 작업하는 것을 줄일 수 있습니다.

5. 규칙 파일을 기준으로 에이전트 팀을 실행합니다

역할과 규칙을 정리했다면 이제 에이전트 팀을 실행합니다. Claude Code는 CLAUDE.md 또는 AGENTS.md에 작성된 규칙을 기준으로 팀을 실행할 수 있습니다.

이때 단순히 "에이전트 팀으로 진행해줘"라고 요청하기보다, 정의된 역할과 규칙을 기준으로 작업하라고 지시하는 것이 좋습니다. 특히 전담 에이전트가 있는 작업은 general-purpose에 넘기지 않도록 명확히 말해두면 역할 오류를 줄일 수 있습니다.

클로드 코드 에이전트 팀 사용법

- 신규 앱 기획 에이전트 팀 만들기

클로드 코드 에이전트 팀이 실행되는 5단계를 ‘신규 앱 기획 에이전트 팀 만들기’를 예시로 정리했습니다. 아래 순서대로 따라하면 에이전트 팀을 직접 구성하고 실행할 수 있습니다.

1.Agent Teams 활성화하기

에이전트 팀을 사용하려면 먼저 Claude Code 설정에서 Agent Teams 기능을 활성화해야 합니다.

Agent Teams는 기본적으로 꺼져 있는 실험적 기능이기 때문에, 사용 전 설정 파일이나 환경 변수에 활성화 값을 추가해야 합니다. 순서는 아래와 같습니다.

1. Claude Code 버전 확인

claude --version

Agent Teams는 Claude Code v2.1.32 이상에서 사용할 수 있습니다. 위의 명령어를 사용해 버전을 확인합니다. 버전이 낮다면 Claude Code를 업데이트한 뒤 진행합니다.

2. Agent Teams 활성화 설정 추가

~/.claude/settings.json 파일을 열고 아래 내용을 추가합니다.

{

"env": {

"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"

}

이미 settings.json에 다른 설정이 있다면 기존 JSON 구조를 유지하면서 env 항목만 추가하면 됩니다.

3. Claude Code를 다시 실행한 뒤 팀 생성 요청

설정을 추가한 뒤에는 Claude Code를 새로 실행합니다. 이후 Claude Code 안에서 자연어로 에이전트 팀 생성을 요청하면 됩니다.

2. 에이전트 별 역할 구성하기

Agents Teams가 완성되었다면 이제 작업을 진행할 역할별 에이전트를 생성합니다. 신규 앱 기획 에이전트 팀을 구성하기 위해 각 구성원의 역할을 정리했습니다. 역할은 아래와 같습니다.

팀 리드: 전체 프로젝트의 방향을 설정하고 팀원 간 업무를 조율하며 최종 의사결정을 내립니다.
시장 분석가: 시장 트렌드와 경쟁사를 분석해 제품이 나아갈 방향의 근거를 만듭니다.
기능 기획자: 사용자 요구사항을 정리해 어떤 기능을 어떻게 만들지 구체적으로 정의합니다.
프론트엔드 개발자: 사용자가 실제로 보고 조작하는 화면을 구현합니다.
백엔드 개발자: 서버, 데이터베이스, API 등 서비스의 내부 로직을 구축합니다.
QA 담당자: 제품 출시 전 버그와 오류를 발견하고 품질 기준 충족 여부를 검증합니다.
PPT 작성자: 프로젝트의 내용과 결과를 시각적으로 정리해 PPT 용 발표 자료로 정리합니다.

3. 에이전트 역할 생성하기

에이전트 별 역할 구성이 완료되었다면 이제 클로드 코드를 실행해 역할 별 에이전트를 생성합니다.

클로드 코드 설치부터 실행 방법 보러가기

클로드 코드가 실행되면 /agents를 입력합니다. Agents 탭에서 Library를 선택한 뒤 Create new agent를 누릅니다.

Agents 탭에서 Create new agent를 선택하면 저장 위치를 선택하는 화면이 나옵니다. Project와 Personal 두 가지 옵션이 있습니다.

Project는 현재 프로젝트 폴더 안의 .claude/agents/에 에이전트를 저장합니다. git으로 관리되기 때문에 팀원과 공유할 수 있고, 해당 프로젝트 안에서만 동작합니다. 팀 단위로 동일한 에이전트를 쓰거나 프로젝트 특성에 맞게 구성을 고정하고 싶을 때 적합합니다.

Personal은 홈 디렉토리의 ~/.claude/agents/에 저장됩니다. 특정 프로젝트에 종속되지 않고 모든 작업 환경에서 불러올 수 있습니다. 나만의 작업 방식을 에이전트로 정형화해두고 어디서든 재사용하고 싶다면 Personal을 선택하면 됩니다.

에이전트 생성 방식을 선택하는 화면이 나옵니다. 옵션은 아래와 같습니다.

Generate with Claude: 어떤 에이전트가 필요한지 설명하면 Claude가 자동으로 설정을 생성해줍니다.
Manual configuration: 이름, 역할, 사용할 툴 등을 직접 하나하나 입력합니다.

1번 'Generate with Claude'를 선택합니다.

클로드 코드에서 Agent 생성을 위해 에이전트 역할을 입력하고 있습니다.

에이전트 생성 방식을 선택하면 에이전트 역할을 입력하는 창이 나옵니다. 각 역할에 맞는 내용을 설명하면 Claude Code가 분석한 뒤 해당 역할에 맞는 에이전트를 생성합니다.

여기서는 에이전트 팀 전체를 조율하는 지휘자 역할이 필요하기 때문에 팀 구성원과 각 역할을 입력한 뒤 마지막에 오케스트레이션 구조로 만들어달라는 내용을 추가합니다.

클로드 코드에서 에이전트를 생성할 때 에이전트가 사용할 툴을 선택하는 화면입니다.

에이전트가 사용할 툴을 선택하는 화면이 나옵니다. 기본값으로 모든 툴이 선택된 상태이므로 그대로 Continue를 선택합니다.

클로드 코드에서 에이전트를 생성할 때 에이전트에 사용할 모델을 선택하는 화면입니다.

에이전트에 사용할 모델을 선택하는 화면이 나옵니다. 모델은 아래 네 가지 옵션이 있습니다.

Sonnet: 속도와 성능이 균형 잡혀 있어 대부분의 에이전트에 적합합니다.
Opus: 복잡한 추론이 필요한 작업에 가장 강력합니다.
Haiku: 단순한 작업에 빠르고 가볍게 동작합니다.
Inherit from parent: 메인 대화에서 사용 중인 모델을 그대로 따릅니다.

원하는 모델을 선택합니다. 다만 Claude의 모델 중 추론 능력이 가장 뛰어난 Opus 모델을 선택할 경우 토큰이 빠르게 소비될 수 있습니다.

기획이나 전략을 구성하는 Agent일 경우 Opus를 선택하고 일반적인 모델에는 Sonnet 이하의 모델을 선택하는 것이 좋습니다.

클로드 코드에서 에이전트를 생성할 때 에이전트에 따른 색상을 지정하는 화면입니다.

Agent의 색상을 선택하는 화면이 나옵니다. 원하는 색으로 선택해 설정해줍니다.

클로드 코드에서 에이전트를 생성할 때 에이전트의 메모리 저장 방식을 설정하는 화면입니다.

에이전트의 메모리 저장 방식을 설정하는 화면이 나옵니다.

User scope: 내 컴퓨터 전체에서 기억을 유지합니다. 모든 프로젝트에서 누적됩니다.
None: 세션이 끝나면 기억을 초기화합니다.
Project scope: 현재 프로젝트 안에서만 기억을 유지합니다.
Local scope: 로컬 환경에서만 기억을 유지합니다.

에이전트 생성 최종 확인 화면이 나옵니다. Claude가 자동으로 구성한 내용을 보여줍니다. 하단에 Warnings가 두 가지 표시되는데, 시스템 프롬프트가 10,000자를 넘는다는 경고입니다. 기능상 문제는 없지만 필요 없는 내용이 있다면 e를 눌러 편집할 수 있습니다. 그냥 저장하려면 s 또는 Enter를 누르면 됩니다.

프로젝트를 통솔할 project-orchestrator 에이전트가 생성되었습니다.

같은 방법으로 팀 리드부터 PPT 작성자까지 각각의 에이전트를 생성합니다.

4. 하네스 엔지니어링으로 규칙 정의하기

역할별 에이전트를 생성했다면 이제 각 에이전트가 어떤 기준으로 움직일지 규칙을 정의해야 합니다. 이 과정을 ‘하네스 엔지니어링’이라고 합니다.

Claude Code에서는 프로젝트의 CLAUDE.md 파일에 각 에이전트의 역할, 작업 범위, 금지 작업, 산출물 형식, 작업 순서, 검증 기준을 정의할 수 있습니다. 이렇게 기준을 명확히 작성해두면 에이전트가 임의로 판단해 엉뚱한 방향으로 작업하는 것을 줄일 수 있습니다.

5. 정해진 규칙을 기준으로 에이전트 팀 실행하기

에이전트 팀과 하네스 규칙을 준비했다면 이제 실제 작업을 요청할 단계입니다. 이때 단순히 “에이전트 팀으로 진행해줘”라고 말하기보다, CLAUDE.md 또는 AGENTS.md에 정리한 역할과 규칙을 기준으로 작업하라고 지시하는 것이 좋습니다.

이렇게 하면 에이전트 팀이 각자 임의로 움직이지 않고, 앞서 정의한 규칙에 따라 계획, 구현, 검증, 정리까지 일관된 흐름으로 작업할 수 있습니다.

클로드 코드 에이전트 팀

사용시 주의사항 4가지

1. 모든 작업에 에이전트 팀을 활용하는건 비효율적입니다

에이전트 팀은 큰 프로젝트를 역할별로 나눠 처리할 때 유용하지만, 모든 작업에 필요한 것은 아닙니다. 간단한 버그 수정, 단일 파일 수정, 작은 기능 추가처럼 작업 범위가 좁은 경우에는 하나의 에이전트가 일관되게 처리하는 편이 더 빠르고 안정적입니다.

에이전트 팀은 병렬로 나눌 수 있는 작업에 사용하고, 하나의 기준으로 끝까지 밀고 가야 하는 작업은 단일 에이전트 또는 리드 에이전트 중심으로 진행하는 것이 좋습니다.

2. 에이전트 팀 활용시 비용이 빠르게 늘어날 수 있습니다

에이전트 팀을 구성하면 여러 Claude 인스턴스가 각각 독립적으로 작업하기 때문에, 단일 에이전트보다 토큰 사용량이 훨씬 빠르게 늘어날 수 있습니다. 그래서 에이전트 팀을 운영할 때는 항상 토큰 사용량을 주의해야 합니다.

토큰을 효율적으로 활용하려면 모든 에이전트에 같은 모델을 배정하기보다 역할에 따라 모델을 나누는 것이 좋습니다.

이렇게 하면 불필요하게 같은 맥락을 반복해서 읽는 일을 줄이고, 역할별 비용을 더 안정적으로 관리할 수 있습니다.

3. 하네스 없이 운영하면 규칙이 매번 흔들릴 수 있습니다

에이전트 팀은 하네스 엔지니어링 없이도 실행할 수 있지만, 실무 서비스에 사용하면 규칙이 매번 달라질 수 있다는 문제가 생깁니다. 매번 프롬프트로 역할과 규칙을 설명해야 하고, 에이전트가 테스트를 빼먹거나 기존 아키텍처와 맞지 않는 방식으로 코드를 수정할 수도 있습니다.

이를 줄이기 위해 AGENTS.md, CLAUDE.md, docs/, scripts/check.py 같은 규칙 파일과 검증 루프를 하네스 엔지니어링을 활용해 만들어 두는 것이 좋습니다. 하네스가 있으면 에이전트가 작업 전에 규칙을 읽고, 작업 후 정해진 검증 명령어를 실행하며, 결과를 일정한 형식으로 보고할 수 있습니다.

4. 결과물은 반드시 별도 검증 과정을 거쳐야 합니다

에이전트 팀이 계획, 구현, 테스트, 리뷰까지 수행하더라도 최종 판단은 사람이 해야 합니다. 특히 데이터베이스 구조 변경, 인증 방식 변경, 외부 API 연동, 비용이 발생하는 기능, 개인정보 처리와 관련된 작업은 반드시 사람이 확인해야 합니다.

에이전트 팀은 반복 작업과 초안 작성, 오류 탐지에는 강하지만 제품 방향이나 비즈니스 판단까지 완전히 대신할 수는 없습니다. 따라서 자동화된 결과를 그대로 반영하기보다, 변경 파일과 검증 결과를 확인하고 위험한 변경이 없는지 마지막에 검토하는 과정이 필요합니다.