# Agent Team Design Patterns (Antigravity CLI)

## 실행 모드: 서브에이전트

Antigravity CLI는 `invoke_subagent` 도구를 통해 멀티-에이전트 워크플로우를 구현한다. 메인 에이전트가 오케스트레이터 역할을 하며, 각 서브에이전트는 독립적인 컨텍스트와 도구 세트로 작업을 수행한다.

### 서브에이전트 (Subagents) — 기본 모드

메인 에이전트가 `invoke_subagent` 도구를 호출하여 서브에이전트를 호출(TypeName 지정)한다. 각 서브에이전트는 별개의 격리된 컨텍스트 윈도우에서 실행되며, 작업 완료 후 최종 상태 및 메시지를 오케스트레이터에게 반환한다.

```
[메인/오케스트레이터]
    ├── invoke_subagent(TypeName: "agent-a") → 작업 수행 → 결과 반환
    ├── invoke_subagent(TypeName: "agent-b") → 작업 수행 → 결과 반환
    └── invoke_subagent(TypeName: "agent-c") → 작업 수행 → 결과 반환
```

**핵심 특징:**

- 서브에이전트는 `.agents/plugins/{plugin-name}/agents/{name}/agent.json` 파일로 정의한다.
- `invoke_subagent` 도구 호출을 사용하여 명시적 위임 호출을 수행한다.
- 각 서브에이전트는 독립적인 컨텍스트, 도구, MCP 서버를 보유한다.
- `send_message` 도구를 통해 실행 중인 서브에이전트와 오케스트레이터 간 추가 정보나 피드백을 전달할 수 있다.
- 결과가 메인 컨텍스트로 요약 및 완료 보고 형태로 반환된다.

**제약:**

- 서브에이전트 간 직접 통신은 불가능하다 (메인을 통해서만 조율).
- 메인이 모든 워크플로우 통제를 담당한다.
- 동일 파일에 대한 동시 쓰기 충돌을 방지해야 한다 (병렬 실행 시).

### 병렬 서브에이전트

독립적인 여러 작업을 동시에 처리하고자 할 때 유용하다. `invoke_subagent` 도구를 여러 번 순차적으로 실행하여 백그라운드 태스크로 구동하고, 모든 서브에이전트의 작업 결과가 수집될 때까지 대기 및 취합한다.

```
[메인]
    ├── invoke_subagent(TypeName: "agent-a") (병렬 백그라운드)
    ├── invoke_subagent(TypeName: "agent-b") (병렬 백그라운드)
    └── invoke_subagent(TypeName: "agent-c") (병렬 백그라운드)
          └── 모든 에이전트 완료 후 결과 통합
```

**적합한 경우:** 작업 간의 독립성이 완벽히 보장되고, 최종 결과만 병합(Merge)하면 되는 경우.
**주의:** 동일 파일에 대한 동시 쓰기 충돌을 방지하기 위해, 각 서브에이전트가 출력할 개별 경로(`_workspace/` 하위 등)를 고유하게 분리해야 한다.

### 직접 실행

단순한 작업은 별도의 서브에이전트 플러그인 생성 없이, 메인 에이전트가 직접 툴(view_file, write_to_file 등)을 사용하여 작업을 즉시 처리한다.

```
[메인]
    └── 직접 실행 (Read/Write/Shell 등)
```

**적합한 경우:** 단순 탐색, 소규모 텍스트 편집 등 에이전트 분리 및 전환에 따르는 오버헤드가 더 클 때.

### 모드 선택 의사결정 트리

```
전문 영역이 2개 이상인가?
├── Yes → 작업이 독립적으로 실행 가능한가?
│         ├── Yes → 병렬 서브에이전트
│         │         각 영역별로 독립 실행, 결과만 통합.
│         │
│         └── No → 순차 서브에이전트 (파이프라인)
│                  이전 에이전트의 산출물이 다음 입력으로 필요.
│
└── No (1개) → 직접 실행
              단일 작업은 서브에이전트 분리 불필요.
```

> **핵심 원칙:** `invoke_subagent`가 기본이다. 직접 실행을 선택할 때는 "이 작업이 정말 독립된 에이전트 페르소나나 격리된 컨텍스트를 필요로 하지 않는가?"를 자문한다.

---

## 팀 아키텍처 유형

### 1. 파이프라인 (Pipeline)

순차적 작업 흐름. 이전 서브에이전트의 출력이 다음 서브에이전트의 입력으로 전달된다.

```
[analyst] ─(Output 파일)─→ [designer] ─(Output 파일)─→ [builder] ─→ [verifier]
```

