tri-agent-manager

Claude Code, Gemini CLI, Codex 3개 AI 에이전트용 서비스 운영 스킬/워크플로우 설치기입니다.

공통 정의(common/) 하나로 3개 플랫폼에 동일한 운영 역량을 배포합니다.

아키텍처 개요

common/                          ← 단일 원천 (Single Source of Truth)
  skills/skill-catalog.json         스킬 8개 (플랫폼별 procedures 포함)
  commands/command-catalog.json     명령 20개
  workflows/workflow-catalog.json   워크플로우 5개 (Gemini CLI 전용)
  settings/security-policy.json     보안 정책
  claude/subagent-catalog.json      Claude 서브에이전트 15개
  claude/team-catalog.json          Claude 팀 3개
  gemini/agent-catalog.json         Gemini 에이전트 카탈로그
  gemini/artifact-catalog.json      Gemini 아티팩트 계약
       │
       ▼  npm run generate
       │
  ┌────┴────────────────────────────────────────────┐
  │                                                  │
claude-code/          gemini/              codex/
  skills/               skills/              skills/
  subagents/            agents/              skills/cmd-*/
  agent-teams/          artifacts/           automations/
  commands/native/      commands/definitions/  commands/
    *.md (Slash Cmd)      *.toml (Extension)   command-catalog.json
  instructions/         workflows/           instructions/
    CLAUDE.template.md    definitions/*.yaml   AGENTS.template.md
  settings/             gemini-extension.json  settings/
    settings.json       instructions/
                          GEMINI.template.md

빠른 시작

# 대화형 설치 (프리셋 선택 → 도구/구성요소 선택 → 설치)
npx --yes --package @dusky-bluehour/agent-service tri-agent-manager --interactive

# 명시적 install / update
npx --yes --package @dusky-bluehour/agent-service tri-agent-manager install --interactive
npx --yes --package @dusky-bluehour/agent-service tri-agent-manager update --interactive

# Non-interactive (CI/스크립트용)
npx --yes --package @dusky-bluehour/agent-service tri-agent-manager install \
  --preset balanced-core --target . --yes

설치하면 무슨 일이 생기나

설치 대상 프로젝트에 아래 파일이 생성됩니다.

<project>/
  .claude/                    ← Claude Code 선택 시
    skills/<name>/SKILL.md       8개 스킬
    agents/<role>.md             15개 서브에이전트
    agent-teams/team-catalog.json
    commands/<name>.md           20개 네이티브 슬래시 명령
    instructions/CLAUDE.template.md
    settings/settings.json
  .gemini/                    ← Gemini CLI 선택 시
    skills/<name>/SKILL.md       8개 스킬
    agents/agent-catalog.json
    artifacts/artifact-catalog.json
    workflows/                   5개 워크플로우 정의
    commands/definitions/*.toml  20개 커스텀 명령
    gemini-extension.json        Extension 매니페스트
    instructions/GEMINI.template.md
    settings/editor-policy.json
  .codex/                     ← Codex 선택 시
    skills/<name>/SKILL.md       8개 스킬
    skills/cmd-*/SKILL.md        20개 명령 스킬
    automations/automation-recipes.toml
    commands/command-catalog.json
    instructions/AGENTS.template.md
    settings/runtime-policy.json
  CLAUDE.md                   ← 프로젝트 규칙 파일 (Claude Code)
  GEMINI.md                   ← 프로젝트 규칙 파일 (Gemini CLI)
  AGENTS.md                   ← 프로젝트 규칙 파일 (Codex)
  .tri-agent-manager/
    state.json                   설치 상태 기록
    USAGE.ko.md                  실행 가이드

동작 방법

1. 스킬 (Skills) — 3개 플랫폼 공통

8개 운영 스킬이 각 에이전트의 네이티브 포맷으로 설치됩니다.

