agency-agents — 전문 역할형 AI 에이전트 명세집 + 멀티툴 변환/설치 툴킷

한 줄 요약: agency-agents는 “실행 가능한 앱”이라기보다, 도메인별 AI 에이전트 명세(prompt/persona/workflow) 저장소와 이를 여러 에이전트 코딩 툴 형식으로 변환·설치하는 Bash 기반 툴체인을 함께 제공하는 레퍼런스 프로젝트다.

핵심 해석: 이 저장소의 본질은 “에이전트 런타임”이 아니라 에이전트 사양(source of truth) + 배포 파이프라인 + 협업 운영모델(NEXUS) 이다.
실제 제품으로 구현하려면 오케스트레이터, 상태 저장소, 평가 체계, 보안/감사 레이어를 별도로 구축해야 한다.

Quick Links

Repository: https://github.com/msitarzewski/agency-agents
Main README: https://github.com/msitarzewski/agency-agents/blob/main/README.md
Integrations Guide: https://github.com/msitarzewski/agency-agents/blob/main/integrations/README.md
Examples Guide: https://github.com/msitarzewski/agency-agents/blob/main/examples/README.md
NEXUS Quick-Start: https://github.com/msitarzewski/agency-agents/blob/main/strategy/QUICKSTART.md
NEXUS Executive Brief: https://github.com/msitarzewski/agency-agents/blob/main/strategy/EXECUTIVE-BRIEF.md
MCP Memory Integration: https://github.com/msitarzewski/agency-agents/blob/main/integrations/mcp-memory/README.md
Discussions: https://github.com/msitarzewski/agency-agents/discussions
Wiki: https://github.com/msitarzewski/agency-agents/wiki (현재 별도 위키가 활성화되어 있지 않고 루트로 리디렉션되는 것으로 보임)
Demo Site: 저장소 기준 별도 데모 사이트 확인되지 않음
Paper: 저장소 기준 관련 논문 링크 확인되지 않음

Key Features

대규모 전문 에이전트 라이브러리
엔지니어링, 디자인, 마케팅, 제품, 테스트, 지원, 공간 컴퓨팅, 게임 개발, 학술, 세일즈, 특수 업무 등 다양한 폴더로 분리된 역할형 에이전트 명세를 제공한다.
각 에이전트를 “실행 가능한 역할 명세”로 정의
단순 프롬프트가 아니라 YAML frontmatter + 정체성/메모리 + 핵심 미션 + 규칙 + 기술 산출물 + 워크플로 + 성공 지표까지 포함한다.
멀티툴 포터블 아키텍처
Claude Code / GitHub Copilot 네이티브 사용 외에 Antigravity, Gemini CLI, OpenCode, Cursor, Aider, Windsurf, OpenClaw, Qwen Code, Kimi Code용 형식으로 변환할 수 있다.
자동 감지 설치기 제공
install.sh가 설치된 툴을 감지하고 대화형 또는 비대화형 방식으로 원하는 타깃에 배포한다. 병렬 설치도 지원한다.
NEXUS 운영모델 제공
단일 에이전트 호출을 넘어, Phase 0~6로 구성된 멀티에이전트 협업 운영모델과 Full / Sprint / Micro 실행 모드를 문서화한다.
실전형 예제 포함
스타트업 MVP, 메모리 기반 핸드오프, 공간 컴퓨팅 제품 탐색 등 실제 멀티에이전트 협업 예시가 제공된다.
지속 메모리(MCP) 확장 패턴
remember / recall / search / rollback을 갖는 MCP 메모리 서버와 결합해 세션 간 연속성과 QA 실패 시 복구 루프를 만들 수 있다.
품질 관리 스크립트 포함
lint-agents.sh가 frontmatter와 권장 섹션을 검사해 에이전트 파일의 일관성을 유지한다.
커뮤니티 신호가 강한 저장소
Discussions에서 Codex 지원, MCP 기반 동적 팀 구성, ADA/접근성, solo-builder 온보딩 등의 아이디어가 논의되고 있어 확장 방향을 읽기 좋다.

Tech Stack

1) 실제 저장소의 핵심 스택

