Agency Agents 설치·사용법: 클로드 코드 에이전트 실전 가이드

개발은 개발 담당에게, 디자인은 디자인 담당에게. 클로드 코드에서도 작업에 맞는 역할을 골라 맡길 수 있습니다.

Agency Agents란 무엇인가요?

Agency Agents는 개발·디자인·마케팅 등 역할별 작업 지침을 모아둔 오픈소스입니다. 필요한 역할을 Claude Code에 설치하면, 매번 업무 기준을 길게 설명하는 수고를 줄일 수 있어요. 원본 저장소

글은 Content Creator, 화면 설계는 UI Designer, 구현은 Frontend Developer부터 시작하세요. 아래에서 설치부터 서비스 페이지·홍보 글 제작까지 따라 해보겠습니다.

역할별 에이전트는 왜 필요한가요?

반복해서 설명하던 작업 기준을 재사용하고, 서로 다른 일을 나눠 요청하기 위해서입니다. 모델의 지식이 갑자기 늘어나는 것은 아니지만, 요청과 결과를 확인할 기준을 명확하게 만들 수 있습니다.

가령 다음처럼 부탁했다고 해보겠습니다.

내 서비스 소개 페이지 만들고, 디자인도 예쁘게 해주고,
인스타그램 홍보 글도 써줘.

여기에는 세 가지 일이 섞여 있습니다. 페이지를 만드는 일, 화면을 검토하는 일, 사람들에게 알릴 글을 쓰는 일이죠. 역할을 나누면 각 단계의 결과물을 구체적으로 요청하기 쉬워집니다.

처음부터 이 네 역할을 모두 쓸 필요는 없습니다. 지금 가장 오래 걸리는 일 하나를 맡겨보세요. 글 초안이 어렵다면 콘텐츠 담당 하나만으로 시작해도 충분합니다.

여기서 말하는 ‘AI 팀’은 역할별로 일을 맡기는 비유입니다. Claude Code의 Agent Teams 기능을 켜는 설치 과정은 아닙니다. Agent Teams는 별도 세션들이 함께 일하도록 조율하는 기능이며, 이 글은 설치한 서브에이전트에 순서대로 작업을 맡기는 실습입니다. Claude Code Agent Teams 공식 문서

에이전트·스킬·프롬프트는 어떻게 다른가요?

Claude Code에서 사용자 에이전트는 보통 ~/.claude/agents/, 사용자 스킬은 ~/.claude/skills/에 둡니다. 각각 역할과 절차를 담는다고 이해하면 쉽지만, 내용이 완전히 분리되는 것은 아닙니다. 에이전트에도 작업 순서가 들어갈 수 있고, 스킬을 에이전트에 연결할 수도 있습니다. Claude Code 서브에이전트 문서, 스킬 문서

자세한 구분은 Claude Code 스킬·워크플로우·에이전트 차이에서 이어서 볼 수 있습니다.

처음에는 어떤 에이전트를 고르면 좋을까요?

만들고 싶은 결과물에 맞춰 하나를 고르세요. 역할 이름이 멋져 보이는지보다, 지금 필요한 산출물과 맞는지가 중요합니다.

앞의 세 역할로 제작 흐름을 익힌 다음, 검수 단계가 필요할 때 Reality Checker를 추가하면 됩니다. 역할별 범위는 UI Designer와 Reality Checker 파일에서도 확인할 수 있습니다.

Claude Code에 Agency Agents를 설치하는 방법

터미널이 익숙하지 않으면 데스크톱 앱을, 필요한 역할과 경로를 직접 지정하고 싶다면 원본 설치 스크립트를 사용하세요. 둘 중 한 가지 방법만 선택하면 됩니다.

방법 1. 데스크톱 앱에서 역할 선택하기

Agency Agents 앱에서 운영체제에 맞는 설치 파일을 내려받습니다. macOS, Windows, Linux용이 제공됩니다.

1. 앱을 열고 역할 목록에서 사용할 역할의 설명을 확인합니다.
2. 설치 대상 도구로 Claude Code를 선택합니다.
3. Content Creator, UI Designer, Frontend Developer 중 필요한 역할을 선택해 설치합니다.
4. Claude Code에서 아래의 설치 확인 프롬프트를 실행합니다.

이 앱은 역할 파일의 설치와 관리를 돕습니다. 실제 작업은 Claude Code 같은 연결 대상 도구에서 수행합니다. 앱 기능과 지원 도구

방법 2. 터미널에서 세 역할만 설치하기

