우리는 모두 알다시피, 프롬프트를 작성하는 일은 일종의 손기술입니다. 같은 Claude 모델에 “React 컴포넌트를 작성해 줘”라고 하면 나오는 결과와, “숙련된 프론트엔드 엔지니어 관점에서 WCAG 2.1 AA 규정을 준수하고 TypeScript + React 18로 접근 가능한 가상 스크롤 테이블을 작성해 줘”라고 했을 때의 출력 품질은 하늘과 땅 차이입니다.
Agency Agents 는 바로 이런 문제를 해결하기 위해 만들어졌습니다. 16개 부서, 100+개의 AI 전문가 역할(Frontend Developer, Backend Architect, Security Auditor, Reddit Community Ninja……)의 설정, 프로세스, 산출물, 측정 지표까지 전부 미리 편성해 두었고, 우리는 해당 역할을 활성화하기만 하면 AI가 자동으로 ‘전문가 모드’로 들어갑니다.
더 좋은 점은 레포지토리에 convert.sh 와 install.sh 가 기본으로 포함되어 있다는 것입니다. 같은 역할 정의를 Claude Code, OpenClaw, Cursor, OpenCode, Codex, Gemini CLI 등 10+가지 도구에 원클릭으로 동기화할 수 있어, 설정을 여러 벌로 관리할 필요가 없습니다.
이 글에서는 처음부터 끝까지 함께 실행해 보고, OpenClaw에서 역할을 활성화해 실제 요구사항을 완성하는 방법까지 시연해 보겠습니다.
프로젝트 소개
msitarzewski/agency-agents 는 레딧 게시물의 “만약 AI 직원 팀을 고용할 수 있다면 어떤 직무를 원하겠어요?”라는 논의에서 출발했습니다. 이후 몇 달에 걸친 반복을 거쳐 꽤 완성도 높은 AI 에이전트 역할 라이브러리로 발전했는데, 그 구성은 다음과 같습니다.
- 16개 부서: engineering, design, marketing, finance, security, sales, testing…… 소프트웨어 회사에서 필요로 하는 거의 모든 직무를 커버합니다.
- 100+개 역할: Frontend Developer, Backend Architect부터 Whimsy Injector, Reality Checker 같은 “설정 온도”가 있는 역할까지 다양합니다.
- 측정 가능한 산출물: 각 역할은 success metrics, deliverables, critical rules를 명시합니다. 비어 있는 프롬프트가 아닙니다.
- 다중 도구 호환: 동일한 Markdown 소스 파일을 Claude Code subagent, OpenClaw workspace, Cursor rule, OpenCode agent, Codex TOML 등 포맷으로 변환할 수 있습니다.
일반적인 프롬프트 템플릿과의 가장 큰 차이는, 여기서는 각 역할마다 완전한 인격화 설정(말투, 스타일, 기억 메커니즘) + 업무 프로세스(mission / workflow / deliverables)가 함께 제공되어, “직무 설명서 한 장”에 훨씬 가깝다는 점입니다.
난이도 / 소요 시간 / 얻는 것
- 난이도: ⭐⭐ (커맨드라인만 쓰면 됩니다. 코드에 대한 진입 장벽이 전혀 없습니다.)
- 소요 시간: 15-30분 (최초 설치 + 역할 1개 활성화 + 실제 요구사항까지 실행)
- 얻는 것: Claude Code / OpenClaw을 ‘필요할 때 호출하는’ 멀티 역할 AI 팀으로 전환하고, 장기적으로 전문 역할의 설정을 안정적으로 유지합니다.
대상 독자
- AI로 생산성을 높이고 싶지만, 프롬프트 작성이 너무 번거로운 개발자
- 1~5년 경력의 프론트엔드 / 백엔드 / 풀스택 / 보안 / 테스트 엔지니어
- 이미 Claude Code, Cursor, OpenClaw, Codex 같은 AI 프로그래밍 도구를 실제로 사용 중인 사람
- 팀 내에 “AI 협업 규정”을 정착시키려는 테크 리드
핵심 의존성과 환경
| 도구 | 최소 버전 | 설명 |
|---|---|---|
| Git | 2.30+ | 레포지토리 클론 |
| Bash | 4.0+ | convert.sh / install.sh 실행 (Windows는 Git Bash 또는 WSL 필요) |
| Node.js | 18+ | 일부 목표 도구(OpenClaw, Codex)가 필요로 함 |
| 목표 IDE / CLI | 최신 버전 | Claude Code, OpenClaw, Cursor, OpenCode 중 하나면 충분 |
TIP
이미 OpenClaw(여러 대형 모델을 통합해 스케줄링하는 CLI 게이트웨이)를 사용 중이라면, 이 글 전체를 ‘추가 비용 없이’ 바로 끝까지 실행할 수 있습니다.
TIP
호출 비용에 대하여: Agency Agents의 각 전문가 역할 뒤에서는 최상위 모델(Claude Opus 4.8, GPT-5.4, Gemini 2.5 Pro)이 동작합니다. 1개 역할을 활성화해 React 컴포넌트 반복 20라운드를 돌리면, 공식적으로 저렴한 모델을 써도 대략 십수 달러가 듭니다. 동일한 모델을 공식 반값으로 쓰고 싶다면 Defapi 를 시도해 볼 수 있습니다. LLM API를 중계하는 플랫폼입니다. 장점은 거의 모든 모델이 v1/chat/completions, v1/messages, v1beta/models/ 세 프로토콜을 호환한다는 점인데, 즉 비즈니스 코드 수정 없이 OpenClaw 설정에서 base_url을 Defapi 엔드포인트로만 바꾸면 즉시 비용을 절감할 수 있습니다. 개인 개발자와 소규모 팀에 특히 유리합니다.
공식 진입: defapi.org.
전체 프로젝트 디렉터리 트리
agency-agents/
├── academic/ # 학술 연구 방향
├── design/ # UI/UX 디자인
├── engineering/ # 개발(가장 큰 부서, 30+ 역할)
├── finance/ # 재무
├── game-development/ # 게임 개발
├── gis/ # 지리 정보
├── marketing/ # 마케팅
├── paid-media/ # 유료 광고
├── product/ # 제품
├── project-management/ # 프로젝트 관리
├── sales/ # 영업
├── security/ # 보안
├── spatial-computing/ # 공간 컴퓨팅
├── specialized/ # 특수 전문가
├── strategy/ # 전략
├── support/ # 고객 지원
├── testing/ # 테스트
├── integrations/ # 멀티 도구 통합 산출물
│ ├── openclaw/ # OpenClaw 워크스페이스（SOUL.md + AGENTS.md + IDENTITY.md）
│ ├── opencode/ # OpenCode agent（.md + YAML frontmatter）
│ ├── claude-code/ # Claude Code subagent
│ ├── cursor/ # Cursor rule（.mdc）
│ ├── codex/ # Codex 커스텀 agent（TOML）
│ ├── gemini-cli/ # Gemini CLI subagent
│ ├── github-copilot/ # GitHub Copilot
│ ├── aider/ # Aider CONVENTIONS.md
│ ├── windsurf/ # Windsurf .windsurfrules
│ ├── kimi/ # Kimi Code CLI
│ ├── qwen/ # Qwen Code SubAgent
│ └── mcp-memory/ # MCP 장기 기억
├── scripts/
│ ├── convert.sh # 역할 정의 → 도구 포맷 변환기
│ ├── install.sh # 로컬에 한 번에 설치
│ ├── lib.sh # 공용 함수
│ └── lint-agents.sh # 역할 정의 lint
├── README.md
└── CONTRIBUTING.md
단계별 진행
아래에서는 OpenClaw 를 예로 들어 전체 흐름을 보여 드리겠습니다. 다른 도구들은 --tool만 해당 이름으로 바꾸면 됩니다.
1단계: 레포지토리 클론
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
네트워크가 제한되어 있다면, 먼저 Gitee나 본인 GitHub로 포크한 뒤 클론하세요.
git clone https://github.com/<your-fork>/agency-agents.git
cd agency-agents
2단계: 설치 가능한 부서와 역할 확인
install.sh 에는 매우 편리한 “목록(list)” 모드가 있습니다.
./scripts/install.sh --list teams
다음과 같은 출력이 보일 겁니다.
engineering 33 agents
design 12 agents
marketing 18 agents
security 9 agents
testing 11 agents
...
특정 부서만 설치하고 싶다면(예: engineering + security), 이후 --division 으로 필터하면 됩니다.
3단계: OpenClaw 포맷 통합 파일 생성
convert.sh 는 소스 Markdown을 OpenClaw이 기대하는 SOUL.md(인격) + AGENTS.md(프로세스) + IDENTITY.md(정체성) 세트로 분해합니다.
./scripts/convert.sh --tool openclaw
성공하면 integrations/openclaw/ 디렉터리 안에 100+개의 하위 디렉터리가 추가됩니다.
ls integrations/openclaw/ | head -20
# agency-frontend-developer
# agency-backend-architect
# agency-security-auditor
# agency-reddit-community-ninja
# agency-whimsy-injector
# ...
각 하위 디렉터리는 이런 식으로 구성됩니다.
agency-frontend-developer/
├── SOUL.md # 역할 인격: 정체성, 기억, 말투, 스타일
├── AGENTS.md # 업무 프로세스: mission, deliverables, workflow
└── IDENTITY.md # 신분 카드: 이모지 + 이름 + 바이브
4단계: OpenClaw에 한 번에 설치
# 전체 설치(약 100+ 역할)
./scripts/install.sh --tool openclaw
# 추천: 부서별로 골라 설치(한 번에 너무 많이 넣지 않기)
./scripts/install.sh --tool openclaw --division engineering,security
스크립트는 워크스페이스를 ~/.openclaw/agency-agents/ 로 자동 복사하고, OpenClaw 게이트웨이에 워크스페이스를 등록합니다.
5단계: OpenClaw 게이트웨이를 재시작해 새 역할 반영
WARNING
OpenClaw gateway가 계속 실행 중이라면, 반드시 재시작해야 새로 등록된 역할을 불러올 수 있습니다. 그렇지 않으면 “agent not found” 오류가 납니다.
openclaw gateway restart
6단계: OpenClaw에서 Frontend Developer 활성화
openclaw chat --agent agency-frontend-developer
또는 설정 파일에서 기본 agent를 agency-frontend-developer 로 바꿔 두면, 매번 OpenClaw를 시작할 때 해당 역할로 자동 진입합니다.
7단계: 실제 요구사항 실행
방금 활성화한 Frontend Developer에게 접근 가능한 가상 스크롤 테이블 컴포넌트를 작성하게 해 보겠습니다.
openclaw chat --agent agency-frontend-developer <<'EOF'
React 18 + TypeScript로 DataTable 컴포넌트를 작성해 줘. 요구사항:
1. @tanstack/react-virtual을 사용한 가상 스크롤
2. WCAG 2.1 AA 접근성 규정 준수
3. 셀은 커스텀 렌더링을 지원
4. 행 클릭 이벤트는 설정 가능하게
5. 바로 실행 가능한 완성 코드 제공
EOF
생성된 코드는 코드 스타일이 매우 일관적일 겁니다. 역할 정의 안에 이미 “WCAG 2.1 AA”, “memo로 감싸기”, “Core Web Vitals 최적화” 같은 제약이 고정돼 있기 때문입니다. 매번 프롬프트에서 이러한 조건을 반복해서 적을 필요가 없습니다.
8단계: 툴 간 시연(선택)
같은 역할 정의를 Cursor로 변환하는 것도 단 한 줄이면 됩니다.
./scripts/convert.sh --tool cursor
./scripts/install.sh --tool cursor --agent frontend-developer,backend-architect
TIP
Cursor 모드에서는 역할이 .cursor/rules/<slug>.mdc 형태로 존재합니다. Cursor는 파일 globs에 따라 필요할 때만 자동으로 로드합니다. globs: "**/*.tsx" 처럼 작성하면 프론트엔드 역할이 TSX 파일에만 적용되어 백엔드 파일을 오염시키는 일을 피할 수 있습니다.
자주 발생하는 문제 해결
Q1：install.sh가 permission denied를 보고함
대개 install.sh에 실행 권한이 없기 때문입니다. macOS / Linux 사용자는 다음을 실행하세요.
chmod +x scripts/install.sh scripts/convert.sh scripts/lib.sh
./scripts/install.sh --tool openclaw
Windows 사용자가 Git Bash에서 같은 오류가 난다면, 먼저 레포지토리가 zip 압축을 풀어서 받은 것이 아니라 git clone으로 내려받은 것인지 확인하세요(압축 zip을 풀지 말 것). 그리고 Git Bash로 스크립트를 실행합니다.
Q2：OpenClaw에서 “agent not found” 또는 “미등록”
99%의 경우는 역할을 설치한 뒤게이트웨이를 재시작하지 않은 것입니다.
openclaw gateway restart
openclaw agent list | grep frontend-developer
# 출력이 보이면 등록 성공입니다
그래도 안 되면, ~/.openclaw/agency-agents/ 디렉터리에 정말로 agency-frontend-developer/SOUL.md 파일이 있는지 확인하세요.
ls ~/.openclaw/agency-agents/agency-frontend-developer/
# SOUL.md AGENTS.md IDENTITY.md를 볼 수 있어야 합니다
Q3：OpenCode에 역할을 너무 많이 한 번에 설치하면 앞의 119개만 보임
이것은 OpenCode 업스트림에서 확인된 알려진 버그(issue #27988)입니다. 런타임에서 대략 119개 정도만 subagent로 등록되며, 나머지는 조용히(묵살된 채) 버려집니다.
해결책： --division 으로 쪼개 설치해서, 전체 역할 수를 119 이내로 제한하세요.
./scripts/install.sh --tool opencode --division engineering
./scripts/install.sh --tool opencode --division marketing --out ~/.opencode-extra/
스크립트는 임계값을 넘으면 warning을 먼저 띄웁니다. 혹시라도 확인이 필요하면 dry-run으로 먼저 테스트해 볼 수도 있습니다.
./scripts/install.sh --tool opencode --division engineering --dry-run
Q4：역할 frontmatter에 필드가 비어 convert가 스킵됨
convert.sh 는 name 필드가 없는 소스 파일은 건너뜁니다. 직접 역할을 fork했는데 integrations/openclaw/ 디렉터리에 항목이 생성되지 않는다면 다음을 확인해 보세요.
# 1. 소스 파일 frontmatter 확인
head -10 engineering/your-custom-agent.md
# 2. 최소한 다음을 포함해야 합니다.
# ---
# name: Your Agent Name
# description: One-line description
# ---
# 3. 다시 변환
./scripts/convert.sh --tool openclaw
Q5：Windows에서 bash 스크립트 줄바꿈 문자 문제
Windows에서 zip으로 스크립트를 풀어 사용했다면 파일이 CRLF 줄바꿈을 가지고 있을 수 있고, bash 실행 시 \r: command not found 오류가 날 수 있습니다.
# 방법 A: zip 다운로드가 아니라 git clone 사용
git clone https://github.com/msitarzewski/agency-agents.git
# 방법 B: 줄바꿈 문자 변환(Git Bash)
dos2unix scripts/*.sh
Q6：역할 간 인격 충돌 / 컨텍스트가 섞임
한 세션에서 먼저 Frontend Developer를 활성화했다가 이후 Security Auditor를 활성화하면, 이전 역할의 말투가 컨텍스트에 남아 있는 것처럼 보일 수 있습니다. 대부분의 CLI 도구에서 agent는 “system prompt 레벨”로 주입되며, agent를 전환해도 대화 기록이 자동으로 비워지지 않기 때문입니다.
해결책：
# agent 전환 전에 새 세션 시작
openclaw chat --new-session --agent agency-security-auditor
또는 OpenClaw 설정에서 “agent 전환 시 이전 세션 자동 아카이브” 기능을 켜면 됩니다.
확장 읽기 / 고급 방향
1. 커스텀 역할 템플릿
engineering/engineering-frontend-developer.md 는 매우 좋은 템플릿입니다. fork한 뒤 engineering-frontend-developer-chinese.md 처럼 한 파일을 수정해 보세요.
---
name: 프론트엔드 엔지니어(중문판)
description: React/Vue, UI 구현, 성능 최적화에 능한 프론트엔드 엔지니어, 중국어 주석으로 출력
color: cyan
emoji: 🖥️
vibe: 중국어로 출력하며 바이트댄스 프론트엔드 표준을 준수
---
# 프론트엔드 엔지니어(중문판)
당신은**프론트엔드 엔지니어**로서 현대 Web 기술에 집중합니다……
## 🧠 당신의 정체성과 기억
- 역할: 현대 Web 애플리케이션과 UI 구현 전문가
- 성격: 디테일에 집착하고, 성능에 민감하며, 사용자 우선
- 기억: 흔한 UI 패턴과 접근성 베스트 프랙티스를 기억합니다
그리고 ./scripts/convert.sh --tool openclaw 를 실행하면, 새 역할이 integrations/openclaw/ 에 나타납니다.
2. MCP-Memory로 역할에 장기 기억 추가
integrations/mcp-memory/ 디렉터리에는 MCP memory server 설정 세트가 제공되어 있습니다. 활성화하면 역할이 session을 넘어 선호(예: “이 팀은 npm이 아니라 pnpm을 선호함”) 같은 정보를 지속적으로 유지할 수 있습니다. 설정 방법은 레포지토리의 mcp-memory/README.md 를 참고하세요.
3. 멀티 에이전트 협업 워크플로우
단일 역할만으로도 이미 상당히 강력하지만, 더 흥미로운 건 이들을 협업 체인으로 편성하는 것입니다. 예를 들어:
요구사항 → [프로덕트 매니저]가 작업을 분해
→ [프론트엔드 개발자] + [백엔드 아키텍트] 병렬 구현
→ [코드 리뷰어]가 자동으로 코드 심사
→ [QA 테스트 엔지니어]가 테스트 실행
→ [테크니컬 라이터]가 PR 설명을 생성
OpenClaw에 내장된 “workflow” 기능으로 이런 역할들을 연결할 수 있습니다. 자세한 내용은 OpenClaw 공식 문서를 참고하세요.
4. 호출 비용 낮추기
앞에서 말했듯이, Agency Agents의 전문가 역할들은 모두 최상위 모델을 기반으로 동작합니다. 장기적으로 돌리면 비용이 적지 않습니다. 동일한 모델을 공식 반값으로 쓰고 싶다면 Defapi를 바로 연결할 수 있습니다(앞의 “핵심 의존성과 환경” 섹션에 자세한 설명이 있습니다). 코드를 바꿀 필요가 없습니다.
본문은 msitarzewski/agency-agents 의 현재 main 브랜치 기준으로 작성되었습니다(커밋: 2026-06-13). 이후 레포지토리에 부서가 추가되거나 스크립트 인터페이스가 조정될 수 있으니, 직접 작업하기 전에 먼저
git pull로 최신 버전을 동기화하는 것을 권장합니다.