| 스킬 ID | 역할 | |---------|------| | change-safety-review | 변경사항 회귀 검증 + 코드 리뷰 | | code-review-and-improvement | 코드 품질 개선 + 기술부채 정리 | | frontend-repetition-pack | UI 컴포넌트화 → Hook 분리 → 성능 최적화 | | incident-response | 장애 트리아지 → 근본원인 수정 → 포스트모템 | | prd-to-production-pipeline | PRD 작성 → 자동 구현 → 검증 → 배포 | | release-and-operations | CI/CD 게이트 → 배포 → 모니터링 | | security-hardening | 위협 모델링 → 취약점 감사 → 하드닝 | | service-lifecycle-orchestration | 전체 수명주기 오케스트레이션 |

각 스킬은 자체적으로 실행 가능한 상세 절차를 포함합니다. 외부 명령(CMD-*) 참조 없이 절차를 직접 기술합니다.

사용 방법:

• Claude Code: .claude/skills/<name>/SKILL.md를 자동 인식하여 사용자 요청에 매칭
• Gemini CLI: .gemini/skills/<name>/SKILL.md를 Extension 내 스킬로 로드
• Codex: .codex/skills/<name>/SKILL.md + agents/openai.yaml로 스킬 UI 표시

2. 명령 (Commands) — 플랫폼별 네이티브 변환

20개 공통 명령이 각 플랫폼의 네이티브 실행 포맷으로 변환됩니다.

| 플랫폼 | 변환 결과 | 실행 방식 | |--------|----------|----------| | Claude Code | commands/native/*.md | /cmd-dev-be-api 슬래시 명령으로 실행 | | Gemini CLI | commands/definitions/*.toml | Extension 커스텀 명령으로 실행 | | Codex | skills/cmd-*/SKILL.md | 스킬로 변환하여 네이티브 실행 |

3. 워크플로우 (Workflows) — Gemini CLI 전용

단계형 에이전트 체인 워크플로우는 Gemini CLI만 네이티브 지원합니다.

| 워크플로우 ID | 용도 | |--------------|------| | WF-SERVICE-E2E | 신규 서비스 E2E (Plan→Implement→Test→Review→Release) | | WF-FRONTEND-REFACTOR | 프론트엔드 반복 개선 (UI→Hook→성능) | | WF-SECURITY-HARDENING | 보안 강화 배치 (진단→보완→검증) | | WF-INCIDENT-RESPONSE | 장애 대응 (트리아지→근본수정→포스트모템) | | WF-PRD-TO-PRODUCTION | PRD 대화형 작성 → 순차 자동 구현 |