아래 명령은 내 컴퓨터의 터미널에서 실행합니다. macOS·Linux에서는 Bash를 사용할 수 있는 터미널, Windows에서는 Git Bash 또는 WSL을 사용하세요. Windows 기본 명령 프롬프트나 PowerShell에 그대로 붙여넣는 예제는 아닙니다. 설치 스크립트의 지원 환경

WSL을 쓴다면 설치와 Claude Code 실행을 같은 WSL 환경에서 진행하세요. Windows와 WSL은 사용자 홈이 달라, 한쪽에 설치한 역할이 다른 쪽에서 보이지 않을 수 있습니다.

먼저 준비물을 확인합니다.

git --version
bash --version
claude --version

git이나 claude를 찾을 수 없다고 나오면 해당 도구를 먼저 설치하세요. Claude Code 준비가 안 됐다면 클로드 코드 설치·첫 실행 가이드를 참고하면 됩니다. 아래의 원본 Claude Code용 설치에는 npx를 사용하지 않습니다.

① 원본 저장소 내려받기

git clone https://github.com/msitarzewski/agency-agents.git "$HOME/agency-agents"

이미 같은 경로에 저장소를 받아두었다면 복제 명령을 다시 실행하지 말고 기존 폴더를 사용하세요.

② 설치할 역할 미리 확인하기

bash "$HOME/agency-agents/scripts/install.sh" \
  --tool claude-code \
  --agent content-creator,ui-designer,frontend-developer \
  --dry-run

--dry-run은 파일을 설치하지 않고 선택한 도구와 역할을 보여줍니다. Tools: claude-code와 역할 수 3을 확인하세요.

③ 실제 설치하기

bash "$HOME/agency-agents/scripts/install.sh" \
  --tool claude-code \
  --agent content-creator,ui-designer,frontend-developer

설치 대상은 기본적으로 사용자 홈의 ~/.claude/agents/입니다. CLAUDE_CONFIG_DIR을 따로 설정했다면 그 설정 경로를 따릅니다. 기존에 같은 이름의 역할 파일을 직접 수정했다면 재설치로 덮어쓸 수 있으니 별도로 보관하세요.

기본 경로로 설치했다면 아래 명령으로 세 파일이 있는지 확인할 수 있습니다.

ls "$HOME/.claude/agents/marketing-content-creator.md" \
   "$HOME/.claude/agents/design-ui-designer.md" \
   "$HOME/.claude/agents/engineering-frontend-developer.md"

설정 경로를 바꿨다면 그 경로에서 확인하세요. 파일 존재 여부를 확인한 뒤에는 아래의 호출 예제로 실제 위임 기록도 확인해야 합니다.

특정 프로젝트에서만 쓰고 싶다면, 위의 전역 설치 대신 작업할 프로젝트 폴더에서 다음 명령을 실행합니다.

bash "$HOME/agency-agents/scripts/install.sh" \
  --tool claude-code \
  --agent content-creator,ui-designer,frontend-developer \
  --path "$PWD/.claude/agents"

역할을 하나만 설치하려면 --agent content-creator처럼 줄이면 됩니다. 전체 목록은 다음 명령으로 확인할 수 있습니다. 옵션의 동작은 원본 설치기를 기준으로 합니다.

bash "$HOME/agency-agents/scripts/install.sh" --list agents

한 줄 설치로 소개되는 reborn-agency는 무엇인가요?

npx --yes reborn-agency

이 명령은 별도 설치기 reborn-agency를 실행하는 방법입니다. 원본의 세 역할 선택 설치와는 다릅니다. 확인한 1.0.0 패키지는 포크 저장소의 에이전트와 한국어 안내 스킬을 설치하도록 작성돼 있습니다. Node.js 18 이상을 요구하며, --yes는 npx의 패키지 다운로드 확인을 생략하는 옵션입니다. npx 공식 문서, 패키지 메타데이터

이 글의 원본 설치 방법을 따라왔다면 추가로 실행할 필요는 없습니다. Claude Code를 설치했다고 Node.js도 반드시 설치된 것은 아니므로, 이 별도 방법을 선택할 때는 node --version과 npx --version을 먼저 확인하세요. Claude Code 자체는 네이티브 설치도 지원합니다. Claude Code 설치 문서

설치한 에이전트는 어떻게 호출하나요?

역할 이름과 맡길 작업을 함께 적고, 해당 서브에이전트에 위임해달라고 요청하세요. “개발자처럼 답해줘”와 설치된 에이전트에 작업을 맡기는 것은 다를 수 있습니다.