**적합한 경우:** 각 단계가 이전 단계의 산출물에 강력하게 의존하는 경우.
**예시:** 문서/콘텐츠 제작 — 자료 조사 및 분석 → 구성안 디자인 → 원고 집필 → 완성도 검증.
**주의:** 앞선 에이전트의 병목이나 실패가 파이프라인 전체를 지연시키므로 에러 발생 시 재시도 메커니즘을 명확히 해야 한다.
**구현:** 파일 기반 데이터 전달 — 각 서브에이전트가 `_workspace/`에 결과 파일을 저장하고, 다음 서브에이전트 호출 프롬프트에 해당 파일의 절대 경로를 읽도록 지시한다.

### 2. 팬아웃/팬인 (Fan-out/Fan-in)

독립적인 작업을 동시에 수행한 뒤 결과를 통합한다.

```
                    ┌→ [expert-a] ─┐
[메인/오케스트레이터] ─┼→ [expert-b] ─┼→ [결과 통합]
                    └→ [expert-c] ─┘
```

**적합한 경우:** 동일 입력에 대해 상이한 전문가 관점의 동시 분석이나 대량 분할 자료 처리가 필요할 때.
**예시:** 종합 리서치 — 보안성 검토, 성능 모델링, 법적 규제 준수 여부를 각각의 에이전트가 병렬로 진행한 후 단일 보고서로 취합.
**주의:** 각 서브에이전트의 출력 경로를 중복되지 않게 고유한 파일명(`02_expert_a_result.md` 등)으로 매핑하여 동시 쓰기 충돌을 방지한다.

### 3. 전문가 풀 (Expert Pool)

상황이나 조건에 따라 적절한 에이전트를 선택하여 호출한다.

```
[메인/라우터] ──(분류/조건 판단)──→ { analyst-agent | builder-agent | qa-agent }
```

**적합한 경우:** 입력 요청의 성격이나 기술 분야에 따라 서로 다른 지시 및 도구 세트가 필요한 경우.
**예시:** 코드 검토 — 변경된 파일의 확장자나 코드 속성에 따라 보안 전문가, 성능 최적화 전문가, 데이터베이스 전문가 중 필요한 전문가만 선별적으로 호출.

### 4. 생성-검증 (Producer-Reviewer)

생성 담당 서브에이전트와 검증 담당 서브에이전트가 쌍(Pair)으로 협업한다.

```
[producer-agent] ──(생성안)──→ [reviewer-agent] ──(피드백/검증)
        ▲                             │
        └─────── (오류 발견 시 재실행) ─────┘
```

**적합한 경우:** 산출물의 정확성이나 코드 품질이 대단히 엄격하게 요구되고, 기계적 혹은 정성적 검증 기준이 명확한 경우.
**주의:** 무한 루프에 빠지는 것을 방지하기 위해 최대 재시도 및 루프 횟수(최대 2~3회)를 반드시 오케스트레이터 수준에서 제한해야 한다.

### 5. 감독자 (Supervisor)

메인 에이전트가 작업의 총괄 상태와 분배 목록을 관리하며 서브에이전트들에게 유동적으로 작업을 위임한다.

```
                 ┌→ [worker-a]
[supervisor-agent] ┼→ [worker-b]  (작업 진행 속도 및 상태에 따라 유동 분배)
                 └→ [worker-c]
```

**적합한 경우:** 대상 파일이나 작업의 목록이 런타임에 동적으로 변경되거나 처리해야 하는 전체 양이 방대하여 점진적인 분할 처리가 유리할 때.

### 6. 계층적 위임 (Hierarchical Delegation)

상위 서브에이전트가 하위 서브에이전트에 다시 `invoke_subagent` 도구 호출로 재귀적 위임을 수행하여 복잡한 전체 문제를 위계적으로 처리한다.

```
[main] → [team-lead-agent] ──→ [worker-agent-1]
                           └──→ [worker-agent-2]
```

**주의:** 위임의 깊이가 3단계 이상을 넘어가게 되면 중간 컨텍스트가 생략되어 지연 및 컨텍스트 손실이 비약적으로 증가한다. 최대 2단계 이내의 위임을 강력히 권장한다.

---

## 서브에이전트 정의 형식 (Antigravity CLI)

Antigravity CLI에서 서브에이전트는 `.agents/plugins/{plugin-name}/agents/{agent-name}/agent.json` 파일에 JSON 포맷으로 정의된다.

