agency-agents는 220개 이상의 전문 AI 에이전트 페르소나를 17개 사업 부서별로 조직화한 오픈소스 라이브러리입니다. 각 에이전트는 YAML 프론트매터 + 마크다운으로 정의되며, convert.sh 스크립트가 Claude Code·Cursor·Windsurf·Aider·Gemini CLI 등 12개 AI 도구에 맞는 포맷으로 자동 변환합니다. 단순 프롬프트 모음이 아니라 페르소나·미션·규칙·코드 예시·성과지표가 통합된 완성형 에이전트 라이브러리입니다.
범용 AI는 "모든 것을 조금씩" 압니다. 하지만 실제 업무에서는 백엔드 아키텍처 전문가, 마케팅 그로스해커, QA 엔지니어처럼 특정 분야 전문가가 필요합니다. agency-agents는 이런 전문가 144명을 미리 정의해 두고 Claude Code나 Cursor에 바로 투입할 수 있게 해줍니다.
핵심은 하나의 에이전트 정의(마크다운)에서 12개 도구용 포맷을 자동 생성한다는 것입니다. 에이전트를 한 번만 작성하면 어떤 도구에서도 쓸 수 있습니다.
Claude Code나 Cursor를 사용할 때 기본 AI는 제너럴리스트입니다. "백엔드 아키텍처 설계해줘"라고 하면 어떤 패턴이 좋은지, 성능 지표가 어떤지 구체적으로 모릅니다. 전문성이 부족한 AI와 일하면 결국 개발자가 더 많은 지시를 해야 합니다.
Backend Architect 에이전트를 로드하면 AI는 "PostgreSQL 조건부 인덱스, GIN 인덱스, sub-20ms 쿼리"를 알고, 보안(Defense in Depth)을 최우선으로 고려하고, 특정 성과 지표(API 응답 95th percentile 200ms 미만)를 기억합니다. 단순 프롬프트가 아닌 전문가의 사고 체계 전체를 주입합니다.
| 비교 대상 | agency-agents 장점 |
|---|---|
| awesome-prompts류 | 단순 프롬프트가 아니라 페르소나+미션+규칙+코드예시+성과지표 통합 |
| mattpocock/skills | 개인 설정 모음 vs 144개 전문 분야별 체계화된 조직 |
| 자체 에이전트 작성 | 검증된 템플릿과 워크플로우를 즉시 사용 가능 |
| Claude Code 내장 에이전트 | 17개 사업부 × 다양한 직군으로 훨씬 깊은 전문화 |
| 기술 | 역할 |
|---|---|
| Markdown (.md) | 에이전트 정의의 콘텐츠 형식 |
| YAML Frontmatter | 에이전트 메타데이터 (name, description, color, emoji, vibe) |
| Bash (convert.sh) | 마크다운 → 각 도구 포맷 변환 (병렬 실행 지원) |
| Bash (install.sh) | 인터랙티브 TUI 설치 스크립트 |
| 도구 | 변환 형식 | 설치 경로 |
|---|---|---|
| Claude Code | .md agents | ~/.claude/agents/ |
| GitHub Copilot | .md | ~/.github/agents/ + ~/.copilot/agents/ |
| Cursor | .mdc rules | .cursor/rules/ |
| Windsurf | .windsurfrules | 프로젝트 루트 |
| Aider | CONVENTIONS.md | 프로젝트 루트 (단일 파일) |
| OpenCode | .md agents | .opencode/agents/ |
| Gemini CLI | 서브에이전트 .md | ~/.gemini/agents/ |
| OpenClaw | SOUL.md + AGENTS.md + IDENTITY.md | 프로젝트 루트 |
| Qwen | SubAgent .md | ~/.qwen/agents/ |
| Antigravity | Skills | ~/.gemini/antigravity/skills/ |
| Kimi Code | YAML agent specs | ~/.config/kimi/agents/ |
| Codex | TOML custom agents | ~/.codex/agents/ |
각 에이전트는 일관된 구조를 따르는 마크다운 문서입니다. LLM에게 단순 지시가 아니라 전문가 페르소나 전체를 주입하여 일관된 행동을 유도합니다.
OpenClaw 변환 시 두드러지는 패턴입니다. 에이전트 콘텐츠를 Identity/Communication(→ SOUL.md)과 Mission/Workflow(→ AGENTS.md)로 헤더 키워드 기반으로 자동 분류합니다.
{부서}-{역할}.md 형식으로 통일 — engineering-backend-architect.md, marketing-growth-hacker.md, testing-accessibility-auditor.md
효과적인 AI 에이전트 페르소나 설계 방법을 배울 수 있습니다. 단순 "helpful assistant"가 아닌, 구체적 수치 목표를 포함한 Core Mission, 절대 위반 불가 Critical Rules, 실제 코드 예시를 담은 Technical Deliverables, 정량적 Success Metrics를 통해 LLM의 행동 패턴을 바꾸는 법을 익힐 수 있습니다.
하나의 소스에서 여러 도구용 포맷을 자동 생성하는 방법입니다. convert.sh의 핵심 로직은 YAML 프론트매터 파싱 → 도구별 포맷 변환 → 병렬 실행(--parallel --jobs 8)입니다. 단일 소스 진실(Single Source of Truth) 원칙의 좋은 사례입니다.
install.sh는 순수 Bash로 체크박스 UI를 구현합니다. 시스템 도구 자동 감지(which, 디렉토리 존재 확인), 비대화형 모드(--no-interactive) 지원으로 CI/CD 호환성을 갖춥니다.
프로젝트 목표에 따른 에이전트 팀 설계 방법을 배웁니다. Phase 1(목표 정의) → Phase 2(역할 매핑) → Phase 3(순서 결정) → Phase 4(품질 게이트: Reality Checker 최종 검증)의 프레임워크입니다.
Backend Architect 에이전트에 포함된 실전 PostgreSQL 패턴(조건부 인덱스, GIN 인덱스), Express.js 보안 미들웨어(helmet, rate-limit), CQRS·Event Sourcing·Circuit Breaker 패턴을 배울 수 있습니다.
Frontend Developer 에이전트에 담긴 가상화 테이블(@tanstack/react-virtual), Core Web Vitals(LCP < 2.5s, FID < 100ms, CLS < 0.1) 목표 설정, 실전 최적화 기법을 배울 수 있습니다.
| 항목 | 요구사항 |
|---|---|
| OS | macOS, Linux, Windows (WSL) |
| Bash | 4.0+ (스크립트 실행용) |
| Git | 필수 (레포 클론) |
| AI 도구 | Claude Code, Cursor, Copilot 중 최소 1개 |
| 디스크 | ~50MB (전체 에이전트 + 변환 결과물) |
| 인터넷 | 초기 클론 시에만 필요 |
특이사항: 코드 실행이 아닌 마크다운 에이전트 정의이므로 컴퓨팅 리소스가 거의 불필요합니다. AI 도구 자체의 요구사항이 실제 병목입니다.
engineering/ 디렉토리의 에이전트 하나를 읽고 구조를 파악합니다. CONTRIBUTING.md의 템플릿을 따라 자신의 전문 분야 에이전트를 작성합니다. 필수 포함: YAML frontmatter, Identity, Core Mission, Critical Rules, 코드 예시, Success Metrics.
git clone https://github.com/msitarzewski/agency-agents
cd agency-agents
./scripts/convert.sh
./scripts/install.sh --tool claude-codeClaude Code에서 @backend-architect처럼 에이전트를 호출해 실제 프로젝트에서 협업합니다.
자신의 프로젝트에 필요한 에이전트 3~5개를 선택하고, 작업 순서와 각 에이전트의 역할을 정의합니다. 실제로 순서대로 에이전트를 사용하며 프로젝트를 진행하고 결과를 examples/ 형식으로 문서화합니다.
새로운 AI 도구(예: Claude Desktop, Cline)용 변환 로직을 추가합니다. YAML frontmatter에 새 필드(예: difficulty, tags)를 추가하고, 변환 시 에이전트 간 의존성 그래프를 생성하는 기능을 구현합니다.
에이전트 정의의 완성도를 자동 평가하는 스크립트를 작성합니다. 평가 기준: frontmatter 완전성, 코드 예시 존재, 성과 지표 정량성. 전체 144개 에이전트에 대한 품질 리포트를 생성하고 부족한 에이전트를 개선하여 PR을 제출합니다.
| 주차 | 주제 | 핵심 학습 내용 |
|---|---|---|
| 1주차 | 에이전트 프롬프트 기초 | 레포 전체 구조 파악 / 에이전트 정의 템플릿 숙달 / Claude Code 기본 사용 / Anthropic 프롬프트 엔지니어링 가이드 |
| 2주차 | 에이전트 설계 심화 | 5개 이상 에이전트 분석 / 좋은 vs 나쁜 에이전트 비교 / Critical Rules 설계 패턴 / 자신만의 에이전트 3개 작성 |
| 3주차 | 멀티 도구 통합 | convert.sh 라인별 분석 / 각 도구 에이전트 포맷 차이 / install.sh TUI 구현 패턴 / 새 도구용 변환 로직 작성 |
| 4주차 | 팀 오케스트레이션 | 5가지 팀 조합 시나리오 실습 / 자신의 프로젝트 최적 팀 설계 / 에이전트 간 핸드오프 문서화 |
| 5주차 | 기여 및 확장 | CONTRIBUTING.md 숙달 / 부족한 분야 에이전트 작성 / convert.sh 새 도구 지원 / PR 제출 경험 |
| 키워드 | 설명 |
|---|---|
| Agent Persona | AI 에이전트에게 부여하는 전체 인격·전문성 정의. 단순 프롬프트보다 깊은 행동 패턴 유도 |
| YAML Frontmatter | 마크다운 파일 상단의 ---로 구분된 메타데이터 블록. name, description, color 등 포함 |
| Critical Rules | 에이전트가 절대 위반하면 안 되는 핵심 제약 조건 (예: "Security-First") |
| Success Metrics | 에이전트 성과를 정량적으로 측정하는 지표 (예: "API 응답 200ms 미만") |
| Tool-Agnostic | 특정 도구에 종속되지 않는 설계. 하나의 정의에서 여러 도구 포맷으로 변환 |
| Semantic Content Routing | 콘텐츠를 의미 기반으로 자동 분류하는 패턴 (OpenClaw의 SOUL/AGENTS 분리) |
| Team Assembly | 목표에 따라 여러 에이전트를 조합하여 협업 팀을 구성하는 전략 |
| Reality Checker | 배포 전 스크린샷 기반 증거로 품질을 검증하는 특수 에이전트 |
| Core Web Vitals | Google의 웹 성능 지표 (LCP, FID, CLS). Frontend Developer 에이전트의 핵심 목표 |
| Defense in Depth | 여러 보안 레이어를 겹치는 보안 전략. Backend Architect 에이전트의 핵심 원칙 |
| CQRS | Command Query Responsibility Segregation. 읽기/쓰기를 분리하는 아키텍처 패턴 |
| Event Sourcing | 상태 변화를 이벤트로 저장하는 데이터 패턴 |
| Circuit Breaker | 장애 전파를 막기 위해 실패하는 서비스 호출을 자동 차단하는 패턴 |
| .mdc | Cursor의 에이전트 규칙 파일 형식 (Markdown with Config) |
| CONVENTIONS.md | Aider가 사용하는 프로젝트 규약 파일. 모든 에이전트가 하나의 파일로 합쳐짐 |