먼저 작업할 프로젝트에서 Claude Code를 열고 다음 프롬프트를 입력해보세요. 다른 역할 하나만 설치했다면 예제의 역할 이름과 작업 내용을 그 역할에 맞게 바꾸면 됩니다.

설치된 Frontend Developer 서브에이전트에 다음 작업을 위임해줘.
현재 프로젝트의 화면 관련 파일 구조를 읽고,
소개 페이지를 추가할 위치와 사용할 기술을 5줄로 정리해줘.
아직 파일은 수정하지 마.
에이전트를 찾지 못하면 일반 역할극으로 대체하지 말고 알려줘.

대화 기록에 해당 에이전트로 위임한 호출이 표시되는지 확인하세요. 답변에 “저는 프론트엔드 개발자입니다”라고 적혀 있는 것만으로는 실제 사용 여부를 확인하기 어렵습니다. Claude Code는 위임 기록에 에이전트 이름과 작업 설명을 표시합니다. 서브에이전트 호출 예시

역할 이름은 파일 상단의 name 값을 기준으로 합니다. 설치 옵션의 frontend-developer와 파일 안의 Frontend Developer를 구분해두면 이해하기 쉽습니다.

새 역할을 못 찾으면 설치 경로와 현재 프로젝트를 먼저 확인하고 Claude Code를 다시 시작해보세요. 최신 버전은 기존 에이전트 폴더의 파일 변경을 감지하지만, 세션을 시작한 뒤 에이전트 폴더 자체를 처음 만들었다면 재시작이 필요할 수 있습니다. 에이전트 파일 감지 방식

실습: 서비스 페이지부터 인스타그램 홍보 글까지 만들기

같은 서비스 설명을 공유하고, 앞 단계의 결과물을 다음 담당에게 전달하는 방식으로 진행합니다. 예제는 기획 중인 가상의 학습 기록 서비스, 코딩로그입니다. 내 서비스 이름과 기능으로 바꿔서 사용하세요.

새로 만드는 페이지라면 디자인부터 정한 뒤 구현해도 좋습니다. 여기서는 쇼츠의 흐름처럼 페이지 초안 구현 → 디자인 점검·수정 → 홍보 글 작성 순서로 진행합니다.

1단계. 모두가 참고할 서비스 설명 만들기

작업 프로젝트에 service-brief.md 파일을 만들고 아래 내용을 넣으세요. 처음 실습한다면 새 작업 폴더에서 시작해도 됩니다.

# 코딩로그 서비스 설명

## 대상
코딩 공부를 시작했지만 학습 기록을 꾸준히 남기기 어려운 사람

## 해결하려는 문제
오늘 무엇을 공부했는지, 어디서 막혔는지 나중에 찾기 어렵다.

## 출시 후 제공할 예정인 기능
- 하루 학습 내용을 짧게 기록한다.
- 해결하지 못한 질문을 모아본다.
- 일주일의 기록을 한 화면에서 확인한다.
이 기능들은 이번 실습에서 구현하지 않으며, 페이지에도 예정 기능으로 표시한다.

## 이번 페이지의 목표
방문자가 기능을 이해하고 사전 신청 영역으로 이동하게 한다.

## 구현 범위
정적인 소개 페이지와 신청 안내 영역까지만 만든다.
실제 회원가입, 결제, 개인정보 수집은 구현하지 않는다.

## 표현 기준
친근하고 구체적인 한국어를 사용한다.
실제 사용자 수, 후기, 할인율, 성과 수치는 아직 없다.
확인되지 않은 숫자나 후기는 만들지 않는다.

이 문서가 있으면 담당이 바뀌어도 서비스 대상과 기능을 다시 설명하는 수고가 줄어듭니다. 특히 아직 없는 기능과 실적이 무엇인지 명시하는 것이 중요합니다.

2단계. Frontend Developer에게 페이지 구현 맡기기

Frontend Developer 서브에이전트에 다음 작업을 위임해줘.

목표: service-brief.md를 바탕으로 코딩로그 소개 페이지 만들기
입력 자료: service-brief.md와 현재 프로젝트