> [!NOTE]
> **다국어 및 영문 작성 규칙**
> 사용자가 영어로 하네스를 구성하도록 요청했거나 프로젝트의 기본 언어가 영어인 경우, `description` 및 `systemPromptSections` 내의 모든 지침 텍스트(핵심 역할, 작업 원칙, 입출력 프로토콜 등)는 자연스러운 **영문(Technical English)**으로 번역 및 작성되어야 합니다. 한국어 주석이나 텍스트를 남기지 않습니다.

### `agent.json` 정의 구조 예시

```json
{
  "name": "agent-name",
  "description": "서브에이전트의 역할 요약 및 사용 용도 설명.",
  "hidden": false,
  "config": {
    "customAgent": {
      "systemPromptSections": [
        {
          "title": "Agent System Instructions",
          "content": "당신은 [도메인]의 전문 서브에이전트 '[TypeName]'입니다.\n\n## 핵심 역할\n1. [핵심 역할 1]\n2. [핵심 역할 2]\n\n## 작업 원칙\n- [작업 원칙 1]\n- [작업 원칙 2]\n\n## 입력/출력 프로토콜\n- 입력: [오케스트레이터로부터 인계받는 파일 경로 및 컨텍스트]\n- 출력: [작업 완료 후 산출물을 작성할 경로 및 구조]\n\n## 에러 핸들링\n- 도구 실패나 누락 발견 시 1회 자체 복구를 시도하고, 해결 불가능할 경우 원인 메시지를 출력하며 실행을 중단하세요.\n\n## 협업 프로토콜\n- 이전 단계의 결과 파일이 `_workspace/` 하위에 있을 경우 이를 로드하여 활용하고, 지시 피드백이 추가 제공되면 해당 사항을 최우선으로 반영하여 결과 파일을 업데이트하세요."
        }
      ],
      "toolNames": [
        "send_message",
        "find_by_name",
        "grep_search",
        "view_file",
        "list_dir",
        "read_url_content",
        "search_web",
        "schedule",
        "multi_replace_file_content",
        "replace_file_content",
        "write_to_file",
        "run_command",
        "manage_task",
        "define_subagent",
        "invoke_subagent",
        "manage_subagents",
        "call_mcp_tool"
      ],
      "systemPromptConfig": {
        "includeSections": [
          "user_information",
          "mcp_servers",
          "skills",
          "subagent_reminder",
          "messaging",
          "artifacts",
          "user_rules"
        ]
      }
    }
  }
}
```

---

## 에이전트 분리 기준

| 기준         | 분리                                                                                   | 통합                                                                      |
| ------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **전문성**   | 작업 영역의 도메인(예: 기획 vs 빌드 vs QA)이 완전히 상이할 때 분리                     | 작업 지식과 프롬프트가 유사하거나 밀접한 연관이 있을 때 통합              |
| **병렬성**   | 다수의 독립 파일을 각기 병렬로 가공해야 할 때 분리                                     | 앞 작업이 끝나야만 뒤 작업을 진행할 수 있는 밀접한 순차 종속 시 통합 고려 |
| **컨텍스트** | 특정 분석을 위해 로딩해야 할 파일 용량이 거대하여 컨텍스트 절약이 요구될 때 분리       | 에이전트 간 컨텍스트가 실시간으로 고도로 결합하여 공유되어야 할 때 통합   |
| **재사용성** | 다양한 시나리오나 다른 플러그인 워크플로우에서도 독립적으로 호출될 여지가 있을 때 분리 | 특정 오케스트레이터의 특수 보조 역할에만 극한될 때 통합                   |

---

## 스킬(Skill) vs 서브에이전트(Agent) 구분

| 구분       | 스킬 (Skill)                                                  | 서브에이전트 (Agent)                                               |
| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------ |
| **정의**   | 절차적인 지식 및 특정 행동 워크플로우 가이드라인              | 행동 원칙, 성격 및 특정 도구 실행 역량을 지닌 전문가 개체          |
| **위치**   | `.agents/plugins/{plugin-name}/skills/{skill-name}/SKILL.md`  | `.agents/plugins/{plugin-name}/agents/{agent-name}/agent.json`     |
| **트리거** | description 분석 기반의 자동 매칭 및 명시적 스킬 활성화       | `invoke_subagent` 도구를 통한 명시적 위임 실행                     |
| **용도**   | **"어떻게(How)"** 작업을 효율적으로 진행할 것인가에 대한 규약 | **"누가(Who)"** 해당 전문 작업을 독립된 컨텍스트에서 수행할 것인가 |