Layer	Stack	Version / Note
Source format	Markdown (`.md`) + YAML frontmatter	버전 고정 없음
Automation	Bash shell scripts	`convert.sh`, `install.sh`, `lint-agents.sh`
Shell utilities	`awk`, `sed`, `grep`, `find`, `xargs`, `head`, `mktemp`, `cp`	POSIX/Unix 계열 환경 친화적
Generated artifacts	`SKILL.md`, `.mdc`, `CONVENTIONS.md`, `.windsurfrules`, `agent.yaml`, `SOUL.md`/`AGENTS.md`/`IDENTITY.md`	툴별 출력 형식
Installation targets	Claude Code, GitHub Copilot, Antigravity, Gemini CLI, OpenCode, Cursor, Aider, Windsurf, OpenClaw, Qwen Code, Kimi Code	설치 경로가 각기 다름
Validation	`lint-agents.sh`	필수 frontmatter 필드 검사
Strategy docs	`strategy/`, `examples/`, `integrations/mcp-memory/`	런타임 코드가 아닌 운영 문서

2) 버전 관련 관찰

중앙 패키지 매니저 파일이 없다: package.json, pyproject.toml, requirements.txt, Cargo.toml, Dockerfile 같은 전통적 애플리케이션 루트 의존성 정의를 중심으로 움직이는 저장소가 아니다.
버전 핀은 거의 없다: 필수 라이브러리 버전을 고정하는 방식보다, 에이전트 명세와 변환 스크립트 중심으로 구성되어 있다.
명시적으로 보이는 버전 정보는 제한적:
- 생성되는 Gemini extension manifest의 버전은 1.0.0
- 일부 에이전트 예시 문서에서 WCAG 2.1 AA 같은 표준 버전 표기가 보인다.
따라서 “필수 라이브러리(버전 포함)” 항목은 일반 소프트웨어 프로젝트처럼 채우기 어렵고, 이 저장소에서는 “실제 런타임 의존성”보다 “타깃 포맷과 툴 호환성” 이 핵심이다.

3) 에이전트 예시 내부에서 등장하는 기술 스택 (참고용, 저장소 의존성 아님)

Context	Referenced Technologies	Version Info
Frontend agent example	React, TypeScript, `@tanstack/react-virtual`	구체 버전 미기재
Workflow examples	Node.js, Express, PostgreSQL, Socket.io, React, Tailwind	구체 버전 미기재
DevOps agent example	GitHub Actions, Terraform, Prometheus	구체 버전 미기재
Accessibility guidance	WCAG 2.1 AA	명시됨

중요: 위 라이브러리들은 저장소 자체의 실행 의존성이 아니라, 에이전트가 산출해야 할 예시 결과물 안에 등장하는 기술들이다.

Architecture

먼저 짚어야 할 점

이 프로젝트의 “아키텍처”는 보통의 웹서비스처럼 API 서버 / DB / 프런트엔드 구조가 아니다.
대신 아래처럼 동작하는 콘텐츠-컴파일-설치 파이프라인에 가깝다.

Source Agent Specs (.md + YAML)
        ↓
convert.sh (tool-specific generation)
        ↓