작업 조건:
- 기존 웹 프로젝트가 있으면 기술과 폴더 규칙을 따라줘.
- 기존 웹 프로젝트가 없으면 외부 의존성 없는 index.html로 만들어줘.
- 서비스 소개, 예정 기능 3개, 출시 후의 사용 흐름, 사전 신청 안내를 넣어줘.
- 학습 기록 서비스는 아직 기획 단계임을 명확히 표시해줘.
- 버튼은 페이지 안의 사전 신청 안내 영역으로 이동하게 해줘.
- 실제 신청 기능은 아직 없다는 안내를 보여줘.
- 모바일에서도 내용이 잘리지 않게 구성해줘.
- 문서에 없는 후기나 성과 수치를 만들지 마.

결과물:
1. 구현한 페이지 파일
2. 실행 방법과 변경 파일을 정리한 implementation-notes.md
3. 확인한 항목과 확인하지 못한 항목

가능한 환경에서 실행과 화면을 확인해줘.
브라우저로 확인하지 못했다면 그 사실을 구분해서 적어줘.

완료 기준: 페이지 파일이 존재하고, 실행 방법이 있으며, 버튼을 눌렀을 때 안내 영역으로 이동해야 합니다. 새 작업 폴더에서 만든 단일 HTML 예제는 index.html을 브라우저에서 열어 확인할 수 있습니다. 기존 프로젝트라면 작성된 실행 안내를 따르세요.

3단계. UI Designer에게 첫 화면 점검 맡기기

UI Designer 서브에이전트에 디자인 검토를 위임해줘.

입력 자료:
- service-brief.md
- 구현한 소개 페이지
- implementation-notes.md

검토 기준:
- 첫 화면에서 누구를 위한 서비스인지 알 수 있는가?
- 핵심 문장과 버튼이 주변 요소보다 눈에 잘 들어오는가?
- 모바일에서 글자와 버튼이 너무 작거나 겹치지 않는가?
- 아직 없는 신청 기능을 사용할 수 있는 것처럼 표현하지 않았는가?

결과는 design-review.md에 저장해줘.
실제 문제가 확인된 개선안을 우선순위순으로 최대 5개까지
문제 위치 / 이유 / 수정 제안 / 확인 방법 순으로 정리해줘.
직접 본 화면과 코드만 보고 추정한 내용을 구분해줘.
이 단계에서는 코드를 수정하지 마.

개선안을 확인한 다음에는 구현 담당에게 다시 전달합니다.

Frontend Developer 서브에이전트에 수정 작업을 위임해줘.
design-review.md를 읽고 우선순위가 높은 개선안을 반영해줘.
service-brief.md의 기능 범위는 유지해줘.
반영한 항목과 보류한 항목, 수정 후 확인 결과를
implementation-notes.md에 업데이트해줘.

완료 기준: “예쁘게 바꿨다”는 설명보다, 어떤 문제를 고쳤고 어떻게 확인했는지 남아 있어야 합니다. 화면을 직접 확인할 도구가 없다면 스크린샷을 제공하거나 내가 브라우저에서 점검한 내용을 전달하세요.

4단계. Content Creator에게 인스타그램 글 맡기기

Content Creator 서브에이전트에 콘텐츠 작성을 위임해줘.

입력 자료: service-brief.md와 완성된 소개 페이지
대상: 코딩 공부를 시작한 초보 개발자
목표: 서비스의 쓰임을 이해하고 소개 페이지를 방문하게 하기
채널: 인스타그램 카드뉴스 5장

결과물은 instagram-draft.md로 저장해줘.
- 1장: 독자가 겪는 문제를 질문으로 제시
- 2~4장: 출시 후 제공할 예정인 기능을 일상적인 사용 예로 설명
- 5장: 소개 페이지 방문을 유도하는 문구
- 각 장의 제목과 본문을 구분
- 게시물 본문 1개와 대체 첫 문장 3개 추가

서비스가 기획 단계라는 사실을 분명히 밝혀줘.
과장된 성과, 가짜 후기, 검증되지 않은 숫자는 넣지 마.
실제 신청을 받을 수 있는 상태인지 먼저 확인하고,
소개 페이지 안내와 모순되는 행동을 유도하지 마.
초안 작성까지만 하고 실제 게시하지 마.

완료 기준: 카드뉴스 5장의 역할이 구분되고, 홍보 문구가 페이지에 실제로 있는 내용과 일치해야 합니다. 이 단계의 결과물은 이미지가 아닌 카드뉴스용 글과 구성안입니다.

5단계. 필요하면 Reality Checker로 근거 점검하기

검수 역할도 사용하려면 추가로 설치하세요.

bash "$HOME/agency-agents/scripts/install.sh" \
  --tool claude-code \
  --agent reality-checker