각 워크플로우는 workflow-catalog.json에 단계/에이전트/아티팩트 계약이 정의되어 있고, definitions/*.workflow.yaml로 실행합니다.

4. 서브에이전트 & 팀 — Claude Code 전용

Claude Code는 리드-전문가 구조의 서브에이전트 팀을 지원합니다.

• 15개 서브에이전트: lead-orchestrator, backend-engineer, security-engineer, sre-release-engineer 등
• 3개 팀: TEAM-SVC-DELIVERY (서비스 딜리버리), TEAM-SEC-HARDENING (보안), TEAM-INCIDENT (장애 대응)

5. 프로젝트 규칙 파일

설치 시 프로젝트 루트에 에이전트별 규칙 파일을 자동 생성합니다 (기존 파일 유지).

| 에이전트 | 규칙 파일 | 템플릿 원본 | |---------|----------|------------| | Claude Code | CLAUDE.md | instructions/CLAUDE.template.md | | Gemini CLI | GEMINI.md | instructions/GEMINI.template.md | | Codex | AGENTS.md | instructions/AGENTS.template.md |

프리셋

자주 쓰는 도구/구성요소 조합을 프리셋으로 제공합니다.

| 프리셋 ID | 포함 도구 | 설명 | |----------|----------|------| | balanced-core | Codex + Claude Code | 빠르게 시작하는 기본 구성 (추천) | | full-suite | Claude Code + Gemini CLI + Codex | 모든 구성요소 설치 | | security-first | Claude Code + Gemini CLI + Codex | 보안 점검/하드닝 중심 | | frontend-refactor | Claude Code + Codex | UI 컴포넌트화/성능 최적화 | | prd-to-production | Claude Code + Gemini CLI + Codex | PRD→구현 자동 파이프라인 |

CLI 옵션

tri-agent-manager [command] [options]

Commands:
  install          설치 (기본값)
  update           업데이트
  list             설치 가능 도구/구성요소 목록

Options:
  --interactive    대화형 모드 (TUI 메뉴)
  --preset <id>    프리셋으로 도구/구성요소 사전 선택
  --tool <ids>     도구 지정 (쉼표 구분: claude-code,gemini,codex)
  --components <ids>  구성요소 지정 (쉼표 구분: skills,commands,...)
  --target <path>  설치 대상 경로 (기본: 현재 디렉토리)
  --project-rules <policy>  규칙 파일 정책 (always|if-instructions|if-present|never)
  --force          install 시 기존 파일 덮어쓰기
  --dry-run        실제 파일 쓰기 없이 계획만 출력
  --yes            확인 프롬프트 건너뛰기
  --help           도움말

install vs update

| 명령 | 기존 파일 처리 | 용도 | |------|-------------|------| | install | 기존 파일 유지 (건너뜀) | 최초 설치, 추가 도구 설치 | | install --force | 기존 파일 덮어씀 | 템플릿 강제 재적용 | | update | 선택한 항목 업데이트 반영 | 버전 갱신, 유지보수 |

도구별 구성요소

| 구성요소 ID | 설치 경로 | 설명 | |------------|----------|------| | skills | .claude/skills | 8개 운영 스킬 | | subagents | .claude/agents | 15개 역할별 서브에이전트 프롬프트 | | agent-teams | .claude/agent-teams | 리드+전문가 팀 구성 | | commands | .claude/commands | 20개 네이티브 슬래시 명령 | | instructions | .claude/instructions | CLAUDE.md 템플릿 | | settings | .claude/settings | 권한/보안 설정 템플릿 |

규칙 파일: <target>/CLAUDE.md

| 구성요소 ID | 설치 경로 | 설명 | |------------|----------|------| | skills | .gemini/skills | 8개 운영 스킬 | | agents | .gemini/agents | 에이전트 역할 카탈로그 | | artifacts | .gemini/artifacts | 단계 입출력 아티팩트 계약 | | workflows | .gemini/workflows | 5개 워크플로우 + YAML 정의 | | commands | .gemini/commands | 20개 TOML 커스텀 명령 | | instructions | .gemini/instructions | GEMINI.md 템플릿 | | settings | .gemini/settings | 에디터 보안/권한 정책 |

규칙 파일: <target>/GEMINI.md

| 구성요소 ID | 설치 경로 | 설명 | |------------|----------|------| | skills | .codex/skills | 8개 운영 스킬 + 20개 명령 스킬 | | instructions | .codex/instructions | AGENTS.md 템플릿 + 권한 스니펫 | | automations | .codex/automations | 반복 작업 자동화 레시피 | | commands | .codex/commands | 공통 명령 계약 | | settings | .codex/settings | 런타임 권한 정책 |

규칙 파일: <target>/AGENTS.md

개발자용

파이프라인

common/* 수정 → npm run generate → npm run validate → npm publish

• npm run generate — 공통 정의를 플랫폼별 파일로 생성
• npm run generate:check — 생성 결과가 최신인지 검증
• npm run validate — 구조/계약/CLI 동작 검증
• npm run prepublish:check — 배포 전 전체 검증

규칙

• 공통 원천은 common/*에서만 수정합니다.
• claude-code/*, codex/*, gemini/*는 생성 결과로 취급합니다. 직접 수정하지 마세요.
• 명령은 공통 계약에서 플랫폼별 네이티브 포맷으로 자동 변환됩니다:
  • Claude Code: commands/native/*.md (Slash Command)
  • Gemini CLI: commands/definitions/*.toml (Extension 커스텀 명령)
  • Codex: skills/cmd-*/SKILL.md (스킬 변환)
• 보안 정책(common/settings/security-policy.json)에서 플랫폼별 설정 템플릿으로 변환됩니다.

검증 대상

• 생성 결과 최신성
• 스킬 frontmatter/절차 유효성 (CMD-/WF-/ART-* 참조 금지)
• 명령/워크플로우 참조 무결성
• 카탈로그/프리셋 무결성
• Gemini Extension 구조 (gemini-extension.json, .toml 커스텀 명령)
• CLI 스모크 테스트 (list/install/update + preset)

라이선스

MIT