159 lines
7.7 KiB
Markdown
159 lines
7.7 KiB
Markdown
# Antigravity CLI 하네스
|
|
|
|
|
|
|
|
<p align="center">
|
|
<a href="LISENCE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
|
|
<img src="https://img.shields.io/badge/Antigravity_CLI-Plugin-purple" alt="Antigravity CLI Plugin">
|
|
<a href="#아키텍처-패턴"><img src="https://img.shields.io/badge/Patterns-6_Architectures-orange" alt="6 Architectural Patterns"></a>
|
|
<img src="https://img.shields.io/badge/Mode-Agent_Teams-green" alt="Agent Teams">
|
|
<a href="https://github.com/Kyeong1024/antigravity-cli-harness/stargazers"><img src="https://img.shields.io/github/stars/Kyeong1024/antigravity-cli-harness?style=flat&logo=github" alt="GitHub Stars"></a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="https://img.shields.io/badge/Layer-Meta--Skill-orange" alt="Meta-Skill Layer">
|
|
<img src="https://img.shields.io/badge/Sub--layer-Team_Architecture_Factory-teal" alt="Team Architecture Factory">
|
|
<a href="README.md"><img src="https://img.shields.io/badge/README-EN_|_KO-lightgrey" alt="README languages"></a>
|
|
</p>
|
|
|
|
한 줄의 도메인 설명을 **Antigravity CLI**를 위한 실무적 다중 에이전트 팀으로 변환하는 메타 스킬입니다.
|
|
|
|
## 빠른 시작
|
|
|
|
**1. 하네스 플러그인 설치**
|
|
|
|
사용 범위에 맞는 방식을 선택하세요:
|
|
|
|
- **전역 설치** — 모든 Antigravity CLI 세션에서 사용 가능:
|
|
```bash
|
|
git clone https://github.com/Kyeong1024/antigravity-cli-harness
|
|
agy plugin install antigravity-cli-harness
|
|
```
|
|
- **워크스페이스 설치** — 특정 프로젝트에만 적용. 프로젝트 루트의 `.agents/plugins/harness-plugin`에 플러그인을 클론:
|
|
```bash
|
|
git clone https://github.com/Kyeong1024/antigravity-cli-harness .agents/plugins/harness-plugin
|
|
```
|
|
|
|
워크스페이스 정의가 전역 설정보다 우선하므로, 전역 설치를 건드리지 않고 프로젝트별 하네스를 반복 개선할 수 있습니다.
|
|
|
|
**2. Antigravity CLI 실행 후 하네스 요청**
|
|
|
|
```bash
|
|
agy
|
|
> {도메인}에 대한 하네스를 만들어줘.
|
|
```
|
|
|
|
`harness` 스킬이 자동으로 트리거되어 서브에이전트, 스킬, 오케스트레이터, 그리고 `AGENTS.md` 트리거 항목까지 팀 스캐폴딩 전 과정을 안내합니다.
|
|
|
|
## 기능
|
|
|
|
하네스에 *"X에 대한 하네스를 만들어줘"*라고 말하면 한 번에 다음을 스캐폴딩합니다:
|
|
|
|
- `.agents/plugins/{domain}-plugin/` 아래의 **플러그인**
|
|
- 각각 정의된 역할, 도구 세트 및 시스템 프롬프트를 가진 **서브에이전트** (`agents/{name}/agent.json`)
|
|
- 그 에이전트들이 사용하는 **스킬** (`skills/{name}/SKILL.md`)
|
|
- 명시적인 데이터 전달 및 오류 처리 규칙으로 팀을 조율하는 **오케스트레이터 스킬**
|
|
- 향후 세션에서 하네스를 자동으로 트리거할 수 있도록 **`AGENTS.md`**의 포인터 항목
|
|
|
|
그 결과는 일회성 스크립트가 아닌 재사용 가능하고 진화 가능한 팀 아키텍처입니다.
|
|
|
|
## 왜 하네스를 사용하나?
|
|
|
|
단일 에이전트 프롬프트는 작업이 여러 전문 분야를 넘으면 한계에 도달합니다 (예: 분석 → 빌드 → QA). 하네스는 다음과 같이 이를 해결합니다:
|
|
|
|
1. **전문성 분할** — 각 서브에이전트가 자체 컨텍스트 윈도우를 가지고 초점을 맞춘 역할을 함.
|
|
2. **협업 표준화** — 파일 기반 워크스페이스 (`_workspace/`)와 오케스트레이터를 통해 표준화된 협업.
|
|
3. **세션 간 생존** — 정의가 디스크에 살아있어 팀이 재현 가능하고 시간 경과에 따라 개선 가능.
|
|
|
|
## 생성된 구조
|
|
|
|
```
|
|
.agents/
|
|
└── plugins/
|
|
└── {domain}-plugin/
|
|
├── plugin.json
|
|
├── agents/
|
|
│ └── {agent-name}/
|
|
│ └── agent.json # 서브에이전트 정의
|
|
└── skills/
|
|
├── {orchestrator}/
|
|
│ └── SKILL.md # 팀을 조율하는 워크플로우
|
|
└── {skill-name}/
|
|
├── SKILL.md # 단일 기능 작동 방식
|
|
└── rules/ # 점진적으로 로드되는 참조
|
|
AGENTS.md # 트리거 포인터 + 변경 로그
|
|
```
|
|
|
|
## 아키텍처 패턴
|
|
|
|
하네스는 도메인에 따라 6가지 팀 패턴 중 하나를 선택합니다:
|
|
|
|
| 패턴 | 사용 시기 |
|
|
|---|---|
|
|
| **파이프라인** | 순차적, 종속적 단계 |
|
|
| **팬아웃 / 팬인** | 병렬로 수행되는 독립적인 작업 |
|
|
| **전문가 풀** | 전문가로의 조건부 라우팅 |
|
|
| **생산자–검토자** | 생성 후 루프에서 QA |
|
|
| **감독자** | 중앙 에이전트가 상태 및 디스패치 관리 |
|
|
| **계층적 위임** | 재귀적 서브 위임 |
|
|
|
|
## 실행 모드
|
|
|
|
| 모드 | 시기 |
|
|
|---|---|
|
|
| **서브에이전트** *(기본)* | ≥2 전문 분야가 협업; 각각 `invoke_subagent`를 통해 격리된 컨텍스트에서 실행 |
|
|
| **병렬 서브에이전트** | 동시에 실행할 독립적인 작업 |
|
|
| **직접 실행** | 에이전트 분리가 오버헤드인 단순한 일회성 작업 |
|
|
|
|
## 워크플로우
|
|
|
|
메타 스킬은 7개 단계를 거칩니다:
|
|
|
|
0. **감사** — 기존 플러그인 감지, 새 빌드 vs. 확장 vs. 유지보수 결정.
|
|
1. **도메인 분석** — 작업 유형, 코드베이스, 사용자 기술 수준 식별.
|
|
2. **팀 아키텍처** — 실행 모드 + 패턴 선택, 작업을 전문 분야로 분할.
|
|
3. **서브에이전트 정의** — 각 `agent.json`을 역할, 도구, I/O 프로토콜로 작성.
|
|
4. **스킬 생성** — 강압적이고 트리거 친화적인 설명과 `rules/`로의 점진적 공개로 `SKILL.md` 파일 작성.
|
|
5. **오케스트레이션** — 파일 기반 데이터 전달, 오류 처리, 후속 지원으로 팀 조율.
|
|
6. **검증** — 구조 검사, 트리거 검사 (should-trigger + near-miss), 드라이 런.
|
|
7. **진화** — 각 실행 후 피드백 수집; 에이전트/스킬 업데이트 및 `AGENTS.md`의 변경 로그.
|
|
|
|
## 설치
|
|
|
|
`.agents/plugins/harness-plugin/` 디렉토리를 모든 Antigravity CLI 프로젝트에 떨어뜨립니다. `harness` 스킬은 다음과 같은 요청에 자동으로 트리거됩니다:
|
|
|
|
- "build a harness for {domain}"
|
|
- "set up a harness", "design a harness"
|
|
- "audit / sync the harness", "harness status"
|
|
|
|
## 사용법
|
|
|
|
Antigravity CLI 세션에서:
|
|
|
|
```
|
|
> Build a harness for a content marketing pipeline.
|
|
```
|
|
|
|
스킬은 다음과 같이 작동합니다:
|
|
|
|
1. 기존의 `.agents/plugins/`와 `AGENTS.md`를 감사합니다.
|
|
2. 팀을 제안하고 (예: 연구자 → 작성자 → 편집자 → QA) 확인합니다.
|
|
3. 플러그인을 생성하고, `agent.json`/`SKILL.md` 파일을 작성하고, `AGENTS.md`에 트리거를 등록합니다.
|
|
4. 검증을 실행하고 보고서를 제출합니다.
|
|
|
|
후속 턴 (`"analyst 단계를 다시 해줘"`, `"security reviewer를 추가해줘"`, `"harness audit"`)은 확장 / 유지보수 모드의 동일한 스킬로 처리됩니다.
|
|
|
|
## 참고자료
|
|
|
|
스킬은 `.agents/plugins/harness-plugin/skills/harness/rules/` 아래에 내부 가이드와 함께 제공됩니다:
|
|
|
|
- `agent-design-patterns.md` — 패턴 카탈로그, 분리 기준
|
|
- `team-examples.md` — 전체 팀 정의 예제
|
|
- `orchestrator-template.md` — 오류 처리가 있는 오케스트레이터 스켈레톤
|
|
- `skill-writing-guide.md` — `SKILL.md` 작성 패턴
|
|
- `skill-testing-guide.md` — 트리거 및 실행 테스트 방법론
|
|
- `qa-agent-guide.md` — QA 서브에이전트 설계
|
|
|
|
## 감사의 말
|
|
|
|
[revfactory/harness](https://github.com/revfactory/harness)에서 포팅되었으며, Antigravity CLI의 플러그인 및 서브에이전트 모델에 맞게 재작업되었습니다.
|