앞서 프로젝트에만 설치했다면 이 명령에도 같은 --path "$PWD/.claude/agents" 옵션을 붙입니다.

Reality Checker 서브에이전트에 결과 검수를 위임해줘.

입력 자료:
- service-brief.md
- 구현한 소개 페이지와 implementation-notes.md
- design-review.md
- instagram-draft.md

다음 항목을 점검해줘.
1. 예정 기능과 현재 사용 가능한 기능이 명확히 구분되는지
2. 버튼과 페이지 내 이동이 동작하는지
3. 모바일 화면에서 내용이 잘리지 않는지
4. 홍보 글에 확인되지 않은 기능·수치·후기가 없는지

결과를 qa-report.md에 저장해줘.
각 항목은 통과 / 실패 / 미확인 중 하나로 표시하고,
파일 위치, 실행 결과, 화면 등 판단 근거를 붙여줘.
실패는 재현 방법과 수정 우선순위를 적어줘.
실행하지 못한 검사를 통과로 처리하지 마.
이번 실습 범위의 검수이며, 전체 서비스의 배포 승인으로 확대하지 마.

검수 담당도 AI이므로 판단이 틀릴 수 있습니다. 특히 “문제없음”이라는 결론보다 무엇을 실행하고 어떤 근거를 남겼는지를 확인하세요.

내 작업에 맞게 바꾸는 공통 프롬프트

역할 + 목표 + 자료 + 조건 + 결과물 + 완료 기준을 함께 주면 첫 요청을 만들기 쉽습니다. 아래 틀의 대괄호 부분을 내 작업으로 바꿔보세요.

[설치된 에이전트 이름] 서브에이전트에 작업을 위임해줘.

목표: [이번에 해결할 문제 하나]
입력 자료: [읽을 파일, 코드, 링크]
대상: [이 결과물을 사용할 사람]
조건: [분량, 기술, 말투, 포함하거나 제외할 내용]
결과물: [파일 이름과 원하는 구성]
완료 기준: [내가 결과를 확인할 구체적인 항목]

사실과 가정을 구분해줘.
실행한 확인과 실행하지 못한 확인을 나눠서 보고해줘.
필수 정보가 빠져 작업할 수 없다면 필요한 질문부터 해줘.

예를 들어 “블로그 잘 써줘”보다 “Content Creator에게 기존 쇼츠 대본을 읽고 입문자용 글을 작성하게 해줘. 설치 예제와 FAQ를 포함하고, 실행하지 않은 명령을 검증했다고 쓰지 마”라고 요청하는 편이 결과를 평가하기 쉽습니다.

역할 파일 자체도 내 작업에 맞게 수정할 수 있습니다. 자주 빠뜨리는 품질 기준은 별도 작업 규칙으로 정리해 함께 전달해보세요. 단, 원본 파일을 직접 바꿨다면 업데이트 때 수정 내용이 덮어써지지 않도록 관리해야 합니다.

설치·호출이 안 될 때 확인할 것

파일이 설치된 것, 실제 에이전트에 위임한 것, 작업 결과가 올바른 것은 서로 다른 확인 단계입니다. 이 세 가지를 나눠보면 어디서 막혔는지 찾기 쉽습니다.

자주 묻는 질문

오늘은 담당 하나와 결과물 하나로 시작하세요

Agency Agents를 잘 쓰는 출발점은 내 일의 담당과 완료 기준을 정하는 것입니다.

글이 필요하면 Content Creator, 화면 설계가 필요하면 UI Designer, 구현이 필요하면 Frontend Developer를 선택하세요. 같은 모델·입력 자료·완료 기준을 사용하고, 각각 새 대화에서 역할을 지정한 경우와 지정하지 않은 경우를 비교해보는 것도 좋습니다. 한 번의 결과만으로 성능 향상을 단정하지 말고 비슷한 작업에서 반복해보세요. 기준은 문장의 화려함보다 빠진 요구사항, 직접 고친 부분, 확인 가능한 근거로 잡아보세요.

오늘의 목표는 하나면 충분합니다. 필요한 역할 하나를 설치하고, 공통 프롬프트에 내 목표를 넣어 실제로 사용할 결과물 하나를 받아보세요. 그다음에 디자인이나 검수 담당을 붙이면 됩니다.

다음 단계로 작업 기준을 정리하고 싶다면 Claude Code 폴더 설정 가이드와 AI가 스스로 검증·수정하는 프롬프트를 함께 읽어보세요.