저장소 에이전트 팀 오케스트레이션 (메타 프로젝트 팀 오케스트레이션)
프로젝트에 특화된 에이전트 팀을 구성, 감사, 최적화하기 위한 자율 스킬입니다.
이 스킬은 저장소 구조를 분석하고, 필요한 특화 분야(GitHub 관리자, DevOps, QA, UI/UX, 보안, 제품 분석가, 법률, 합의 심판 등)를 식별하며, .agents/team/ 디렉토리에 격리된 프로필을 생성하고, 엄격한 조정 프로토콜(인간 개입, 사용자 중재 핸드오프, 불변 노트, 증거 기반 중재)을 수립합니다.
스킬 호출 시기
- 사용자가 요청하는 경우: "에이전트 팀 구성", "프로젝트에 역할 배정", "에이전트 역할 구성", "팀 활동 감사", "팀 역할 검토", "에이전트 팀 구성 업데이트"
- 프로젝트에 Docker, CI/CD, 모바일 UI, 데이터베이스, 외부 결제 통합 등 새로운 주요 기술 계층이 도입되어 전담 도메인 거버넌스가 필요한 경우
실행 단계
1단계: 빠른 저장소 스캔 (마커 검사)
역할을 정의하기 전에 에이전트는 주요 프로젝트 마커를 검사해야 합니다:
- 호스팅 및 CI 인프라:
.github/디렉토리, 워크플로우, 풀 리퀘스트 템플릿, 이슈 템플릿의 존재 여부. - 라이선스 및 오픈소스 거버넌스:
LICENSE, 저작권,CONTRIBUTING.md, 의존성 매니페스트의 존재 여부. - 컨테이너화 및 오케스트레이션:
Dockerfile,docker-compose*.yml,k8s/,helm/. - 테스트 인프라:
tests/디렉토리,pytest.ini,vitest.config.*, 테스트 픽스처. - 보안 및 민감 데이터:
auth/,security/디렉토리, 토큰 처리, 세션 관리, 암호화 로직. - 사용자 인터페이스 및 디자인: 프론트엔드 모듈, HTML/CSS, 봇 키보드 레이아웃, 에셋, 디자인 토큰.
- 현재 프로젝트 여권:
AGENTS.md및.agents/project_knowledge/슬라이스 읽기 (이미 초기화된 경우). - 2차 / 폴리글롯 스택: 컴파일된 언어 또는 대체 언어 소스 파일(예:
client/,native/,core/,desktop/디렉토리의.cpp,.c,.h,.rs,.go,.swift)을 포함하는 하위 디렉토리.
2단계: 규모 적응형 크기 조정 및 개방 역량 매트릭스
역할을 제안하기 전에 에이전트는 저장소 규모를 평가하고 최소한으로 충분한 팀을 구성해야 합니다.
1. 저장소 크기 조정 및 역할 합성
에이전트는 코드베이스 규모(LOC, 폴더 깊이, 기술 다양성)를 추정합니다:
-
초소형 / 소형 저장소 (<1만 라인, 단일 개발자, 1~2개의 주요 스택): 매트릭스의 역량 블록을 통합 프로필로 묶어 2~3개의 결합 역할을 합성합니다.
- 표준 초소형 삼중 구성:
agent-dev-lead: 수집 분석, 작업 분해, 일반 코드 구현(agent-intake-dispatcher+agent-general-worker)을 결합합니다.agent-quality-guardian: 여권/지식 무결성, 단위 테스트 스위트, 데드 코드 감사(agent-meta-guardian+agent-qa-engineer+agent-deep-auditor)를 결합합니다.agent-github-steward: Git 위생, 컨벤셔널 커밋, Code-to-README 진실성, CI/CD를 담당합니다.
- 표준 초소형 삼중 구성:
-
중형 저장소 (1만~5만 라인, 소규모 팀, 여러 서비스): 주요 구성 요소에 맞춰 3~5개의 전용 역할을 배치합니다.
-
대형 / 엔터프라이즈 저장소 (>5만 라인, 모노레포, 마이크로서비스): 엄격한 관심사 분리로 6개 이상의 세분화된 역할을 배치합니다.
-
폴리글롯 스택 격리 규칙 (유해 번들 금지): C/C++, Rust, Go, 네이티브 GUI와 같은 2차 컴파일 또는 특수 스택을 전용 스킬 없이
agent-general-worker에 번들링하는 것을 엄격히 금지합니다. 폴리글롯 스택이 감지되면 전용 역할(예: 네이티브 컴파일러 및 툴체인이 있는agent-native-desktop)을 합성하거나, 네이티브 디렉토리를 Red Zone에 명시적으로 매핑하고 필수 핸드오프 트리거를 설정합니다. -
필수 디스패처 규칙 (다중 역할 혼란 금지): 3개 이상의 특수 역할을 배치할 때는 수집 디스패처(
agent-intake-dispatcher또는agent-dev-lead에 통합된 디스패처)를 반드시 배치해야 합니다. 단일 진입점 없이 여러 개의 격리된 역할을 사용자에게 라우팅되지 않은 채로 남겨두는 것을 금지합니다.
2. 개방 역량 카탈로그 (역할 매트릭스)
[!IMPORTANT] 아래 표는 개방 역량 카탈로그이며, 불변의 닫힌 열거형이 아닙니다. 에이전트는 저장소의 실제 아키텍처에 맞는 결합 역할을 합성하거나 사용자 지정 도메인별 역할(예:
agent-solana-smart-contracts,agent-3d-designer,agent-data-pipeline)을 자유롭게 창안할 수 있습니다.
| 카테고리 | 역량 블록 / 역할 | 저장소 마커 | 특화 스킬 | 책임 경계 |
|---|---|---|---|---|
| 기본 역할 | agent-general-worker(기본 작업자 / 제너럴리스트) | 모든 프로젝트 (기본 역할) | clean-codecode-reviewersystematic-debugging + 스택 스킬 | 초록: 기능 구현, 스크립트, 테스트, 버그 수정.노랑: API 계약 및 의존성 수정.빨강: 파괴적 작업 및 핸드오프 없는 특수 도메인 모듈. |
| 오케스트레이션 | agent-intake-dispatcher(수집 디스패처) | 2개 이상의 역할이 있는 모든 프로젝트 | prompt-engineeringbrainstorming | 초록: 요청 분해, 프롬프트 준비, 빠른 실행.빨강: 프로젝트 소스 코드 직접 수정. |
| 오케스트레이션 | agent-meta-guardian(메타 프로젝트 가디언) | meta-project 구조 존재 | clean-codecode-reviewer | 초록: 여권 감사, 역할 텔레메트리, 지식 베이스 유지 관리.노랑: 비활성 역할 보관.빨강: 사용자 확인 없이 지식 베이스 삭제. |
| 오케스트레이션 | agent-consensus-judge(중재자 및 합의 심판) | 논쟁이 있는 결정이 있는 프로젝트 | architecture-decision-recordsapi-design-principles | 초록: 주장 비교, 경험적 테스트 검증.노랑: ADR 작성.빨강: 경험적 증거 없이 결정 내리기. |
| 오케스트레이션 | agent-deep-auditor(전체 저장소 심층 감사자) | 성숙한 코드베이스 (>500라인) | systematic-debuggingcode-reviewer | 초록: 감사 보고서 생성, 데드 코드 감지, 링크/앵커 무결성 검증.노랑: 발견 사항을 관찰 기록에 기록.빨강: 파괴적 리팩토링, 자율 파일 삭제. |
| 제품 및 비즈니스 | agent-product-roaster(제품 분석가 및 비평가) | 제품 서비스, 스타트업 | search_webbrainstorming | 초록: 경쟁 분석, 가설 스트레스 테스트.빨강: 사양 없이 비즈니스 로직 변경. |
| 제품 및 비즈니스 | agent-creative-director(크리에이티브 디렉터) | UI 컴포넌트, 웹, 테마, 아이콘 | image-generatorcss-tokens | 초록: 색상 팔레트, 아이콘, 배너 생성.노랑: 전역 스타일 편집.빨강: 확인 없이 브랜드 아이덴티티 교체. |
| 제품 및 비즈니스 | agent-ui-ux-engineer(UI/UX 엔지니어) | 프론트엔드, 봇, 인터페이스 | semantic-htmlcss-coderui-ux-invariants | 초록: 컴포넌트 레이아웃, FSM 상태.노랑: 화면 탐색 변경.빨강: 파괴적 작업에 대한 확인 제거. |
| 제품 및 비즈니스 | agent-legal-compliance(법률 및 규정 준수 감사자) | LICENSE, 공개 저장소 | SPDX/SBOM 감사 | 초록: 의존성 라이선스 감사.노랑: NOTICE 및 헤더 저작권 업데이트.빨강: 저장소 라이선스 변경. |
| 엔지니어링 | agent-github-steward(GitHub 전문가 및 릴리스 책임자) | .github/, git 원격 | github-managementgithub-actions-creatorclean-codecode-reviewer | 초록: Git 위생, 컨벤셔널 커밋, 브랜치 관리, 이슈 분류, 릴리스 초안 작성.노랑: Code-to-README 일치성 확인(README 지침/CLI가 실제 코드와 일치하는지 확인), CI/CD 조정.빨강: force-push, 리뷰 없이 main에 병합, 시크릿 수정. |
| 엔지니어링 | agent-devops-infra(인프라 아키텍트) | Dockerfile, docker-compose* | docker-expertkubernetes-architectbash-linux | 초록: 개발 컨테이너, 구성 린팅.노랑: 멀티 스테이지 빌드 최적화.빨강: 프로덕션 시크릿, .env*, 프로덕션 k8s. |
| 엔지니어링 | agent-qa-engineer(신뢰성 및 QA 엔지니어) | tests/, 테스트 프레임워크 | test-driven-developmentverification-before-completion | 초록: 단위/통합 테스트 작성, 테스트 실행 확인.노랑: 테스트 러너 및 계약 어설션 구성.빨강: CI에서 테스트 비활성화. |
| 엔지니어링 | agent-tech-writer(테크니컬 라이터) | docs/, OpenAPI, Swagger | mermaid-diagram-specialistopenapigoogle-style-guide | 초록: 함수 문서화, README, 다이어그램.노랑: API 사양 편집.빨강: 검토되지 않은 문서 게시. |
3단계: 기존 팀 감사 (역할 정리 및 가비지 컬렉션)
.agents/team/ 디렉토리가 이미 존재하는 경우:
- 모든 폴더 스캔:
.agents/team/*/profile.md. - 각 프로필의
역할 호출 로그 (텔레메트리)테이블 검사. - 비활성 또는 쓸모없는 역할 식별:
- 역할이 초기화되었지만 로그에 초기 항목만 있고 30일 이상 실제 호출이 없는 경우.
- 역할의 기본 기술 스택이 프로젝트에서 완전히 제거된 경우(예: Docker가 해체되었지만
agent-devops-infra가 남아 있는 경우).
.agents/team/archive/<role_id>/로 보관할 후보 목록 컴파일.- 자율 삭제 금지: 역할 보관은 명시적인 사용자 승인이 필요합니다!
4단계: 대화 및 사용자 조정
사용자를 위한 간결한 제안 보고서 생성:
- 감지된 마커: 확인된 프로젝트 구성 요소 목록.
- 활성화할 권장 역할: 기본 작업자(
agent-general-worker) + 감지된 마커와 일치하는 2~4개의 가장 중요한 도메인 역할 및 간략한 근거. - 보관 후보: (비활성 역할이 있는 경우).
- 승인 프롬프트: "다음 역할 프로비저닝을 승인하시겠습니까: [...]?"
5단계: 프로필 구체화 및 여권 등록
사용자 확인 후 프로덕션 쓰기 수행:
- 각 승인된 역할에 대한 디렉토리 생성:
.agents/team/<role_id>/. - 참조 템플릿
templates/team/profile.md(또는 아래 포함된 템플릿)를 사용하여.agents/team/<role_id>/profile.md스캐폴딩:- 역할 ID, 범위, 호출 트리거, 활성 스킬, 경계 권한을 채웁니다.
- 현재 날짜로 텔레메트리 테이블 초기화.
- 비공개 노트 파일 생성:
.agents/team/<role_id>/notes.md(참조 템플릿templates/team/notes.md또는 아래 포함된 템플릿 사용). - 참조 템플릿
templates/team/system_prompt.md(또는 아래 포함된 템플릿)를 사용하여 초기 즉시 사용 가능한 시스템 프롬프트.agents/team/<role_id>/system_prompt.md생성:- 역할 이름, 목적, 스킬 스택, 표준 경계 권한(초록/노랑/빨강)을 채웁니다.
- 루트
AGENTS.md의 다음 섹션 아래에 역할 등록:## 6. 프로젝트 에이전트 팀 (.agents/team/) - [{{ROLE_TITLE}}](.agents/team/{{ROLE_ID}}/profile.md) — {{ROLE_SCOPE}} (호출: {{ROLE_TRIGGERS}}) - 긴 프롬프트 텍스트로 채팅을 스팸하지 않도록 사용자에게 간결한 빠른 실행 테이블 생성 및 표시:
| 역할 | 목적 | 시스템 프롬프트 경로 | 트리거 키워드 | | :--- | :--- | :--- | :--- | | `agent-qa-engineer` | 테스트 및 검증 | `.agents/team/agent-qa-engineer/system_prompt.md` | "테스트 실행", "검증 확인" |
6단계: 팀 규칙
모든 팀 에이전트는 핵심 조정 원칙을 준수해야 합니다:
- 사용자 주도 수동성: 에이전트는 명시적인 사용자 지시 없이 백그라운드 작업을 수행하지 않습니다.
- 사용자 중재 핸드오프: 에이전트는 사용자를 우회하여 서로에게 직접 제어권을 전송하지 않습니다. 작업에 다른 도메인이 필요한 경우 에이전트는 구조화된 핸드오프 패키지를 사용자에게 반환합니다:
### 작업 핸드오프 패키지: [agent-A -> agent-B] - 원래 목표: <요청된 내용> - 완료된 작업: <수정된 파일 목록> - 핸드오프 경계: <현재 에이전트가 중단된 이유> - agent-B에 대한 권장 프롬프트: <즉시 사용 가능한 프롬프트 텍스트> - 핸드오프 체인 제한: 최대 2개의 연속 핸드오프(홉 = 2). 3번째 단계에서는 제어권이 사람에게 반환되어야 합니다.
- 공유 파일 주석 성역:
tasks.md,observations.md,architecture.md에서 다른 사람의 노트를 편집하는 것이 금지됩니다. 자신의 상태/작업만 업데이트할 수 있습니다. 충돌 시 사용자에게 트레이드오프에 대한 명확한 설명을 제시합니다. notes.md에 대한 독점 소유권: 역할 소유자만.agents/team/<role>/notes.md를 수정할 수 있습니다.- 증거 기반 중재:
agent-consensus-judge는 테스트 결과, 벤치마크 측정값, 공식 사양에 따라 엄격하게 판결을 내립니다. - 병렬 하위 에이전트 위임 (
dispatching-parallel-agents): 반복적이거나 병렬적이거나 다중 디렉토리 일괄 작업(예: 다중 파일 마이그레이션, 여러 테스트 스위트 생성, 대량 린팅/감사)을 처리할 때 기본 에이전트는dispatching-parallel-agents스킬을 반드시 호출해야 합니다. 상위 에이전트는 겹치지 않는 디렉토리 또는 작업별로 작업을 일시적인 하위 에이전트에 분할하고,AGENTS.md의 프로젝트 불변 조건과 역할 경계를 전달합니다. 상위 에이전트는 완료를 조정하고, 무결성 테스트를 실행하며, 중간 하위 에이전트 핸드오프로 사람에게 부담을 주지 않고 통합 보고서를 사용자에게 반환합니다. - 회로 차단기 (2번째 반복 시 작업 중단): 버그 수정에 동일한 모듈에서 2번째 연속 편집이 필요하거나 인접 코드에서 2차 회귀를 생성하는 경우 코드 작성을 중단합니다. 확대하여 원본에서 소비자까지 전체 데이터 수명 주기를 추적하고, 아키텍처 근본 원인을 식별하며, 새로운 diff를 제안하기 전에 시스템 분석을 제시합니다.
- 목표 상태 감사: 노랑 또는 빨강 영역에서 중요하지 않은 모듈을 수정하기 전에 단일 코드 경로가 아닌 전체 구성 요소 수명 주기와 데이터 흐름을 고려하십시오.
포함된 파일 템플릿
[선택 사항] 이 섹션에는
profile.md,notes.md,system_prompt.md에 대한 표준 템플릿이 포함될 수 있습니다. 내용을 번역하지 않고 원래 템플릿 구조를 유지하십시오.
관련 스킬
dispatching-parallel-agents: 병렬 하위 에이전트 위임을 위해 이 스킬에 의해 호출됩니다.manage-project-knowledge: 메타 프로젝트 가디언이 사용하는 프로젝트 지식 베이스 관리.