integrations/<tool>/*
        ↓
install.sh (detect + deploy)
        ↓
Target Tool Runtime (Claude/Cursor/Aider/...)

여기에 별도로,

strategy/ = 멀티에이전트 운영모델(NEXUS)
examples/ = 실제 협업 시나리오
integrations/mcp-memory/ = 지속 메모리 확장 패턴

이 얹혀서 “어떻게 여러 에이전트를 함께 움직일 것인가” 를 설명한다.

Analyst-generated figures

저장소를 검사한 범위에서는 원본 아키텍처 다이어그램 / UI 스크린샷 / GIF 가 명확히 보이지 않았다.
아래 그림들은 저장소 문서와 스크립트 구조를 바탕으로 분석자가 재구성한 참고용 도식이다.

Repository map

Architecture overview

NEXUS coordination model

Memory-enabled handoff model

Layer-by-layer interpretation

1. Source-of-truth layer

실제 핵심 자산은 각 폴더에 있는 .md 에이전트 파일이다.
파일 하나가 하나의 전문가 역할을 나타내며, 최소한 다음 특성을 가진다.

name, description, color 같은 frontmatter
역할 정체성(Identity & Memory)
핵심 미션(Core Mission)
반드시 지켜야 할 규칙(Critical Rules)
기술 산출물 예시(Technical Deliverables)
워크플로 단계(Workflow Process)
성공 지표(Success Metrics)

즉, 이 저장소는 “프롬프트 카탈로그”라기보다 역할 명세 DSL에 가까운 Markdown 규약 모음으로 볼 수 있다.

2. Compilation layer

convert.sh는 표준 에이전트 디렉터리를 순회하면서 frontmatter를 파싱하고, 각 타깃 툴이 기대하는 포맷으로 변환한다.

핵심 포인트:

소스는 Markdown 하나로 유지
타깃별 출력은 integrations/ 아래에 생성
일부 툴은 에이전트별 파일을 받고, 일부는 단일 집계 파일을 받음
- 예: Cursor는 .mdc rule files
- Aider는 CONVENTIONS.md
- Windsurf는 .windsurfrules
- OpenClaw는 SOUL.md + AGENTS.md + IDENTITY.md

이는 “one source, many runtimes” 패턴으로, 에이전트 사양의 이식성을 매우 높인다.

3. Installation layer

install.sh는 사용 환경을 감지해 툴별 설치 경로로 파일을 복사한다.

예시:

Claude Code → ~/.claude/agents/
Copilot → ~/.github/agents/, ~/.copilot/agents/
Cursor → .cursor/rules/
Aider → ./CONVENTIONS.md
Windsurf → ./.windsurfrules
Qwen → ~/.qwen/agents/
Kimi → ~/.config/kimi/agents/

즉, 저장소는 자체 런타임을 실행하는 대신 외부 에이전트 코딩 툴들의 공급원(source distributor) 역할을 한다.

4. Orchestration docs layer

strategy/와 examples/가 특히 중요하다.

strategy/QUICKSTART.md는 NEXUS-Full / Sprint / Micro 모드와 7개 phase를 정의한다.
strategy/EXECUTIVE-BRIEF.md는 NEXUS를 “운영 체계” 관점에서 설명한다.
examples/는 수동 핸드오프와 메모리 기반 핸드오프 차이를 실제 예제로 보여준다.
specialized/agents-orchestrator.md는 개발 파이프라인 전체를 관리하는 오케스트레이터 역할을 정의한다.

즉, 저장소는 역할 정의 + 협업 프로토콜 + 품질 게이트까지 함께 제공한다.

5. Optional persistent memory layer

integrations/mcp-memory/README.md는 에이전트 파일 자체를 크게 바꾸지 않고도,
MCP memory server를 붙여 세션 간 상태 지속성을 확보하는 패턴을 제안한다.

이 부분이 중요한 이유:

수동 copy-paste 핸드오프 제거
QA 실패 시 rollback 가능
장기 프로젝트 / 다회 세션 / 다중 역할 협업에 적합

이는 향후 자율형 에이전트 시스템에서 매우 강력한 확장 포인트다.

Usage & Setup

1) 가장 단순한 사용 방식

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

2) Claude Code에 바로 쓰기 (네이티브 포맷)

# README의 가장 빠른 시작 방식
cp -r agency-agents/* ~/.claude/agents/

또는:

./scripts/install.sh --tool claude-code

3) 다른 툴로 변환 후 설치

# 모든 지원 포맷 생성
./scripts/convert.sh

# 설치 툴 자동 감지 + 대화형 선택
./scripts/install.sh

4) 특정 툴만 설치

./scripts/install.sh --tool cursor
./scripts/install.sh --tool copilot
./scripts/install.sh --tool aider
./scripts/install.sh --tool windsurf
./scripts/install.sh --tool kimi

5) 병렬 실행

./scripts/convert.sh --parallel
./scripts/install.sh --no-interactive --parallel
./scripts/install.sh --no-interactive --parallel --jobs 4

6) 린트 / 품질 확인

./scripts/lint-agents.sh

7) 새 에이전트 추가 시 추천 루프

# 1. 적절한 카테고리에 새 agent.md 작성
# 2. lint
./scripts/lint-agents.sh

# 3. 타깃 포맷 재생성
./scripts/convert.sh

# 4. 원하는 툴에 설치
./scripts/install.sh --tool claude-code

8) 툴별 실무 메모

Claude Code / GitHub Copilot: 네이티브 .md 사용. 변환 없이 바로 설치 가능.
Gemini CLI / Kimi / Qwen / Cursor / Aider / Windsurf / OpenClaw / OpenCode: 툴별 출력 형식이 달라서 변환 단계가 중요하다.
프로젝트 스코프 설치:
- Cursor
- Aider
- Windsurf
- OpenCode
- Qwen Code
  같은 도구는 현재 작업 디렉터리 기준으로 설치되는 흐름이 많다.
운영체제 가정: Bash + Unix 유틸리티 기반이므로 macOS/Linux 스타일 환경에서 가장 자연스럽다.

Community / Wiki / Discussion Analysis

Wiki

별도 위키는 사실상 비활성 상태로 보인다. 위키 URL이 저장소 루트로 되돌아간다.
따라서 문서의 중심은 README, integrations/, strategy/, examples/다.

Discussions

현재 논의되는 주제는 저장소가 어디로 가고 있는지를 잘 보여준다.

주요 신호:

Codex 통합 요청
MCP 서버를 통한 동적 에이전트 팀 구성
ADA / 접근성 모드 제안
Solo builder용 온보딩 경로
외부 AI 툴 디렉터리 등록 등 생태계 확장

즉, 커뮤니티는 단순히 “에이전트를 더 추가하자”보다
패키징, 툴 호환성, 접근성, 조합 가능한 팀 오케스트레이션 쪽으로 관심이 이동하는 중이다.

Personal Insights

1) 의료 AI 관점

이 저장소는 의료 도메인 전용 프로젝트가 아니지만, 의료 AI 시스템 설계 패턴으로서 매우 흥미롭다.

영감을 주는 포인트

전문 역할 분리
진단 보조, 가이드라인 검색, 규제 검토, 환자 커뮤니케이션, 운영 자동화 등 역할을 분리해 설계하기 좋다.
품질 게이트 / handoff 구조
NEXUS나 Dev↔QA 루프는 의료처럼 실수가 비싼 환경에서 특히 중요하다.
메모리 + rollback 패턴
장기 환자 사례 요약, multidisciplinary review, 임상 운영 workflow 자동화에 적합한 아이디어다.
Governance-first 사고
automation-governance-architect 같은 패턴은 의료기관의 SOP, 접근 권한, 추적성, 변경 관리와 잘 맞는다.

실제 구현 시 필요한 보강

사람(의사/임상전문가) 승인 단계
데이터 provenance 및 audit log
근거 문헌 citation 강제
HIPAA/GDPR/국가별 의료 규제 대응
hallucination 억제용 structured retrieval / evidence binding

요점: 의료 AI에 바로 투입할 수 있는 프로젝트는 아니지만, “역할 분리 + 품질 게이트 + 추적 가능한 handoff” 는 의료용 agent system 설계에 매우 좋은 참고 패턴이다.

2) Bioinformatics 관점

Bioinformatics / computational biology 쪽에서는 특히 phase-based orchestration 이 유용하다.

가능한 매핑 예시:

Discovery agent → 논문/데이터셋 탐색
Backend/Data agent → 파이프라인 인프라 및 저장 전략
QA / Evidence agent → 결과 재현성 검증
Product / PM agent → 분석 요구사항, 산출물 정리
Memory integration → 실험 맥락, 중간 산출물, 파라미터 기억

왜 잘 맞는가

분석이 장기적이고 세션이 분산됨
실험 조건과 파라미터 추적이 중요함
실패했을 때 rollback / checkpoint 개념이 유용함
wet-lab ↔ dry-lab handoff 문서화가 중요함

구현 아이디어

remember에 샘플 ID, reference genome, pipeline version, QC result 저장
handoff template를 이용해 wet-lab → bioinformatics → statistician 전달 표준화
QA loop로 differential expression / variant calling / pathway analysis 결과 검증 체계화

요점: 이 저장소는 생물정보학 코드를 직접 제공하지 않지만, 재현 가능한 다단계 분석 파이프라인을 agent-based로 관리하는 방법론 에 큰 영감을 준다.

3) Autonomous Agent 관점

이 저장소가 가장 강하게 주는 메시지는
“좋은 autonomous system은 똑똑한 단일 에이전트보다, 좋은 인터페이스/규약/핸드오프를 가진 여러 역할의 조합” 이라는 점이다.

가장 인상적인 설계 포인트:

One source of truth
에이전트 정의를 한 포맷으로 유지하고 타깃 툴로 컴파일한다.
Prompt portability
툴이 바뀌어도 역할 명세를 재사용할 수 있다.
Quality loops over raw autonomy
자율성보다 Dev↔QA loop, retry, escalation이 실제 품질에 더 중요하다.
Memory as an extension, not a requirement
기본은 stateless지만 필요할 때 stateful로 확장할 수 있다.
Operating model as product moat
NEXUS는 단순 프롬프트 묶음보다 한 단계 위의 “운영 체계”다.

이 저장소를 바탕으로 실제 Autonomous Agent 제품을 만든다면 추가로 필요한 것

실제 에이전트 레지스트리/API
작업 큐와 상태 머신
평가 harness / benchmark suite
observability / tracing
policy engine / permissioning
vector/RAG or memory backend
UI or dashboard
human-in-the-loop approval flow

요점: 이 저장소는 “agent operating system의 사양 레이어” 를 보여준다.
제품화하려면 그 위에 런타임, 기억, 평가, 보안 계층을 쌓아야 한다.

Caveats & Notable Observations

문서상 수치가 완전히 일치하지 않는다
- README Stats: 144 agents / 12 divisions
- README Acknowledgments: 147 agents / 12 divisions
- convert.sh의 source agent directories: 13개 카테고리
- NEXUS Executive Brief는 9 divisions 중심으로 설명
  → 즉, 저장소가 빠르게 성장하면서 문서 숫자가 완전히 동기화되지는 않은 상태로 보인다.
lint-agents.sh 대상 폴더가 install/convert보다 좁다
- install.sh / convert.sh는 academic, sales 등을 포함해 더 넓게 처리
- lint-agents.sh는 일부 폴더가 빠져 있음
  → 실제 유지보수 시 린트 범위를 스크립트 간 일치시키는 것이 좋다.
런타임 코드보다 운영 문서가 더 중심이다
- 실제 애플리케이션을 기대하고 들어오면 다소 당황할 수 있다.
- 반대로 프롬프트 엔지니어링, 멀티에이전트 설계, 역할 기반 오케스트레이션을 배우려는 사람에게는 매우 높은 참고 가치가 있다.
원본 이미지 자산은 거의 보이지 않는다
- 아키텍처 다이어그램/GIF/UI 스크린샷보다 텍스트 문서 중심 저장소다.
- 그래서 본 아카이브의 figures/는 분석 보조용 재구성 다이어그램 위주로 구성했다.

Sources Analyzed

이번 요약은 아래 자료를 중심으로 작성했다.

README.md
scripts/convert.sh
scripts/install.sh
scripts/lint-agents.sh
examples/README.md
examples/workflow-startup-mvp.md
examples/workflow-with-memory.md
integrations/README.md
integrations/mcp-memory/README.md
strategy/QUICKSTART.md
strategy/EXECUTIVE-BRIEF.md
engineering/engineering-frontend-developer.md
engineering/engineering-backend-architect.md
engineering/engineering-ai-engineer.md
engineering/engineering-devops-automator.md
engineering/engineering-autonomous-optimization-architect.md
product/product-manager.md
specialized/agents-orchestrator.md
specialized/automation-governance-architect.md
GitHub Discussions 목록
Wiki URL 동작

Bottom Line

이 저장소를 한 문장으로 정리하면:

“전문 에이전트 정의를 하나의 소스 포맷으로 유지하고, 여러 AI 코딩 툴에 맞게 배포하면서, NEXUS라는 운영 모델로 멀티에이전트 협업까지 설계한 prompt-ops 레퍼런스 저장소”

실제로 구현 대상으로 삼는다면, 가장 먼저 가져갈 만한 것은 다음 세 가지다.

에이전트 파일 규약
변환/배포 파이프라인
NEXUS + MCP memory 기반의 협업 운영모델

'AI 생성 글 정리 > tech_github' 카테고리의 다른 글

OpenScreen — 오픈소스 Screen Studio 대안, Electron 기반 데스크톱 데모 레코더/에디터 (0)	2026.04.09
PageIndex — 벡터 DB 없이 문서 구조와 LLM 추론으로 검색하는 reasoning-based RAG (0)	2026.04.09
Daytona — AI가 생성한 코드를 실행하기 위한 보안형·탄력형 샌드박스 플랫폼 (0)	2026.04.09
Hermes Agent — self-improving 멀티채널 AI agent runtime (0)	2026.04.08
Unsloth — unified local interface for running and training AI models (0)	2026.04.08