diff --git a/.agents/plugins/harness-plugin/.gitignore b/.agents/plugins/harness-plugin/.gitignore new file mode 100644 index 0000000..496ee2c --- /dev/null +++ b/.agents/plugins/harness-plugin/.gitignore @@ -0,0 +1 @@ +.DS_Store \ No newline at end of file diff --git a/.agents/plugins/harness-plugin/LICENSE b/.agents/plugins/harness-plugin/LICENSE new file mode 100644 index 0000000..0fd5b43 --- /dev/null +++ b/.agents/plugins/harness-plugin/LICENSE @@ -0,0 +1,191 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to the Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by the Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding any notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +Copyright 2025 robin +Copyright 2026 Kyeong1024 + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/.agents/plugins/harness-plugin/README.ko.md b/.agents/plugins/harness-plugin/README.ko.md new file mode 100644 index 0000000..0a19a48 --- /dev/null +++ b/.agents/plugins/harness-plugin/README.ko.md @@ -0,0 +1,159 @@ +# Antigravity CLI 하네스 + +![Antigravity CLI](docs/images/antigravity-cli.png) + +

+ License + Antigravity CLI Plugin + 6 Architectural Patterns + Agent Teams + GitHub Stars +

+ +

+ Meta-Skill Layer + Team Architecture Factory + README languages +

+ +한 줄의 도메인 설명을 **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의 플러그인 및 서브에이전트 모델에 맞게 재작업되었습니다. diff --git a/.agents/plugins/harness-plugin/README.md b/.agents/plugins/harness-plugin/README.md new file mode 100644 index 0000000..b403760 --- /dev/null +++ b/.agents/plugins/harness-plugin/README.md @@ -0,0 +1,159 @@ +# Antigravity CLI Harness + +![Antigravity CLI](docs/images/antigravity-cli.png) + +

+ License + Antigravity CLI Plugin + 6 Architectural Patterns + Agent Teams + GitHub Stars +

+ +

+ Meta-Skill Layer + Team Architecture Factory + README languages +

+ +A meta-skill that turns a one-line domain description into a working multi-agent team for the **Antigravity CLI**. + +## Quick start + +**1. Install the harness plugin** + +Choose the scope that fits your workflow: + +- **Global install** — available in every Antigravity CLI session: + ```bash + git clone https://github.com/Kyeong1024/antigravity-cli-harness + agy plugin install antigravity-cli-harness + ``` +- **Workspace install** — scoped to a single project. Clone the plugin into `.agents/plugins/harness-plugin` in the project root: + ```bash + git clone https://github.com/Kyeong1024/antigravity-cli-harness .agents/plugins/harness-plugin + ``` + +Workspace definitions take precedence over global ones, so you can iterate on a project-specific harness without touching the global install. + +**2. Launch Antigravity CLI and request a harness** + +```bash +agy +> Build me a harness for {your-domain}. +``` + +The `harness` skill auto-triggers and walks you through scaffolding the team — subagents, skills, orchestrator, and the `AGENTS.md` trigger entry. + +## What it does + +Tell the harness *"build me a harness for X"* and it scaffolds, in one go: + +- A **plugin** under `.agents/plugins/{domain}-plugin/` +- A team of **subagents** (`agents/{name}/agent.json`), each with a defined role, tool set, and system prompt +- A set of **skills** (`skills/{name}/SKILL.md`) those agents use to do their work +- An **orchestrator skill** that wires the team into a workflow with explicit data-passing and error-handling rules +- A pointer entry in **`AGENTS.md`** so future sessions auto-trigger the harness + +The result is a reusable, evolvable team architecture — not a one-shot script. + +## Why a harness? + +Single-agent prompts hit a ceiling once a task crosses multiple specializations (e.g. analysis → build → QA). A harness solves this by: + +1. **Splitting expertise** into focused subagents, each with its own context window. +2. **Standardizing collaboration** through a file-based workspace (`_workspace/`) and an orchestrator. +3. **Surviving across sessions** — definitions live on disk, so the team is reproducible and improvable over time. + +## Generated structure + +``` +.agents/ +└── plugins/ + └── {domain}-plugin/ + ├── plugin.json + ├── agents/ + │ └── {agent-name}/ + │ └── agent.json # subagent definition + └── skills/ + ├── {orchestrator}/ + │ └── SKILL.md # workflow that wires the team + └── {skill-name}/ + ├── SKILL.md # how a single capability works + └── rules/ # progressively-loaded references +AGENTS.md # trigger pointer + change log +``` + +## Architectural patterns + +The harness picks one of six team patterns based on the domain: + +| Pattern | When to use | +|---|---| +| **Pipeline** | Sequential, dependent steps | +| **Fan-out / Fan-in** | Independent work done in parallel | +| **Expert Pool** | Conditional routing to specialists | +| **Producer–Reviewer** | Generate then QA in a loop | +| **Supervisor** | Central agent manages state and dispatch | +| **Hierarchical Delegation** | Recursive sub-delegation | + +## Execution modes + +| Mode | When | +|---|---| +| **Subagent** *(default)* | ≥2 specializations collaborating; each runs in an isolated context via `invoke_subagent` | +| **Parallel subagent** | Independent work to run concurrently | +| **Direct execution** | Simple, one-shot tasks where agent separation is overhead | + +## Workflow + +The meta-skill runs through seven phases: + +0. **Audit** — detect existing plugins, decide new build vs. extension vs. maintenance. +1. **Domain analysis** — identify task types, codebase, user skill level. +2. **Team architecture** — choose execution mode + pattern, split work into specializations. +3. **Subagent definitions** — write each `agent.json` with role, tools, and I/O protocol. +4. **Skill creation** — write `SKILL.md` files with pushy, trigger-friendly descriptions and progressive disclosure into `rules/`. +5. **Orchestration** — wire the team with file-based data passing, error handling, and follow-up support. +6. **Validation** — structure checks, trigger checks (should-trigger + near-miss), dry-run. +7. **Evolution** — collect feedback after each run; update agents/skills and log changes in `AGENTS.md`. + +## Installation + +Drop the `.agents/plugins/harness-plugin/` directory into any Antigravity CLI project. The `harness` skill auto-triggers on requests like: + +- "build a harness for {domain}" +- "set up a harness", "design a harness" +- "audit / sync the harness", "harness status" + +## Usage + +In an Antigravity CLI session: + +``` +> Build a harness for a content marketing pipeline. +``` + +The skill will: + +1. Audit any existing `.agents/plugins/` and `AGENTS.md`. +2. Propose a team (e.g. researcher → writer → editor → QA) and confirm with you. +3. Generate the plugin, write `agent.json`/`SKILL.md` files, and register the trigger in `AGENTS.md`. +4. Run validation and report. + +Follow-up turns (`"redo the analyst step"`, `"add a security reviewer"`, `"harness audit"`) are handled by the same skill in extension / maintenance mode. + +## References + +The skill ships with internal guides under `.agents/plugins/harness-plugin/skills/harness/rules/`: + +- `agent-design-patterns.md` — pattern catalog, separation criteria +- `team-examples.md` — full example team definitions +- `orchestrator-template.md` — orchestrator skeleton with error handling +- `skill-writing-guide.md` — `SKILL.md` authoring patterns +- `skill-testing-guide.md` — trigger and execution testing methodology +- `qa-agent-guide.md` — designing QA subagents + +## Acknowledgements + +Ported from [revfactory/harness](https://github.com/revfactory/harness), with rework for Antigravity CLI's plugin and subagent model. diff --git a/.agents/plugins/harness-plugin/docs/images/antigravity-cli.png b/.agents/plugins/harness-plugin/docs/images/antigravity-cli.png new file mode 100644 index 0000000..df2b892 Binary files /dev/null and b/.agents/plugins/harness-plugin/docs/images/antigravity-cli.png differ diff --git a/.agents/plugins/harness-plugin/plugin.json b/.agents/plugins/harness-plugin/plugin.json new file mode 100644 index 0000000..efbb925 --- /dev/null +++ b/.agents/plugins/harness-plugin/plugin.json @@ -0,0 +1,5 @@ +{ + "name": "harness-plugin", + "description": "Antigravity CLI용 팀 아키텍처 팩토리: 도메인 한 문장을 플러그인(Subagent, Skill 세트)으로 변환하는 메타 스킬.", + "version": "1.0.0" +} diff --git a/.agents/plugins/harness-plugin/skills/harness/SKILL.md b/.agents/plugins/harness-plugin/skills/harness/SKILL.md new file mode 100644 index 0000000..7fb8638 --- /dev/null +++ b/.agents/plugins/harness-plugin/skills/harness/SKILL.md @@ -0,0 +1,437 @@ +--- +name: harness +description: "하네스를 구성합니다. 전문 서브에이전트 정의(agent.json)와 스킬(SKILL.md)을 플러그인 형태로 생성하는 메타 스킬. (1) '하네스 구성해줘', '하네스 구축해줘' 요청 시, (2) '하네스 설계', '하네스 엔지니어링' 요청 시, (3) 새로운 도메인/프로젝트에 대한 하네스 기반 자동화 체계를 구축할 때, (4) 하네스 구성을 재구성하거나 확장할 때, (5) '하네스 점검', '하네스 감사', '하네스 현황', '에이전트/스킬 동기화' 등 기존 하네스 운영/유지보수 요청 시 사용." +--- + +# Harness — Agent Team & Skill Architect for Antigravity CLI + +도메인/프로젝트에 맞는 하네스를 구성하고, 각 서브에이전트의 역할을 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬. + +**핵심 원칙:** +1. **플러그인 구조로 패키징한다.** — 서브에이전트 정의(`.agents/plugins/{domain}-plugin/agents/{name}/agent.json`)와 스킬(`.agents/plugins/{domain}-plugin/skills/{name}/SKILL.md`)을 하나의 플러그인 폴더에 묶어 생성한다. +2. **`invoke_subagent` 도구를 기본 실행 모드로 사용한다.** — Antigravity CLI의 서브에이전트 위임 메커니즘(`invoke_subagent` 호출 및 `send_message`를 통한 협업)을 활용한다. +3. **AGENTS.md에 하네스 포인터를 등록한다.** — 새 세션에서 오케스트레이터 스킬이 트리거되도록 최소한의 포인터(트리거 규칙 + 변경 이력)만 기록한다. +4. **하네스는 고정물이 아니라 진화하는 시스템이다.** — 매 실행 후 피드백을 반영하고, 에이전트·스킬·AGENTS.md를 지속 갱신한다. +5. **사용자 요청 언어 및 컨텍스트에 맞게 작성 언어를 결정한다.** — 사용자가 영어로 요청을 하거나, 프로젝트의 글로벌 협업 환경, 코드베이스 주석/문서 표준이 영어인 경우, 새로 생성하는 서브에이전트(`agent.json`의 `description` 및 `systemPromptSections` 등), 스킬(`SKILL.md` 본문 및 YAML frontmatter `description` 등), 그리고 오케스트레이터의 모든 텍스트를 영문(English)으로 작성한다. + +## 워크플로우 + +### Phase 0: 현황 감사 + +하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다. + +1. `프로젝트/.agents/plugins/`, `프로젝트/AGENTS.md`를 읽는다. +2. 현황에 따라 실행 모드를 분기한다: + - **신규 구축**: 플러그인 디렉토리가 없거나 비어있음 → Phase 1부터 전체 실행 + - **기존 확장**: 기존 하네스가 있고 새 에이전트/스킬 추가 요청 → 아래 Phase 선택 매트릭스에 따라 필요한 Phase만 실행 + - **운영/유지보수**: 기존 하네스의 감사·수정·동기화 요청 → Phase 7-5 운영/유지보수 워크플로우로 이동 + + **기존 확장 시 Phase 선택 매트릭:** + | 변경 유형 | Phase 1 | Phase 2 | Phase 3 | Phase 4 | Phase 5 | Phase 6 | + |----------|---------|---------|---------|---------|---------|---------| + | 에이전트 추가 | 건너뜀 (Phase 0 결과 활용) | 배치 결정만 | 필수 | 전용 스킬 필요 시 | 오케스트레이터 수정 | 필수 | + | 스킬 추가/수정 | 건너뜀 | 건너뜀 | 건너뜀 | 필수 | 연결 변경 시 | 필수 | + | 아키텍처 변경 | 건너뜀 | 필수 | 영향받는 에이전트만 | 영향받는 스킬만 | 필수 | 필수 | +3. 기존 에이전트/스킬 목록과 AGENTS.md 기록을 대조하여 불일치(drift)를 감지한다. +4. 감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다. + +### Phase 1: 도메인 분석 +1. 사용자 요청에서 도메인/프로젝트 파악 +2. 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등) +3. Phase 0 감사 결과를 기반으로 기존 에이전트/스킬과의 충돌/중복 분석 +4. 프로젝트 코드베이스 탐색 — 기술 스택, 데이터 모델, 주요 모듈 파악 +5. **사용자 숙련도 감지** — 대화의 맥락 단서(사용 용어, 질문 수준)로 기술 수준을 파악하고, 이후 커뮤니케이션 톤을 조절한다. 코딩 경험이 적은 사용자에게는 "assertion", "JSON schema" 같은 용어를 설명 없이 쓰지 않는다. +6. **작성 언어 식별** — 사용자가 영어로 하네스 구성을 요청하는지, 혹은 codebase(README, 기존 스킬/코드)의 기본 언어가 영어인지 감지한다. 영어 기반 프로젝트이거나 사용자가 영어로 요청한 경우, 하네스 산출물(스킬, 에이전트 정의, 오케스트레이터)의 언어는 영어(English)로 결정한다. + +### Phase 2: 팀 아키텍처 설계 + +#### 2-1. 실행 모드 선택 + +**서브에이전트가 기본 실행 모드이다.** 2개 이상의 에이전트가 협업할 때는 Antigravity CLI 서브에이전트를 통해 위임한다. 메인 에이전트가 오케스트레이터 역할을 하며, 각 서브에이전트는 `invoke_subagent` 도구 호출로 생성된 독립적인 컨텍스트에서 작업을 수행하고 결과를 반환한다. + +| 모드 | 언제 사용 | 특성 | +|------|----------|------| +| **서브에이전트** (기본) | 2명 이상 협업, 각 에이전트가 독립 컨텍스트에서 작업 | `invoke_subagent` 위임, 파일 기반 결과 공유 | +| **직접 실행** (대안) | 단순 작업, 에이전트 분리가 오버헤드일 때 | 별도 에이전트 없이 메인이 직접 처리 | +| **병렬 서브에이전트** | 독립적인 작업을 동시에 처리 | `invoke_subagent`를 통해 여러 서브에이전트를 동시에 실행하여 결과 수집 | + +**의사결정 순서:** +1. 먼저 서브에이전트로 분리 가능한 작업 영역을 식별한다 — 2개 이상의 전문 영역이면 기본값 +2. 병렬 실행이 가능한 독립 작업이면 병렬 서브에이전트 고려 +3. 단순하고 일회성인 작업은 직접 실행 + +> 상세 비교표와 패턴별 의사결정 트리는 `rules/agent-design-patterns.md`의 "실행 모드" 참조. + +#### 2-2. 아키텍처 패턴 선택 + +1. 작업을 전문 영역으로 분해 +2. 서브에이전트 팀 구조 결정 (아키텍처 패턴은 `rules/agent-design-patterns.md` 참조) + - **파이프라인**: 순차 의존 작업 (서브에이전트 체인) + - **팬아웃/팬인**: 병렬 독립 작업 (병렬 서브에이전트) + - **전문가 풀**: 상황별 선택 호출 (조건부 서브에이전트) + - **생성-검증**: 생성 후 품질 검수 (서브에이전트 루프) + - **감독자**: 중앙 에이전트가 상태 관리 및 동적 분배 (메인 → 서브) + - **계층적 위임**: 상위 에이전트가 하위에 재귀적 위임 (서브에이전트 체인) + +#### 2-3. 에이전트 분리 기준 + +전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 `rules/agent-design-patterns.md`의 "에이전트 분리 기준" 참조. + +### Phase 3: 서브에이전트 정의 생성 + +**모든 서브에이전트는 반드시 `프로젝트/.agents/plugins/{domain}-plugin/agents/{name}/agent.json` 파일로 정의한다.** +서브에이전트 정의가 파일로 존재해야 다음 세션에서 재사용 가능하며, 역할과 작업 원칙이 명시되어야 협업 품질이 보장된다. + +각 서브에이전트의 `agent.json` 필수 구성 요소: +- `name`: 에이전트 이름 (TypeName으로 매핑됨) +- `description`: 사용자가 이 에이전트의 정체성을 한눈에 파악할 수 있는 요약 +- `config.customAgent.systemPromptSections`: 에이전트의 구체적 instructions를 섹션 단위로 명시 (핵심 역할, 작업 원칙, 입출력 프로토콜 포함) +- `config.customAgent.toolNames`: 에이전트가 활용할 권장 도구 세트 +- `config.customAgent.systemPromptConfig.includeSections`: Antigravity CLI가 제공할 시스템 프롬프트 섹션 목록 +- **언어 일관성**: Phase 1에서 결정된 작성 언어(한국어 또는 영어)에 맞게 `description`과 `systemPromptSections` 내부의 system prompt를 일관되게 작성한다. 영어 프로젝트 또는 영어 요청의 경우, 모든 프롬프트와 설명을 자연스러운 영문(Technical English)으로 작성해야 한다. + +> 정의 구조와 실제 파일 전문은 `rules/agent-design-patterns.md`의 "서브에이전트 정의 구조" + `rules/team-examples.md` 참조. + +**QA 에이전트 포함 시 필수 사항:** +- QA 에이전트는 전체 도구 접근이 필요하므로 읽기 전용 제한을 두지 않는다. +- QA의 핵심은 "존재 확인"이 아니라 **"경계면 교차 비교"** — API 응답과 프론트 훅을 동시에 읽고 shape을 비교. +- QA는 전체 완성 후 1회가 아니라, **각 모듈 완성 직후 점진적으로 실행** (incremental QA). +- 상세 가이드: `rules/qa-agent-guide.md` 참조. + +### Phase 4: 스킬 생성 + +각 서브에이전트가 사용할 스킬을 `프로젝트/.agents/plugins/{domain}-plugin/skills/{name}/SKILL.md`에 생성한다. 상세 작성 가이드는 `rules/skill-writing-guide.md` 참조. + +#### 4-1. 스킬 구조 + +``` +{domain}-plugin/ +└── skills/ + └── {skill-name}/ + ├── SKILL.md (필수) + │ ├── YAML frontmatter (name, description 필수) + │ └── Markdown 본문 + └── Bundled Resources (선택) + ├── scripts/ - 반복/결정적 작업용 실행 코드 + ├── rules/ - 조건부 로딩하는 참조 문서 + └── assets/ - 출력에 사용되는 파일 (템플릿, 이미지 등) +``` + +#### 4-2. Description 작성 — 적극적 트리거 유도 + +description은 스킬의 유일한 트리거 메커니즘이다. Antigravity CLI는 `available_skills` 목록에서 name + description만 보고 스킬 사용 여부를 결정하므로, description을 **적극적("pushy")**으로 작성한다. + +**나쁜 예:** `"PDF 문서를 처리하는 스킬"` +**좋은 예:** `"PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크, 암호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나 PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것."` + +핵심: 스킬이 하는 일 + 구체적 트리거 상황을 모두 기술하고, 유사하지만 트리거하면 안 되는 경우와 구분되도록 작성. + +#### 4-3. 본문 작성 원칙 + +| 원칙 | 설명 | +|------|------| +| **Why를 설명하라** | "ALWAYS/NEVER" 같은 강압적 지시 대신, 왜 그렇게 해야 하는지 이유를 전달한다. LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. | +| **Lean하게 유지** | 컨텍스트 윈도우는 공공재다. SKILL.md 본문은 500줄 이내를 목표로, 무게를 벌지 않는 내용은 삭제하거나 rules/로 이동한다. | +| **일반화하라** | 특정 예시에만 맞는 좁은 규칙보다, 원리를 설명하여 다양한 입력에 대응할 수 있게 한다. 오버피팅 금지. | +| **반복 코드는 번들링** | 테스트 실행에서 에이전트들이 공통으로 작성하는 스크립트가 발견되면 `scripts/`에 미리 번들링한다. | +| **명령형으로 작성** | "~한다", "~하라" 형태의 명령형/지시형 어조를 사용한다. | +| **언어 일관성** | 감지된 언어(한국어/영어)를 일관되게 사용한다. 영문 요청/글로벌 프로젝트의 경우, YAML frontmatter description과 스킬 본문 전체를 완벽한 영어로 작성하며, 설명이 번역기 톤이 아닌 자연스러운 기술 문서 톤이 되도록 한다. | + +#### 4-4. Progressive Disclosure (단계적 정보 공개) + +스킬은 3단계 로딩 시스템으로 컨텍스트를 관리한다: + +| 단계 | 로딩 시점 | 크기 목표 | +|------|----------|----------| +| **Metadata** (name + description) | 항상 컨텍스트에 존재 | ~100단어 | +| **SKILL.md 본문** | 스킬 트리거 시 | <500줄 | +| **rules/** | 필요할 때만 | 무제한 (스크립트는 로딩 없이 실행 가능) | + +**크기 관리 규칙:** +- SKILL.md가 500줄에 근접하면 세부 내용을 rules/로 분리하고, 본문에 "언제 이 파일을 읽으라"는 포인터를 남긴다. +- 300줄 이상의 rules 파일에는 상단에 **목차(ToC)**를 포함한다. +- 도메인/프레임워크별 변형이 있으면 rules/ 하위에 도메인별로 분리하여, 관련 파일만 로드한다. + +``` +cloud-deploy-plugin/ +└── skills/ + └── cloud-deploy/ + ├── SKILL.md (워크플로우 + 선택 가이드) + └── rules/ + ├── aws.md ← AWS 선택 시만 로드 + ├── gcp.md + └── azure.md +``` + +#### 4-5. 스킬-에이전트 연결 원칙 + +- 서브에이전트 1개 ↔ 스킬 1~N개 (1:1 또는 1:다) +- 여러 서브에이전트가 공유하는 스킬도 가능 +- 스킬은 "어떻게 하는가"를 담고, 에이전트는 "누가 하는가"를 담는다. + +> 상세 작성 패턴, 예시, 데이터 스키마 표준은 `rules/skill-writing-guide.md` 참조. + +### Phase 5: 통합 및 오케스트레이션 + +오케스트레이터는 스킬의 특수한 형태로, 개별 서브에이전트와 스킬을 하나의 워크플로우로 엮어 팀 전체를 조율한다. Phase 4에서 생성한 개별 스킬이 "각 에이전트가 무엇을 어떻게 하는가"를 정의한다면, 오케스트레이터는 "누가 언제 어떤 순서로 협업하는가"를 정의한다. 구체적 템플릿은 `rules/orchestrator-template.md` 참조. + +**기존 확장 시 오케스트레이터 수정:** 신규 구축이 아닌 기존 확장일 때는 오케스트레이터를 새로 생성하지 않고 기존 오케스트레이터를 수정한다. 서브에이전트 추가 시 팀 구성·작업 할당·데이터 흐름에 새 에이전트를 반영하고, description에 새 에이전트 관련 트리거 키워드를 추가한다. + +Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴이 달라진다: + +#### 5-0. 오케스트레이터 패턴 (모드별) + +**서브에이전트 패턴 (기본):** +메인 에이전트(오케스트레이터)가 서브에이전트를 `invoke_subagent` 도구 호출로 실행한다. 각 서브에이전트는 독립적인 컨텍스트에서 작업을 수행하고, 결과를 메인에게 반환한다. 파일 기반으로 중간 산출물을 공유한다. + +``` +[오케스트레이터/메인] + ├── invoke_subagent(TypeName: "analyst") ──→ _workspace/02_analysis.md + ├── invoke_subagent(TypeName: "builder") ──→ _workspace/03_build.md + ├── invoke_subagent(TypeName: "qa") ──────→ _workspace/04_qa_report.md + └── 결과 수집 및 통합 +``` + +**병렬 서브에이전트 패턴:** +독립적인 작업을 동시에 실행한다. `invoke_subagent`를 통해 여러 에이전트를 순차적으로 호출하여 모두 백그라운드로 보낸 뒤, 모든 결과가 수집될 때까지 대기하고 수집 후 통합한다. + +``` +[오케스트레이터/메인] + ├── invoke_subagent(TypeName: "researcher-a") ──→ _workspace/02_research_a.md + ├── invoke_subagent(TypeName: "researcher-b") ──→ _workspace/02_research_b.md + ├── invoke_subagent(TypeName: "researcher-c") ──→ _workspace/02_research_c.md + └── 모든 결과 통합 → 최종 산출물 +``` + +**직접 실행 패턴 (대안):** +단순 작업은 별도 서브에이전트 없이 메인이 직접 처리한다. 서브에이전트 생성 오버헤드가 작업 자체보다 클 때 사용. + +``` +[메인] + └── 직접 실행 (도구 호출) +``` + +#### 5-1. 데이터 전달 프로토콜 + +오케스트레이터 내에 서브에이전트 간 데이터 전달 방식을 명시한다: + +| 전략 | 방식 | 적합한 경우 | +|------|------|-----------| +| **파일 기반** | 약속된 경로에 파일을 쓰고 읽음 | 대용량 데이터, 구조화된 산출물, 감사 추적 필요 | +| **반환값 기반** | 서브에이전트 실행 결과 메시지 활용 | 경량 결과, 간단한 상태 전달 | +| **AGENTS.md 공유** | 프로젝트 AGENTS.md에 컨텍스트 기록 | 장기 보존이 필요한 설정 정보 | + +**권장 조합:** 파일 기반(주 산출물) + 반환값 기반(상태 전달) + +파일 기반 전달 시 규칙: +- 작업 디렉토리 하위에 `_workspace/` 폴더를 만들어 중간 산출물 저장 +- 파일명 컨벤션: `{phase}_{agent}_{artifact}.{ext}` (예: `01_analyst_requirements.md`) +- 최종 산출물만 사용자 지정 경로에 출력, 중간 파일(`_workspace/`)은 보존 (사후 검증·감사 추적용) + +#### 5-2. 에러 핸들링 + +오케스트레이터 내에 에러 처리 방침을 포함한다. 핵심 원칙: 1회 재시도 후 재실패 시 해당 결과 없이 진행(보고서에 누락 명시), 상충 데이터는 삭제하지 않고 출처 병기. + +> 에러 유형별 전략표와 구현 상세는 `rules/orchestrator-template.md`의 "에러 핸들링" 참조. + +#### 5-3. 팀 크기 가이드라인 + +| 작업 규모 | 권장 서브에이전트 수 | 에이전트당 작업 수 | +|----------|-------------------|--------------| +| 소규모 (5~10개 작업) | 2~3명 | 3~5개 | +| 중규모 (10~20개 작업) | 3~5명 | 4~6개 | +| 대규모 (20개+ 작업) | 5~7명 | 4~5개 | + +> 서브에이전트가 많을수록 메인의 조율 부담이 커진다. 3명의 집중된 팀이 5명의 산만한 팀보다 낫다. + +#### 5-4. AGENTS.md 하네스 포인터 등록 + +하네스 구성 완료 후, 프로젝트의 `AGENTS.md`에 최소한의 포인터를 등록한다. AGENTS.md는 새 세션마다 로딩되므로, 하네스 존재와 트리거 규칙만 기록하면 오케스트레이터 스킬이 나머지를 처리한다. + +**AGENTS.md 템플릿:** + +```markdown +## 하네스: {도메인명} + +**목표:** {하네스의 핵심 목표 한 줄} + +**트리거:** {도메인} 관련 작업 요청 시 `{orchestrator-skill-name}` 스킬을 사용하라. 단순 질문은 직접 응답 가능. + +**변경 이력:** +| 날짜 | 변경 내용 | 대상 | 사유 | +|------|----------|------|------| +| {YYYY-MM-DD} | 초기 구성 | 전체 | - | +``` + +**AGENTS.md에 넣지 않는 것:** 서브에이전트 목록, 스킬 목록, 디렉토리 구조, 실행 규칙 상세. 이유: 에이전트/스킬 목록은 오케스트레이터 스킬과 플러그인 디렉토리 내부에서 관리하므로 중복이다. 디렉토리 구조는 파일 시스템에서 직접 확인 가능하다. AGENTS.md는 **포인터(트리거 규칙) + 변경 이력**만 담는다. + +#### 5-5. 후속 작업 지원 + +오케스트레이터는 초기 실행뿐 아니라 후속 작업도 처리해야 한다. 다음 세 가지를 보장하라: + +**1. 오케스트레이터 description에 후속 키워드 포함:** +초기 생성 키워드만으로는 후속 요청이 트리거되지 않는다. description에 반드시 포함할 후속 표현: +- "다시 실행", "재실행", "업데이트", "수정", "보완" +- "{도메인}의 {부분작업}만 다시" +- "이전 결과 기반으로", "결과 개선" + +**2. 오케스트레이터 Phase 1에 컨텍스트 확인 단계 추가:** +워크플로우 시작 시 기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다: +- `_workspace/` 존재 + 사용자가 부분 수정 요청 → **부분 재실행** (해당 서브에이전트만 재호출) +- `_workspace/` 존재 + 사용자가 새 입력 제공 → **새 실행** (기존 _workspace를 `_workspace_prev/`로 이동) +- `_workspace/` 미존재 → **초기 실행** + +**3. 서브에이전트 정의에 재호출 지침 포함:** +각 서브에이전트 `agent.json` 내의 systemPromptSections에 "이전 산출물이 있을 때의 행동"을 명시한다: +- 이전 결과 파일이 존재하면 읽고 개선점을 반영 +- 사용자 피드백이 주어지면 해당 부분만 수정 + +> 오케스트레이터 템플릿의 "Phase 0: 컨텍스트 확인" 섹션 참조: `rules/orchestrator-template.md` + +### Phase 6: 검증 및 테스트 + +생성된 하네스를 검증한다. 상세 테스트 방법론은 `rules/skill-testing-guide.md` 참조. + +#### 6-1. 구조 검증 + +- 모든 서브에이전트 `agent.json` 파일이 올바른 위치에 있는지 확인 +- 스킬의 frontmatter(name, description) 검증 +- 서브에이전트 간 참조 일관성 확인 + +#### 6-2. 실행 모드별 검증 + +- **서브에이전트**: 각 에이전트의 입출력 연결, 파일 기반 데이터 흐름 확인 +- **병렬 서브에이전트**: 독립성 보장 (동일 파일에 동시 쓰기 방지), 결과 수집 로직 확인 +- **직접 실행**: 오케스트레이터가 불필요한 에이전트 분리를 하지 않았는지 확인 + +#### 6-3. 스킬 실행 테스트 + +생성된 각 스킬에 대해 실제 실행 테스트를 수행한다: + +1. **테스트 프롬프트 작성** — 각 스킬에 대해 2~3개의 현실적인 테스트 프롬프트를 작성한다. 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장으로 작성한다. +2. **With-skill vs Without-skill 비교 실행** — 가능하면 스킬 있는 실행과 없는 실행을 비교하여 스킬의 부가가치를 확인한다. +3. **결과 평가** — 산출물의 품질을 정성적(사용자 리뷰) + 정량적(assertion 기반) 으로 평가한다. 산출물이 객관적으로 검증 가능한 경우(파일 생성, 데이터 추출 등) assertion을 정의하고, 주관적인 경우(문체, 디자인) 사용자 피드백에 의존한다. +4. **반복 개선 루프** — 테스트 결과에서 문제가 발견되면: + - 피드백을 **일반화**하여 스킬을 수정한다 (특정 예시에만 맞는 좁은 수정 금지) + - 수정 후 재테스트한다 + - 사용자가 만족하거나 의미 있는 개선이 더 이상 없을 때까지 반복한다. +5. **반복 패턴 번들링** — 테스트 실행에서 에이전트들이 공통으로 작성하는 코드가 발견되면, 해당 코드를 `scripts/`에 미리 번들링한다. + +#### 6-4. 트리거 검증 + +각 스킬의 description이 올바르게 트리거되는지 검증한다: + +1. **Should-trigger 쿼리** (8~10개) — 스킬을 트리거해야 하는 다양한 표현 (공식적/캐주얼, 명시적/암시적) +2. **Should-NOT-trigger 쿼리** (8~10개) — 키워드가 유사하지만 이 스킬이 아닌 다른 도구/스킬이 적합한 "near-miss" 쿼리 + +**near-miss 작성 핵심:** "피보나치 함수 작성" 같이 명백히 무관한 쿼리는 테스트 가치가 없다. "이 엑셀 파일의 차트를 PNG로 추출해줘" (xlsx 스킬 vs 이미지 변환)처럼 **경계가 모호한 쿼리**가 좋은 테스트 케이스다. + +기존 스킬과의 트리거 충돌도 이 단계에서 확인한다. + +#### 6-5. 드라이런 테스트 + +- 오케스트레이터 스킬의 Phase 순서가 논리적인지 검토 +- 데이터 전달 경로에 빈 구간(dead link)이 없는지 확인 +- 모든 서브에이전트의 입력이 이전 Phase의 출력과 매칭되는지 확인 +- 에러 시나리오별 폴백 경로가 실행 가능한지 확인 + +#### 6-6. 테스트 시나리오 작성 + +- 오케스트레이터 스킬에 `## 테스트 시나리오` 섹션 추가 +- 정상 흐름 1개 + 에러 흐름 1개 이상 기술 + +### Phase 7: 하네스 진화 + +하네스는 한 번 만들고 끝나는 정적 산출물이 아니다. 사용자 피드백에 따라 계속 진화하는 시스템이다. + +#### 7-1. 실행 후 피드백 수집 + +매 하네스 실행 완료 후, 사용자에게 피드백을 요청한다: +- "결과에서 개선할 부분이 있나요?" +- "서브에이전트 구성이나 워크플로우에 바꾸고 싶은 점이 있나요?" + +피드백이 없으면 넘어간다. 강요하지 않되, 반드시 기회를 제공한다. + +#### 7-2. 피드백 반영 경로 + +피드백 유형에 따라 수정 대상이 다르다: + +| 피드백 유형 | 수정 대상 | 예시 | +|-----------|----------|------| +| 결과물 품질 | 해당 에이전트의 스킬 | "분석이 너무 피상적" → 스킬에 깊이 기준 추가 | +| 에이전트 역할 | 서브에이전트 정의 `agent.json` | "보안 검토도 필요" → 새 에이전트 추가 | +| 워크플로우 순서 | 오케스트레이터 스킬 | "검증을 먼저 해야" → Phase 순서 변경 | +| 팀 구성 | 오케스트레이터 + 에이전트 | "이 둘은 합쳐도 될 듯" → 에이전트 병합 | +| 트리거 누락 | 스킬 description | "이 표현으로 하면 작동 안 함" → description 확장 | + +#### 7-3. 변경 이력 + +모든 변경은 AGENTS.md의 **변경 이력** 테이블에 기록한다 (Phase 5-4 템플릿의 "변경 이력" 섹션과 동일 테이블): + +```markdown +**변경 이력:** +| 날짜 | 변경 내용 | 대상 | 사유 | +|------|----------|------|------| +| 2026-04-05 | 초기 구성 | 전체 | - | +| 2026-04-07 | QA 에이전트 추가 | agents/qa/agent.json | 산출물 품질 검증 부족 피드백 | +| 2026-04-10 | 톤 가이드 추가 | skills/content-creator | "너무 딱딱하다" 피드백 | +``` + +이 이력을 통해 하네스가 어떤 방향으로 진화했는지 추적하고, 퇴행(regression)을 방지한다. + +#### 7-4. 진화 트리거 + +사용자가 명시적으로 "하네스 수정해줘"라고 할 때만이 아니라, 다음 상황에서도 진화를 제안한다: +- 같은 유형의 피드백이 2회 이상 반복될 때 +- 서브에이전트가 반복적으로 실패하는 패턴이 발견될 때 +- 사용자가 오케스트레이터를 우회하여 수동으로 작업하는 것이 관찰될 때 + +#### 7-5. 운영/유지보수 워크플로우 + +기존 하네스의 점검·수정·동기화를 체계적으로 수행한다. Phase 0에서 "운영/유지보수" 분기로 진입했을 때 이 워크플로우를 따른다. + +**Step 1: 현황 감사** +- 플러그인 디렉토리(`agents/`) 파일 목록과 오케스트레이터 스킬의 에이전트 구성 비교 → 불일치 목록 생성 +- 플러그인 디렉토리(`skills/`) 목록과 오케스트레이터 스킬의 스킬 구성 비교 → 불일치 목록 생성 +- 감사 결과를 사용자에게 보고한다. + +**Step 2: 점진적 추가/수정** +- 사용자 요청에 따라 서브에이전트 추가/수정/삭제, 스킬 추가/수정/삭제를 수행한다. +- 변경은 한 번에 하나씩, 각 변경 후 즉시 Step 3(동기화)을 실행한다. + +**Step 3: AGENTS.md 변경 이력 갱신** +- 변경 이력 테이블에 날짜, 변경 내용, 대상, 사유를 기록한다. + +**Step 4: 변경 검증** +- 수정된 에이전트/스킬의 구조 검증 (Phase 6-1 기준) +- 수정 범위가 트리거에 영향을 주면 트리거 검증 (Phase 6-4 기준) +- 대규모 변경(아키텍처 변경, 에이전트 3개 이상 추가/삭제) 시 Phase 6-3(실행 테스트), 6-5(드라이런)까지 수행 +- AGENTS.md와 실제 파일의 일치 여부 최종 확인 + +## 산출물 체크리스트 + +생성 완료 후 확인: + +- [ ] `.agents/plugins/{domain}-plugin/plugin.json` — **플러그인 정의 파일 필수 생성** +- [ ] `.agents/plugins/{domain}-plugin/agents/{name}/agent.json` — **서브에이전트 정의 파일 필수 생성** +- [ ] `.agents/plugins/{domain}-plugin/skills/` — 스킬 파일들 (SKILL.md + rules/) +- [ ] 오케스트레이터 스킬 1개 (데이터 흐름 + 에러 핸들링 + 테스트 시나리오 포함) +- [ ] 실행 모드 명시 (invoke_subagent 기반 서브에이전트 / 병렬 서브에이전트 / 직접 실행 중 선택) +- [ ] 기존 에이전트/스킬과 충돌 없음 +- [ ] **작성 언어(한국어/영어) 일관성 및 다국어 대응 규칙 준수** (영문 요청 시 모든 에이전트/스킬 정의 및 오케스트레이터 텍스트 영어 작성) +- [ ] 스킬 description이 적극적("pushy")으로 작성됨 — **후속 작업 키워드 포함** +- [ ] SKILL.md 본문이 500줄 이내, 초과 시 rules/ 분리 +- [ ] 테스트 프롬프트 2~3개로 실행 검증 완료 +- [ ] 트리거 검증 (should-trigger + should-NOT-trigger) 완료 +- [ ] **AGENTS.md에 하네스 포인터 등록** (트리거 규칙 + 변경 이력) +- [ ] **AGENTS.md 변경 이력에 에이전트/스킬 추가/삭제/수정 기록** +- [ ] **오케스트레이터 Phase 1에 컨텍스트 확인 단계** (초기/후속/부분 재실행 판별) + +## 참고 + +- 하네스 패턴: `rules/agent-design-patterns.md` +- 기존 하네스 예시 (실제 파일 전문 포함): `rules/team-examples.md` +- 오케스트레이터 템플릿: `rules/orchestrator-template.md` +- **스킬 작성 가이드**: `rules/skill-writing-guide.md` — 작성 패턴, 예시, 데이터 스키마 표준 +- **스킬 테스트 가이드**: `rules/skill-testing-guide.md` — 테스트/평가/반복 개선 방법론 +- **QA 에이전트 가이드**: `rules/qa-agent-guide.md` — 빌드 하네스에 QA 에이전트를 포함할 때 참조. diff --git a/.agents/plugins/harness-plugin/skills/harness/rules/agent-design-patterns.md b/.agents/plugins/harness-plugin/skills/harness/rules/agent-design-patterns.md new file mode 100644 index 0000000..688ace3 --- /dev/null +++ b/.agents/plugins/harness-plugin/skills/harness/rules/agent-design-patterns.md @@ -0,0 +1,233 @@ +# 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)"** 해당 전문 작업을 독립된 컨텍스트에서 수행할 것인가 | diff --git a/.agents/plugins/harness-plugin/skills/harness/rules/orchestrator-template.md b/.agents/plugins/harness-plugin/skills/harness/rules/orchestrator-template.md new file mode 100644 index 0000000..468e16a --- /dev/null +++ b/.agents/plugins/harness-plugin/skills/harness/rules/orchestrator-template.md @@ -0,0 +1,248 @@ +# 오케스트레이터 스킬 템플릿 (Antigravity CLI) + +오케스트레이터는 팀 전체를 조율하는 상위 스킬이다. Antigravity CLI에서는 메인 에이전트가 오케스트레이터 역할을 하며, `invoke_subagent` 도구를 호출하여 각 서브에이전트에게 작업을 위임하고 전체 워크플로우를 통제한다. + +**실행 모드별 3가지 템플릿:** +- **템플릿 A: 서브에이전트 모드 (기본)** — 순차적 위임, 파일 기반 데이터 전달 +- **템플릿 B: 병렬 서브에이전트 모드** — 독립 작업 동시 실행 +- **템플릿 C: 하이브리드 모드** — Phase마다 다른 패턴 혼합 + +--- + +## 템플릿 A: 서브에이전트 모드 (기본 · 순차) + +2명 이상의 서브에이전트가 순차적으로 협업할 때 사용한다. 각 서브에이전트는 독립된 격리 컨텍스트에서 실행되며, 약속된 파일 경로를 통해 중간 결과를 넘겨받아 가공한다. + +```markdown +--- +name: {domain}-orchestrator +description: "{도메인} 서브에이전트 팀을 조율하는 오케스트레이터. {초기 실행 키워드}. 후속 작업: {도메인} 결과 수정, 부분 재실행, 업데이트, 보완, 다시 실행, 이전 결과 개선 요청 시에도 반드시 이 스킬을 사용." +--- + +# {Domain} Orchestrator + +{도메인}의 서브에이전트 팀을 조율하여 {최종 산출물}을 생성하는 통합 스킬. + +## 실행 모드: 서브에이전트 (순차) + +## 서브에이전트 구성 + +| 에이전트 TypeName | 역할 | 스킬 | 출력 | +|:---|:---|:---|:---| +| {agent-1} | {역할} | {skill} | `_workspace/{phase}_{agent}_{artifact}.md` | +| {agent-2} | {역할} | {skill} | `_workspace/{phase}_{agent}_{artifact}.md` | + +## 워크플로우 + +### Phase 0: 컨텍스트 확인 (후속 작업 지원) + +기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다: + +1. `_workspace/` 디렉토리 존재 여부 확인 +2. 실행 모드 결정: + - **`_workspace/` 미존재** → 초기 실행. Phase 1로 진행 + - **`_workspace/` 존재 + 사용자가 부분 수정 요청** → 부분 재실행. `invoke_subagent`를 통해 해당 서브에이전트만 호출하고, 기존 산출물 중 수정 대상만 덮어쓴다. + - **`_workspace/` 존재 + 새 입력 제공** → 새 실행. 기존 `_workspace/`를 `_workspace_{YYYYMMDD_HHMMSS}/`로 백업 이동한 뒤 Phase 1 진행. +3. 부분 재실행 시: 이전 산출물 경로를 `invoke_subagent` 프롬프트에 포함하여, 서브에이전트가 기존 결과를 읽고 피드백을 반영하도록 지시한다. + +### Phase 1: 준비 +1. 사용자 입력 분석 — {무엇을 파악하는지} +2. 작업 디렉토리에 `_workspace/` 생성 + - **초기 실행**: 새 `_workspace/` 생성 + - **새 실행**: 기존 `_workspace/`를 백업 이동한 직후 새 `_workspace/` 재생성 +3. 입력 데이터를 `_workspace/00_input/`에 저장 + +### Phase 2: {주요 작업 — 예: 분석/조사} + +1. `invoke_subagent` 도구 호출로 {agent-1} 구동: + - **TypeName**: "{agent-1}" + - **Role**: "{agent-1-role}" + - **Prompt**: "지정된 입력 경로 `_workspace/00_input/`에서 데이터를 읽어 {구체적 분석 수행 내용}을 수행하고, 결과를 `_workspace/02_{agent-1}_result.md`에 작성하세요." + +2. `invoke_subagent` 도구 호출로 {agent-2} 구동: + - **TypeName**: "{agent-2}" + - **Role**: "{agent-2-role}" + - **Prompt**: "{agent-1}의 분석 결과 파일 `_workspace/02_{agent-1}_result.md`를 로드하여 {구체적 가공 내용}을 수행하고, 결과를 `_workspace/02_{agent-2}_result.md`에 최종 작성하세요." + +### Phase 3: {후속 작업 — 예: 생성/구현} + +3. `invoke_subagent` 도구 호출로 {agent-3} 구동: + - **TypeName**: "{agent-3}" + - **Role**: "{agent-3-role}" + - **Prompt**: "`_workspace/02_{agent-2}_result.md`를 로드하여 {구체적 생성 내용}을 수행하고, 결과를 `_workspace/03_{agent-3}_result.md`에 작성하세요." + +### Phase 4: 통합 +1. 모든 서브에이전트의 산출물 파일 Read (`view_file` 도구 활용) +2. {통합/검증 로직 적용} +3. 최종 산출물 생성: `{output-path}/{filename}` + +### Phase 5: 정리 +1. `_workspace/` 디렉토리 보존 (중간 산출물은 삭제하지 않음 — 사후 검증 및 히스토리 역추적용) +2. 사용자에게 결과 요약 보고 + +## 데이터 흐름 + +``` +[오케스트레이터/메인] + │ + ├── invoke_subagent("agent-1") ──→ _workspace/02_agent1_result.md + │ │ + │ ↓ (Read) + ├── invoke_subagent("agent-2") ──→ _workspace/02_agent2_result.md + │ │ + │ ↓ (Read) + ├── invoke_subagent("agent-3") ──→ _workspace/03_agent3_result.md + │ + └── 최종 결과 통합 및 생성 → 최종 산출물 +``` + +## 에러 핸들링 + +| 상황 | 전략 | +|------|------| +| 서브에이전트 1명 실패 | 1회 재호출 시도. 재실패 시 보고서에 누락을 명시하고 다음 단계 진행 | +| 과반 실패 | 사용자에게 즉각 에러 로그를 보고하고 진행 여부 컨펌 | +| 타임아웃 | 현재까지 수집된 부분 결과 및 백업 파일을 활용하여 복구 진행 | +| 서브에이전트 간 데이터 충돌 | 데이터를 덮어쓰지 않고 출처를 병기하여 보존 | + +## 테스트 시나리오 + +### 정상 흐름 +1. 사용자가 {입력}을 제공 +2. Phase 1에서 {분석 결과} 도출 +3. Phase 2에서 서브에이전트들 순차 실행 +4. Phase 3에서 산출물을 통합하여 최종 결과 생성 +5. 예상 결과: `{output-path}/{filename}` 생성 + +### 에러 흐름 +1. Phase 2에서 {agent-2} 실행 도중 에러 중단 +2. 오케스트레이터가 1회 재호출을 수행 +3. 재실행 실패 시 해당 단계를 누락 처리 +4. 나머지 결과로 Phase 3 진행 +5. 최종 보고서에 "{agent-2} 작업 영역 수집 실패"를 명시하고 보존 +``` + +--- + +## 템플릿 B: 병렬 서브에이전트 모드 (병렬) + +독립적인 여러 작업을 동시에 실행하여 리소스를 아끼고 속도를 높일 때 사용한다. 출력 파일들이 겹치지 않도록 경로 및 파일명을 명확히 구별해야 한다. + +```markdown +--- +name: {domain}-orchestrator +description: "{도메인} 서브에이전트 팀을 병렬 조율하는 오케스트레이터. {초기 실행 키워드}. 후속 작업 키워드 포함." +--- + +## 실행 모드: 병렬 서브에이전트 + +## 서브에이전트 구성 + +| 에이전트 TypeName | 역할 | 스킬 | 출력 | +|:---|:---|:---|:---| +| {agent-1} | {역할} | {skill} | `_workspace/02_{agent-1}.md` | +| {agent-2} | {역할} | {skill} | `_workspace/02_{agent-2}.md` | +| {agent-3} | {역할} | {skill} | `_workspace/02_{agent-3}.md` | + +## 워크플로우 + +### Phase 0: 컨텍스트 확인 +(Template A와 동일 — `_workspace/` 존재 여부 분기) + +### Phase 1: 준비 +1. 입력 분석 +2. `_workspace/` 생성 + +### Phase 2: 병렬 실행 +모든 서브에이전트가 백그라운드에서 실행될 수 있도록 순차적으로 `invoke_subagent` 도구를 즉시 호출한다 (각각 고유 출력 경로 지정): + +1. `invoke_subagent` 호출 ({agent-1}) +2. `invoke_subagent` 호출 ({agent-2}) +3. `invoke_subagent` 호출 ({agent-3}) +*모든 서브에이전트 완료 노티 및 응답을 수집할 때까지 대기.* + +### Phase 3: 통합 +1. 각 서브에이전트 완료 보고를 확인하고 `_workspace/` 하위 결과 수집 (Read) +2. 통합 로직 적용 → 최종 산출물 작성 + +### Phase 4: 정리 +1. `_workspace/` 보존 +2. 결과 요약 보고 + +## 에러 핸들링 +- 에이전트 1개 실패: 1회 재실행. 지속 실패 시 누락 명시 후 파이프라인 진행. +- 과반 실패: 사용자 조작 유도 및 컨펌. +- 출력 파일 경로 중복 방지: 각 에이전트의 출력 파일명에 TypeName을 포함하여 고유화. +``` + +--- + +## 템플릿 C: 하이브리드 모드 + +Phase마다 서로 다른 실행 패턴(순차, 병렬, 직접 실행)을 혼합하여 워크플로우를 설계한다. 각 Phase 상단에 `**실행 패턴:** {순차 | 병렬 | 직접}`를 필히 명시한다. + +```markdown +--- +name: {domain}-orchestrator +description: "{도메인} 오케스트레이터 (하이브리드). {키워드}. 후속 작업 키워드 포함." +--- + +## 실행 모드: 하이브리드 + +| Phase | 패턴 | 이유 | +|:---|:---|:---| +| Phase 2 (병렬 수집) | 병렬 서브에이전트 | 복수의 독립 자료 수집 속도 최적화 | +| Phase 3 (합의 통합) | 직접 실행 (메인 통합) | 복합적 정합성 및 가치 판단 필요 | +| Phase 4 (독립 검증) | 순차 서브에이전트 | QA 전문 에이전트를 통한 철저한 사후 분석 | + +## 워크플로우 + +### Phase 2: 병렬 자료 수집 +**실행 패턴:** 병렬 서브에이전트 + +여러 서브에이전트를 동시 구동한다. 결과는 각기 `_workspace/02_{agent}_raw.md`에 안전하게 분할 저장된다. + +### Phase 3: 합의 기반 통합 +**실행 패턴:** 직접 실행 + +메인 에이전트가 Phase 2의 출력 파일들을 모두 취합하여 읽어들여 상충 내용을 보완하고 종합적인 정합성을 반영한다. 최종 통합본 `_workspace/03_integrated.md`를 생산한다. + +### Phase 4: 독립 검증 +**실행 패턴:** 순차 서브에이전트 + +QA 서브에이전트 `invoke_subagent`를 구동하여, 입력으로 넘겨받은 `_workspace/03_integrated.md`에 대한 객관적인 품질 및 정합성 검증 레포트를 작성하도록 한다. +``` + +**하이브리드 전환 규칙:** +- **병렬 → 순차**: 병렬 구동 중인 모든 백그라운드 서브에이전트의 작업 완료(메시지 수집)를 완전 대기한 뒤 순차 Phase로 진입한다. +- **순차 → 병렬**: 이전 순차 단계 완료 후 저장된 최종 결과 경로를 모든 병렬 서브에이전트 프롬프트에 공유 및 전달하여 동시 작업을 시작한다. +- **서브에이전트 → 직접 실행**: 서브에이전트가 완성해 둔 산출물들을 메인 오케스트레이터가 직접 도구로 읽고 처리한다. + +--- + +## 작성 원칙 + +1. **실행 패턴 명시**: 오케스트레이터 스킬 상단에 어떤 패턴("순차 서브에이전트", "병렬 서브에이전트", "직접 실행", "하이브리드")을 쓰는지 반드시 적는다. +2. **`invoke_subagent` 도구 호출로 위임**: 서브에이전트 호출이 텍스트(예: @analyst)가 아닌, Antigravity CLI의 `invoke_subagent` 도구 실행임을 규정한다. +3. **고유 절대 경로 지정**: 에이전트 간 산출물이 엉키거나 덮어써지지 않도록 `_workspace/` 하위에 에이전트 이름이 들어간 고유 파일명을 설정한다. +4. **에러 폴백 설계**: 현실적인 실행 실패 및 복구 수단을 에러 핸들링 섹션에 기재한다. +5. **description 내 후속 제어 키워드 필수 반영**: 스킬이 1회용으로 사장되지 않도록 "재실행, 다시 실행, 수정, 업데이트, 보완" 등의 키워드를 description에 확실히 담는다. +6. **에러 핸들링은 현실적으로** — "모든 것이 성공한다"고 가정하지 않는다. +7. **테스트 시나리오 필수** — 정상 흐름 1개 + 에러 흐름 1개 이상 기술한다. + +## description 작성 시 후속 작업 키워드 + +오케스트레이터 description은 초기 실행 키워드만으로는 부족하다. 다음 후속 작업 표현을 반드시 포함하라: + +- 재실행/다시 실행/업데이트/수정/보완 +- "{도메인}의 {부분}만 다시" +- "이전 결과 기반으로", "결과 개선" +- 도메인 관련 일상적 요청 (예: 런치 전략 하네스라면 "런치", "홍보", "트렌딩" 등) + +후속 키워드가 없으면 첫 실행 후 하네스가 사실상 죽은 코드가 된다. + +## 실제 오케스트레이터 참고 + +병렬 서브에이전트 패턴의 오케스트레이터 기본 구조: +준비 → Phase 0(컨텍스트 확인) → invoke_subagent 병렬 호출 → 결과 수집 → 통합 → 정리. +`rules/team-examples.md`의 리서치 팀 예시를 참조. diff --git a/.agents/plugins/harness-plugin/skills/harness/rules/qa-agent-guide.md b/.agents/plugins/harness-plugin/skills/harness/rules/qa-agent-guide.md new file mode 100644 index 0000000..cff0e72 --- /dev/null +++ b/.agents/plugins/harness-plugin/skills/harness/rules/qa-agent-guide.md @@ -0,0 +1,220 @@ +# QA 서브에이전트 설계 가이드 (Antigravity CLI) + +빌드 하네스에 QA 에이전트를 포함할 때 참고하는 가이드. 실제 프로젝트(SatangSlide)에서 발견된 버그 패턴과 그 근본 원인 분석을 바탕으로, QA가 놓치기 쉬운 결함을 체계적으로 잡는 검증 방법론을 제공한다. + +> **참고:** 이 가이드는 Antigravity CLI의 플러그인 규격에 대응합니다. 서브에이전트 정의 파일은 `.agents/plugins/{plugin-name}/agents/{name}/agent.json`으로 위치시킵니다. + +--- + +## 목차 + +1. [QA 서브에이전트가 놓치는 결함의 패턴](#1-qa-서브에이전트가-놓치는-결함의-패턴) +2. [통합 정합성 검증](#2-통합-정합성-검증) +3. [QA 서브에이전트 설계 원칙](#3-qa-서브에이전트-설계-원칙) +4. [검증 체크리스트 템플릿](#4-검증-체크리스트-템플릿) +5. [QA 서브에이전트 정의 템플릿 (agent.json)](#5-qa-서브에이전트-정의-템플릿-agentjson) + +--- + +## 1. QA 서브에이전트가 놓치는 결함의 패턴 + +### 1-1. 경계면 불일치 (Boundary Mismatch) + +가장 빈번한 결함. 두 컴포넌트가 각각 "올바르게" 구현되어 있지만, 연결 지점에서 계약이 어긋남. + +| 경계면 | 불일치 예시 | 놓치는 이유 | +|:---|:---|:---| +| API 응답 → 프론트 훅 | API가 `{ projects: [...] }` 반환, 훅이 `SlideProject[]` 기대 | 각각 개별 검증하면 정상, 교차 비교 안 함 | +| API 응답 필드명 → 타입 정의 | API가 `thumbnailUrl`(camelCase), 타입이 `thumbnail_url`(snake_case) | TypeScript 제네릭으로 캐스팅하면 컴파일러가 못 잡음 | +| 파일 경로 → 링크 href | 페이지가 `/dashboard/create`에 있는데 링크가 `/create`로 지정 | 파일 구조와 href를 교차 비교하지 않음 | +| 상태 전이 맵 → 실제 status 업데이트 | 맵에 `generating_template → template_approved` 정의, 코드에서 전환 누락 | 맵 존재 확인만 하고, 모든 업데이트 코드를 추적하지 않음 | +| API 엔드포인트 → 프론트 훅 | API 존재하지만 대응 훅 없음 (호출 안 됨) | API 목록과 훅 목록을 1:1 매핑하지 않음 | +| 즉시 응답 → 비동기 결과 | API가 즉시 `{ status }` 반환, 프론트가 `data.failedIndices` 접근 | 동기/비동기 응답 구분 없이 타입만 확인 | + +### 1-2. 왜 정적 코드 리뷰로 못 잡나 + +- **TypeScript 제네릭의 한계**: `fetchJson()` — 런타임 응답이 `{ projects: [...] }`여도 컴파일 통과. +- **`npm run build` 통과 ≠ 정상 동작**: 타입 캐스팅, `any`, 제네릭이 사용되면 빌드는 성공하지만 런타임에 실패. +- **존재 검증 vs 연결 검증의 차이**: "API가 있는가?"와 "API의 응답이 호출측의 기대와 일치하는가?"는 전혀 다른 검증. + +--- + +## 2. 통합 정합성 검증 + +QA 서브에이전트에 반드시 포함해야 하는 **교차 비교 검증** 영역. + +### 2-1. API 응답 ↔ 프론트 훅 타입 교차 검증 + +**방법**: 각 API route의 `NextResponse.json()` 호출부와 대응 훅의 `fetchJson` 타입 파라미터를 비교. + +``` +검증 단계: +1. API route에서 NextResponse.json()에 전달하는 객체의 shape 추출 +2. 대응 훅에서 fetchJson의 T 타입 확인 +3. shape과 T가 일치하는지 비교 +4. 래핑 여부 확인 (API가 { data: [...] }를 반환하면 훅이 .data를 꺼내는지) +``` + +**특히 주의할 패턴:** +- 페이지네이션 API: `{ items: [], total, page }` vs 프론트가 배열 기대. +- snake_case DB 필드 → camelCase API 응답 → 프론트 타입 정의 간 불일치. +- 즉시 응답 (202 Accepted) vs 최종 결과의 shape 차이. + +### 2-2. 파일 경로 ↔ 링크/라우터 경로 매핑 + +**방법**: `src/app/` 하위 page 파일의 URL 경로를 추출하고, 코드 내 모든 `href`, `router.push()`, `redirect()` 값과 대조. + +``` +검증 단계: +1. src/app/ 하위 page.tsx 파일 경로에서 URL 패턴 추출 + - (group) → URL에서 제거 + - [param] → 동적 세그먼트 +2. 코드 내 모든 href=, router.push(, redirect( 값 수집 +3. 각 링크가 실제 존재하는 page 경로와 매칭되는지 확인 +4. route group 내부 페이지의 URL 접두사 주의 (예: dashboard/ 하위) +``` + +### 2-3. 상태 전이 완전성 추적 + +**방법**: 코드에서 모든 `status:` 업데이트를 추출하여 상태 전이 맵과 대조. + +``` +검증 단계: +1. 상태 전이 맵(STATE_TRANSITIONS)에서 허용된 전이 목록 추출 +2. 모든 API route에서 .update({ status: "..." }) 패턴 검색 +3. 각 전이가 맵에 정의되어 있는지 확인 +4. 맵에 정의된 전이 중 코드에서 실행되지 않는 것 식별 (죽은 전이) +5. 특히: 중간 상태(예: generating_template)에서 최종 상태(template_approved)로의 전환이 누락되지 않았는지 +``` + +### 2-4. API 엔드포인트 ↔ 프론트 훅 1:1 매핑 + +**방법**: 모든 API route와 프론트 훅을 나열하여 짝이 맞는지 확인. + +``` +검증 단계: +1. src/app/api/ 하위 route.ts에서 HTTP 메서드별 엔드포인트 목록 추출 +2. src/hooks/ 하위 use*.ts에서 fetch 호출 URL 목록 추출 +3. API 엔드포인트 중 훅에서 호출하지 않는 것 식별 → "사용 안 됨" 플래그 +4. "사용 안 됨"이 의도적인지 (관리 API 등) 아닌지 (호출 누락) 판단 +``` + +--- + +## 3. QA 서브에이전트 설계 원칙 + +### 3-1. 도구 사용에 제한을 두지 않는다 + +QA 서브에이전트는 Grep으로 패턴 검색, 스크립트 실행으로 자동 대조, 필요 시 수정까지 가능해야 하므로 안전한 읽기/쓰기 도구를 기본적으로 부여한다. + +### 3-2. 체크리스트는 "존재 확인"보다 "교차 비교"를 우선하라 + +| 약한 체크리스트 | 강한 체크리스트 | +|:---|:---| +| API 엔드포인트가 존재하는가? | API 엔드포인트의 응답 shape과 대응 훅의 타입이 일치하는가? | +| 상태 전이 맵이 정의되어 있는가? | 모든 status 업데이트 코드가 맵의 전이와 일치하는가? | +| 페이지 파일이 존재하는가? | 코드 내 모든 링크가 실제 존재하는 페이지를 가리키는가? | +| TypeScript strict mode인가? | 제네릭 캐스팅으로 우회된 타입 안전성이 없는가? | + +### 3-3. "양쪽을 동시에 읽어라" 원칙 + +QA가 경계면 버그를 잡으려면, 한쪽만 읽어선 안 된다. 반드시: +- API route **와** 대응 훅을 **같이** 읽고 +- 상태 전이 맵 **와** 실제 업데이트 코드를 **같이** 읽고 +- 파일 구조 **와** 링크 경로를 **같이** 읽어야 한다. + +서브에이전트 정의에 이 원칙을 명시적으로 기재하라. + +### 3-4. QA는 빌드 후가 아니라, 각 모듈 완성 직후에 실행하라 + +오케스트레이터에서 QA를 "Phase 4: 전체 완성 후"에만 배치하면 버그가 누적되어 디버깅 비용이 높아진다. 매 백엔드 API 및 기능 완성 직후 즉시 해당 API + 대응 훅의 교차 검증을 병렬 또는 순차적으로 실행하라 (Incremental QA). + +--- + +## 4. 검증 체크리스트 템플릿 + +QA 서브에이전트 정의에 포함할 웹 애플리케이션용 통합 정합성 체크리스트. + +```markdown +### 통합 정합성 검증 (웹 앱) + +#### API ↔ 프론트엔드 연결 +- [ ] 모든 API route의 응답 shape과 대응 훅의 제네릭 타입이 일치 +- [ ] 래핑된 응답({ items: [...] })은 훅에서 unwrap하는지 확인 +- [ ] snake_case ↔ camelCase 변환이 일관되게 적용 +- [ ] 즉시 응답(202)과 최종 결과의 shape이 프론트에서 구분되는지 확인 +- [ ] 모든 API 엔드포인트에 대응하는 프론트 훅이 존재하고 실제로 호출됨 + +#### 라우팅 정합성 +- [ ] 코드 내 모든 href/router.push 값이 실제 page 파일 경로와 매칭 +- [ ] route group ((group))이 URL에서 제거되는 것을 고려한 경로 검증 +- [ ] 동적 세그먼트([id])가 올바른 파라미터로 채워지는지 확인 + +#### 상태 머신 정합성 +- [ ] 정의된 모든 상태 전이가 코드에서 실행됨 (죽은 전이 없음) +- [ ] 코드의 모든 status 업데이트가 전이 맵에 정의됨 (무단 전이 없음) +- [ ] 중간 상태에서 최종 상태로의 전환이 누락되지 않음 +- [ ] 프론트에서 상태 기반 분기(if status === "X")의 X가 실제 도달 가능 + +#### 데이터 흐름 정합성 +- [ ] DB 스키마 필드명과 API 응답 필드명의 매핑이 일관됨 +- [ ] 프론트 타입 정의와 API 응답의 필드명이 일치 +- [ ] 옵셔널 필드에 대한 null/undefined 처리가 양쪽에서 일관됨 +``` + +--- + +## 5. QA 서브에이전트 정의 템플릿 (agent.json) + +빌드 하네스의 QA 에이전트 생성 시 활용하는 `agent.json` 파일 템플릿. + +```json +{ + "name": "qa-inspector", + "description": "QA 검증 전문가. 스펙 준수, 통합 정합성, 디자인 품질을 검증.", + "hidden": false, + "config": { + "customAgent": { + "systemPromptSections": [ + { + "title": "Agent System Instructions", + "content": "당신은 Antigravity CLI의 전문 서브에이전트 'qa-inspector'입니다.\n\n## 핵심 역할\n스펙 대비 구현 품질과 **모듈 간 통합 정합성**을 집중 검증합니다.\n\n## 검증 우선순위\n1. **통합 정합성** (가장 높음) — 경계면 불일치가 런타임 에러의 주요 원인\n2. **기능 스펙 준수** — API/상태머신/데이터모델\n3. **디자인 품질** — 색상/타이포/반응형\n4. **코드 품질** — 미사용 코드, 명명 규칙\n\n## 검증 방법: \"양쪽 동시 읽기\"\n경계면 검증은 반드시 **양쪽 코드를 동시에 열어** 교차 비교합니다:\n- API 응답 shape: `route.ts`의 NextResponse.json() **및** `hooks/`의 fetchJson\n- 라우팅: `src/app/` page 파일 경로 **및** href, router.push 값\n- 상태 전이: STATE_TRANSITIONS 맵 **및** `.update({ status })` 코드\n- DB → API → UI: 테이블 컬럼명 **및** API 응답 필드 → 타입 정의\n\n## 입력/출력 프로토콜\n- 입력: 검증 대상 코드베이스 경로, 스펙 문서\n- 출력: 검증 리포트 (`_workspace/qa_report.md`)\n * 통과/실패/미검증 항목을 아이콘으로 구분하여 기재할 것.\n * 실패 항목은 구체적 파일:라인 정보와 함께 명확한 수정 제안 코드를 포함할 것." + } + ], + "toolNames": [ + "view_file", + "write_to_file", + "replace_file_content", + "list_dir", + "grep_search", + "run_command" + ], + "systemPromptConfig": { + "includeSections": [ + "user_information", + "skills", + "messaging", + "artifacts", + "user_rules" + ] + } + } + } +} +``` + +--- + +## 실제 사례: SatangSlide에서 발견된 버그 + +이 가이드의 모든 내용은 아래 실제 버그에서 추출한 교훈이다. + +| 버그 | 경계면 | 원인 | +|:---|:---|:---| +| `projects?.filter is not a function` | API→훅 | API가 `{projects:[]}` 반환, 훅이 배열 기대 | +| 대시보드 모든 링크 404 | 파일경로→href | `/dashboard/` 접두사 누락 | +| 테마 이미지 안 보임 | API→컴포넌트 | `thumbnailUrl` vs `thumbnail_url` | +| 테마 선택 저장 안 됨 | API→훅 | select-theme API 존재, 훅 없음 | +| 생성 페이지 영원히 대기 | 상태전이→코드 | `template_approved` 전이 코드 누락 | +| `data.failedIndices` 크래시 | 즉시응답→프론트 | 백그라운드 결과를 즉시 응답에서 접근 | +| 완료 후 슬라이드 보기 404 | 파일경로→href | `/projects/` → `/dashboard/projects/` | diff --git a/.agents/plugins/harness-plugin/skills/harness/rules/skill-testing-guide.md b/.agents/plugins/harness-plugin/skills/harness/rules/skill-testing-guide.md new file mode 100644 index 0000000..3bcaee5 --- /dev/null +++ b/.agents/plugins/harness-plugin/skills/harness/rules/skill-testing-guide.md @@ -0,0 +1,283 @@ +# 스킬 테스트 & 반복 개선 가이드 (Antigravity CLI) + +하네스에서 생성한 스킬의 품질을 검증하고 반복적으로 개선하는 방법론. SKILL.md Phase 6의 보충 레퍼런스. + +--- + +## 목차 + +1. [테스트 프레임워크 개요](#1-테스트-프레임워크-개요) +2. [테스트 프롬프트 작성법](#2-테스트-프롬프트-작성법) +3. [실행 테스트: With-skill vs Baseline](#3-실행-테스트-with-skill-vs-baseline) +4. [정량적 평가: Assertion 기반 채점](#4-정량적-평가-assertion-기반-채점) +5. [전문 에이전트 활용](#5-전문-에이전트-활용) +6. [반복 개선 루프](#6-반복-개선-루프) +7. [Description 트리거 검증](#7-description-트리거-검증) +8. [워크스페이스 구조](#8-워크스페이스-구조) + +--- + +## 1. 테스트 프레임워크 개요 + +스킬 품질 검증은 **정성적 평가**와 **정량적 평가**의 조합이다. + +| 평가 유형 | 방법 | 적합한 스킬 | +|:---|:---|:---| +| **정성적** | 사용자가 산출물을 직접 리뷰 | 문체, 디자인, 창작물 등 주관적 품질 | +| **정량적** | assertion 기반 자동 채점 | 파일 생성, 데이터 추출, 코드 생성 등 객관적 검증 가능 | + +핵심 루프: **작성 → 테스트 실행 → 평가 → 개선 → 재테스트** + +--- + +## 2. 테스트 프롬프트 작성법 + +### 원칙 + +테스트 프롬프트는 **실제 사용자가 입력할 법한 구체적이고 자연스러운 문장**이어야 한다. 추상적이거나 인공적인 프롬프트는 테스트 가치가 낮다. + +### 나쁜 예 + +``` +"PDF를 처리하라" +"데이터를 추출하라" +"차트를 생성하라" +``` + +### 좋은 예 + +``` +"다운로드 폴더에 있는 'Q4_매출_최종_v2.xlsx'에서 C열(매출)과 D열(비용)을 +사용해서 이익률(%) 열을 추가해줘. 그리고 이익률 기준으로 내림차순 정렬." +``` + +``` +"이 PDF에서 3페이지 표를 추출해서 CSV로 변환해줘. 표 헤더가 2줄로 +되어 있어서 첫 번째 줄은 카테고리, 두 번째 줄이 실제 열 이름이야." +``` + +### 프롬프트 다양성 + +- **공식적 / 캐주얼** 톤 혼합. +- **명시적 / 암시적** 의도 혼합 (파일 형식을 직접 말하는 경우 vs 맥락으로 추론해야 하는 경우). +- **단순 / 복잡** 작업 혼합. +- 일부는 약어, 오타, 캐주얼한 표현 포함. + +### 커버리지 + +2~3개 프롬프트로 시작하되, 다음을 커버하도록 설계: +- 핵심 사용 사례 1개 +- 엣지 케이스 1개 +- (선택) 복합 작업 1개 + +--- + +## 3. 실행 테스트: With-skill vs Baseline + +### 3-1. 비교 실행 구조 + +각 테스트 프롬프트에 대해 스킬이 있는 실행과 없는 실행을 비교한다: + +**With-skill 실행:** +``` +프롬프트: "{테스트 프롬프트}" +스킬 경로: {스킬 경로} +출력 경로: _workspace/iteration-N/eval-{id}/with_skill/outputs/ +``` + +**Baseline 실행:** +``` +프롬프트: "{테스트 프롬프트}" (동일) +스킬: 없음 +출력 경로: _workspace/iteration-N/eval-{id}/without_skill/outputs/ +``` + +### 3-2. Baseline 선택 + +| 상황 | Baseline | +|:---|:---| +| 새 스킬 생성 | 스킬 없이 같은 프롬프트 실행 | +| 기존 스킬 개선 | 수정 전 스킬 버전 (스냅샷 보존) | + +--- + +## 4. 정량적 평가: Assertion 기반 채점 + +### 4-1. Assertion 작성 + +산출물이 객관적으로 검증 가능한 경우, 자동 채점을 위한 assertion을 정의한다. + +**좋은 assertion:** +- 객관적으로 참/거짓 판별 가능. +- 서술적인 이름으로 결과만 봐도 무엇을 검사하는지 명확. +- 스킬의 핵심 가치를 검증. + +**나쁜 assertion:** +- 스킬 유무와 무관하게 항상 통과하는 것 (예: "출력이 존재한다"). +- 주관적 판단이 필요한 것 (예: "잘 작성되었다"). + +### 4-2. 프로그래밍 가능한 검증 + +assertion이 코드로 검증 가능하면 스크립트로 작성한다. 눈으로 확인하는 것보다 빠르고 신뢰성 있으며, iteration마다 재사용 가능하다. + +### 4-3. Non-discriminating assertion 주의 + +"두 구성 모두에서 100% 통과"하는 assertion은 스킬의 차별적 가치를 측정하지 못한다. 이런 assertion을 발견하면 제거하거나, 더 도전적인 assertion으로 교체한다. + +### 4-4. 채점 결과 스키마 + +```json +{ + "expectations": [ + { + "text": "이익률 열이 추가됨", + "passed": true, + "evidence": "E열에 'profit_margin_pct' 열 확인" + }, + { + "text": "이익률 기준 내림차순 정렬", + "passed": false, + "evidence": "정렬 없이 원본 순서 유지됨" + } + ], + "summary": { + "passed": 1, + "failed": 1, + "total": 2, + "pass_rate": 0.50 + } +} +``` + +--- + +## 5. 전문 에이전트 활용 + +테스트/평가 과정에서 전문 역할의 서브에이전트를 활용하면 품질이 향상된다. + +### 5-1. Grader (채점자) + +assertion 기반 채점을 수행하고, 산출물에서 검증 가능한 주장(claim)을 추출하여 교차 검증한다. + +**역할:** +- assertion별 통과/실패 판정 + 근거 제시. +- 산출물에서 사실적 주장을 추출하고 검증. +- eval 자체의 품질에 대한 피드백 (assertion이 너무 쉽거나 모호한 경우 제안). + +### 5-2. Comparator (블라인드 비교자) + +두 산출물을 A/B로 익명화하여, 어떤 것이 스킬을 사용한 결과인지 모르는 상태에서 품질을 판정한다. + +**활용 시점:** "새 버전이 정말 더 나은가?"를 엄밀하게 확인하고 싶을 때. 일반적인 반복 개선에서는 생략 가능. + +**판정 기준:** +- 내용: 정확성, 완성도 +- 구조: 조직화, 포맷팅, 사용성 +- 종합 점수 + +### 5-3. Analyzer (분석자) + +벤치마크 데이터에서 통계적 패턴을 분석한다: +- Non-discriminating assertion (두 구성 모두 통과 → 차별력 없음). +- 고분산 eval (결과가 실행마다 크게 달라짐 → 불안정). +- 시간/토큰 트레이드오프 (스킬이 품질은 높이지만 비용도 높이는 경우). + +--- + +## 6. 반복 개선 루프 + +### 6-1. 피드백 수집 + +사용자에게 산출물을 보여주고 피드백을 받는다. 빈 피드백은 "이상 없음"으로 해석한다. + +### 6-2. 개선 원칙 + +1. **피드백을 일반화하라** — 테스트 예시에만 맞는 좁은 수정은 오버피팅이다. 원리 수준에서 수정한다. +2. **무게를 벌지 않는 것은 제거하라** — 실행 이력을 읽고, 스킬이 비생산적인 작업을 시키고 있다면 해당 부분을 삭제한다. +3. **Why를 설명하라** — 사용자의 피드백이 간결하더라도, 왜 그것이 중요한지 이해하고 그 이해를 스킬에 반영한다. +4. **반복 작업은 번들링하라** — 모든 테스트 실행에서 동일한 헬퍼 스크립트가 생성되면, `scripts/`에 미리 포함한다. + +### 6-3. 반복 절차 + +``` +1. 스킬 수정 +2. 새 iteration-N+1/ 디렉토리에 모든 테스트 케이스 재실행 +3. 사용자에게 결과 제시 (이전 iteration과 비교) +4. 피드백 수집 +5. 다시 수정 → 반복 +``` + +**종료 조건:** +- 사용자가 만족. +- 피드백이 모두 비어 있음 (모든 산출물 이상 없음). +- 의미 있는 개선이 더 이상 없음. + +### 6-4. 초안 → 재검토 패턴 + +스킬 수정 시, 초안을 작성한 후 **새로운 시각으로 다시 읽고** 개선한다. 한 번에 완벽하게 쓰려 하지 말고, 초안-검토 사이클을 거친다. + +--- + +## 7. Description 트리거 검증 + +### 7-1. 트리거 Eval 쿼리 작성 + +20개의 eval 쿼리를 작성한다 — should-trigger 10개 + should-NOT-trigger 10개. + +**쿼리 품질 기준:** +- 실제 사용자가 입력할 법한 구체적이고 자연스러운 문장. +- 파일 경로, 개인적 맥락, 열 이름, 회사명 등 구체적 디테일 포함. +- 길이, 톤, 형식 다양하게 혼합. +- 명확한 정답보다 **경계 케이스(edge case)**에 집중. + +**Should-trigger 쿼리 (8~10개):** +- 다양한 표현의 같은 의도 (공식적/캐주얼). +- 스킬/파일 유형을 명시적으로 말하지 않지만 분명히 필요한 경우. +- 비주류 사용 사례. +- 다른 스킬과 경쟁하지만 이 스킬이 이겨야 하는 경우. + +**Should-NOT-trigger 쿼리 (8~10개):** +- **Near-miss가 핵심** — 키워드가 유사하지만 다른 도구/스킬이 적합한 쿼리. +- 명백히 무관한 쿼리는 테스트 가치가 없다. +- 인접 도메인, 모호한 표현, 키워드 겹침 but 맥락이 다른 경우. + +### 7-2. 기존 스킬 충돌 검증 + +새 스킬의 description이 기존 스킬의 트리거 영역과 겹치지 않는지 확인한다: + +1. 기존 스킬 목록의 description을 수집. +2. 새 스킬의 should-trigger 쿼리가 기존 스킬을 잘못 트리거하지 않는지 확인. +3. 충돌 발견 시 description의 경계 조건을 더 명확히 기술. + +--- + +## 8. 워크스페이스 구조 + +테스트/평가 결과를 체계적으로 관리하는 디렉토리 구조: + +``` +{skill-name}-workspace/ +├── iteration-1/ +│ ├── eval-descriptive-name-1/ +│ │ ├── eval_metadata.json +│ │ ├── with_skill/ +│ │ │ ├── outputs/ +│ │ │ ├── timing.json +│ │ │ └── grading.json +│ │ └── without_skill/ +│ │ ├── outputs/ +│ │ ├── timing.json +│ │ └── grading.json +│ ├── eval-descriptive-name-2/ +│ │ └── ... +│ └── benchmark.json +├── iteration-2/ +│ └── ... +└── evals/ + └── evals.json +``` + +**규칙:** +- eval 디렉토리는 숫자가 아닌 **서술적 이름** 사용 (예: `eval-multi-page-table-extraction`). +- 각 iteration은 독립 디렉토리에 보존 (이전 iteration 덮어쓰기 금지). +- `_workspace/`는 삭제하지 않는다 (사후 검증 및 히스토리 역추적용). diff --git a/.agents/plugins/harness-plugin/skills/harness/rules/skill-writing-guide.md b/.agents/plugins/harness-plugin/skills/harness/rules/skill-writing-guide.md new file mode 100644 index 0000000..dee2641 --- /dev/null +++ b/.agents/plugins/harness-plugin/skills/harness/rules/skill-writing-guide.md @@ -0,0 +1,278 @@ +# 스킬 작성 가이드 (Antigravity CLI) + +하네스에서 생성하는 스킬의 품질을 높이기 위한 상세 작성 가이드. SKILL.md Phase 4의 보충 레퍼런스. + +--- + +## 목차 + +1. [Description 작성 패턴](#1-description-작성-패턴) +2. [본문 작성 스타일](#2-본문-작성-스타일) +3. [출력 형식 정의 패턴](#3-출력-형식-정의-패턴) +4. [예시 작성 패턴](#4-예시-작성-패턴) +5. [Progressive Disclosure 패턴](#5-progressive-disclosure-패턴) +6. [스크립트 번들링 판단 기준](#6-스크립트-번들링-판단-기준) +7. [데이터 스키마 표준](#7-데이터-스키마-표준) +8. [스킬에 포함하지 않을 것](#8-스킬에-포함하지-않을-것) + +--- + +## 1. Description 작성 패턴 + +Description은 스킬의 유일한 트리거 메커니즘이다. Antigravity CLI는 `available_skills` 목록에서 name + description만 보고 스킬 사용 여부를 결정한다. + +### 트리거 메커니즘 이해 + +Antigravity CLI는 기본 도구로 쉽게 처리할 수 있는 단순 작업(단순 파일 읽기 등)에는 스킬을 쉽게 호출하지 않는 성향이 있다. 복잡하고 다단계이며 전문성이 강력하게 요구되는 작업일수록 스킬 트리거 확률이 높다. + +### 작성 원칙 + +1. **스킬이 하는 일** + **구체적 트리거 상황**을 모두 기술. +2. 유사하지만 트리거하면 안 되는 경우를 구분하는 경계 조건 명시. +3. 약간 "pushy"하게 — 트리거 결정을 보수적으로 판단하려는 경향을 해소. + +### 좋은 예시 + +```yaml +description: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크, + 암호화/복호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나 + PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것. 단순히 PDF를 + '읽어달라'는 요청이 아닌 변환/편집/분석이 필요할 때 특히 유용." +``` + +```yaml +description: "엑셀/CSV/TSV 파일의 열 추가, 수식 계산, 서식, 차트, + 데이터 정제를 포함한 모든 스프레드시트 작업. 사용자가 스프레드시트 + 파일을 언급하면 — 심지어 캐주얼하게('다운로드 폴더의 xlsx')라고만 + 해도 — 이 스킬을 사용할 것." +``` + +### 나쁜 예시 + +- `"데이터를 처리하는 스킬"` — 너무 모호, 어떤 파일/작업인지 불분명. +- `"PDF 관련 작업"` — 구체적 동작 나열 없음, 트리거 상황 미기술. + +--- + +## 2. 본문 작성 스타일 + +### Why-First 원칙 + +LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. 강압적 규칙보다 맥락 전달이 효과적이다. + +**나쁜 예:** +```markdown +ALWAYS use pdfplumber for table extraction. NEVER use PyPDF2 for tables. +``` + +**좋은 예:** +```markdown +테이블 추출에는 pdfplumber를 사용한다. PyPDF2는 텍스트 추출에 특화되어 +있어 테이블의 행/열 구조를 보존하지 못하기 때문이다. pdfplumber는 +셀 경계를 인식하여 구조화된 데이터를 반환한다. +``` + +### 일반화 원칙 + +피드백이나 테스트 결과에서 문제가 발견되면, 특정 예시에만 맞는 좁은 수정 대신 **원리 수준에서 일반화**한다. + +**오버피팅 수정:** +```markdown +"Q4 매출" 열이 있으면 해당 열을 숫자로 변환하라. +``` + +**일반화된 수정:** +```markdown +열 이름에 "매출", "금액", "수량" 등 수치를 암시하는 키워드가 있으면 +해당 열을 숫자 타입으로 변환한다. 변환 실패 시 원본 값을 유지한다. +``` + +### 명령형 어조 + +"~합니다", "~할 수 있습니다" 대신 "~한다", "~하라" 형태를 사용한다. 스킬은 지시서이다. + +### 다국어 및 영문 작성 원칙 + +사용자가 영어로 요청을 하거나, 프로젝트의 글로벌 협업 환경/코드베이스 표준이 영어인 경우, 스킬(`SKILL.md`)은 완벽하게 영어로 작성되어야 한다. + +1. **YAML Frontmatter Description**: Antigravity CLI가 이해하기 쉽도록 구체적이고 명확한 영어 기술 용어를 사용하여 "pushy"하게 작성한다. +2. **자연스러운 영어 어조 (Technical English)**: + - 지시조의 동사 원형(Imperative Mood)으로 작성한다. (예: "Create", "Extract", "Validate" 등. "~is used to" 나 "~should be" 와 같은 수동태 대신 능동태 명령형 권장) + - 설명식 문장에서는 3인칭 단수/현재형 또는 간결한 문장 구조를 사용한다. +3. **용어 통일**: 한국어 스킬에서의 "서브에이전트", "산출물", "오케스트레이터" 등의 용어는 영문 스킬에서 "subagent", "artifact", "orchestrator"로 번역 및 정의를 일관되게 사용한다. + +### 컨텍스트 절약 + +컨텍스트 윈도우는 공공재다. 모든 문장이 토큰 비용을 정당화하는지 자문한다: +- "Antigravity CLI가 이미 알고 있는 내용인가?" → 삭제. +- "이 설명이 없으면 에이전트가 실수하는가?" → 유지. +- "구체적 예시 하나가 긴 설명보다 효과적인가?" → 예시로 대체. + +--- + +## 3. 출력 형식 정의 패턴 + +산출물의 형식이 중요한 스킬에서 사용: + +```markdown +## 보고서 구조 +다음 템플릿을 정확히 따른다: + +# [제목] +## 요약 +## 핵심 발견 +## 권장 사항 +``` + +형식 정의는 간결하게, 실제 예시를 포함하면 더 효과적이다. + +--- + +## 4. 예시 작성 패턴 + +예시는 긴 설명보다 효과적이다: + +```markdown +## 커밋 메시지 형식 + +**예시 1:** +입력: JWT 토큰 기반 사용자 인증 추가 +출력: feat(auth): JWT 기반 인증 구현 + +**예시 2:** +입력: 로그인 페이지에서 비밀번호 표시 버튼이 동작하지 않는 버그 수정 +출력: fix(login): 비밀번호 표시 토글 버튼 동작 수정 +``` + +--- + +## 5. Progressive Disclosure 패턴 + +### 패턴 1: 도메인별 분리 + +``` +bigquery-plugin/ +└── skills/ + └── bigquery-skill/ + ├── SKILL.md (개요 + 도메인 선택 가이드) + └── rules/ + ├── finance.md (매출, 빌링 메트릭) + ├── sales.md (기회, 파이프라인) + └── product.md (API 사용량, 기능) +``` + +사용자가 매출에 대해 물으면 `finance.md`만 로드하여 컨텍스트 효율을 최대화한다. + +### 패턴 2: 조건부 상세 + +```markdown +# DOCX 처리 + +## 문서 생성 +docx-js로 새 문서를 생성한다. → [DOCX-JS.md](rules/docx-js.md) 참조. + +## 문서 편집 +단순 편집은 XML을 직접 수정. +**추적 변경이 필요하면**: [REDLINING.md](rules/redlining.md) 참조. +``` + +### 패턴 3: 대형 레퍼런스 파일 구조 + +300줄 이상의 reference 파일은 상단에 목차를 포함한다: + +```markdown +# API 레퍼런스 + +## 목차 +1. [인증](#인증) +2. [엔드포인트 목록](#엔드포인트-목록) +3. [에러 코드](#에러-코드) +4. [레이트 리밋](#레이트-리밋) + +--- + +## 인증 +... +``` + +--- + +## 6. 스크립트 번들링 판단 기준 + +테스트 실행에서 에이전트들의 실행 이력을 관찰한다. 다음 패턴이 보이면 번들링 대상: + +| 신호 | 조치 | +|:---|:---| +| 3개 테스트 중 3개에서 동일한 헬퍼 스크립트 생성 | `scripts/`에 번들링 | +| 매번 같은 pip install/npm install 실행 | 스킬에 의존성 설치 단계 명시 | +| 동일한 다단계 접근법 반복 | 스킬 본문에 표준 절차로 기술 | +| 매번 비슷한 에러 후 같은 회피책 적용 | 스킬에 알려진 문제와 해결법 기술 | + +번들링된 스크립트는 반드시 실행 테스트를 거친다. + +--- + +## 7. 데이터 스키마 표준 + +스킬 간 데이터 교환의 일관성을 위해 표준 스키마를 사용한다. 하네스에서 생성하는 스킬의 테스트/평가에 사용할 수 있다. + +### eval_metadata.json + +각 테스트 케이스의 메타데이터: + +```json +{ + "eval_id": 0, + "eval_name": "descriptive-name-here", + "prompt": "사용자의 작업 프롬프트", + "assertions": [ + "산출물에 X가 포함되어 있다", + "Y 형식으로 파일이 생성되었다" + ] +} +``` + +### grading.json + +assertion 기반 채점 결과: + +```json +{ + "expectations": [ + { + "text": "산출물에 '서울'이 포함됨", + "passed": true, + "evidence": "3번째 단계에서 '서울 지역 데이터 추출' 확인" + } + ], + "summary": { + "passed": 2, + "failed": 1, + "total": 3, + "pass_rate": 0.67 + } +} +``` + +**필드명 주의:** `text`, `passed`, `evidence`를 정확히 사용한다 (`name`/`met`/`details` 등 변형 금지). + +### timing.json + +실행 시간/토큰 측정: + +```json +{ + "total_tokens": 84852, + "duration_ms": 23332, + "total_duration_seconds": 23.3 +} +``` + +--- + +## 8. 스킬에 포함하지 않을 것 + +- README.md, CHANGELOG.md, INSTALLATION_GUIDE.md 등 부가 문서. +- 스킬 생성 과정의 메타 정보 (테스트 결과, 반복 이력). +- 사용자 대상 설명서 (스킬은 AI 에이전트를 위한 지시서). +- 이미 Antigravity CLI가 알고 있는 일반적 지식. diff --git a/.agents/plugins/harness-plugin/skills/harness/rules/team-examples.md b/.agents/plugins/harness-plugin/skills/harness/rules/team-examples.md new file mode 100644 index 0000000..c12ac81 --- /dev/null +++ b/.agents/plugins/harness-plugin/skills/harness/rules/team-examples.md @@ -0,0 +1,275 @@ +# Agent Team Examples (Antigravity CLI) + +--- + +## 예시 1: 리서치 팀 (병렬 서브에이전트 모드) + +### 팀 아키텍처: 팬아웃/팬인 +### 실행 모드: 병렬 서브에이전트 + +``` +[오케스트레이터/메인] + ├── invoke_subagent(TypeName: "official-researcher") → research_official.md + ├── invoke_subagent(TypeName: "media-researcher") → research_media.md + ├── invoke_subagent(TypeName: "community-researcher") → research_community.md + ├── invoke_subagent(TypeName: "background-researcher") → research_background.md + └── 통합 → 종합보고서.md +``` + +### 서브에이전트 구성 + +| 에이전트 TypeName | 역할 | 출력 | +|:---|:---|:---| +| `official-researcher` | 공식 문서/블로그 | `_workspace/02_official.md` | +| `media-researcher` | 미디어/투자 | `_workspace/02_media.md` | +| `community-researcher` | 커뮤니티/SNS | `_workspace/02_community.md` | +| `background-researcher` | 배경/경쟁/학술 | `_workspace/02_background.md` | +| (오케스트레이터/메인) | 통합 보고서 | `종합보고서.md` | + +> 리서치 서브에이전트는 각기 `.agents/plugins/research-plugin/agents/{name}/agent.json` 파일에 정의한다. 파일에는 역할·조사 범위·출력 형식을 명시하여 재사용성과 결과 일관성을 보장한다. + +### 오케스트레이터 워크플로우 (병렬 서브에이전트) + +``` +Phase 1: 준비 + - 사용자 입력 분석 (주제, 조사 모드 파악) + - _workspace/ 생성 + - 입력 데이터를 _workspace/00_input/에 저장 + +Phase 2: 병렬 조사 + - 4개 서브에이전트 동시 백그라운드 구동 (invoke_subagent): + TypeName: "official-researcher" → _workspace/02_official.md + TypeName: "media-researcher" → _workspace/02_media.md + TypeName: "community-researcher" → _workspace/02_community.md + TypeName: "background-researcher" → _workspace/02_background.md + - 모든 에이전트 완료 노티 대기 + +Phase 3: 통합 + - 메인이 4개 산출물 Read + - 종합 보고서 생성 + - 상충 정보는 출처 병기 + +Phase 4: 정리 + - _workspace/ 보존 (사후 검증·감사 추적용) +``` + +--- + +## 예시 2: SF 소설 집필 팀 (순차 + 병렬 서브에이전트) + +### 팀 아키텍처: 파이프라인 + 팬아웃 +### 실행 모드: 서브에이전트 (순차 + 병렬 혼합) + +``` +Phase 1 (병렬): invoke_subagent(worldbuilder) + invoke_subagent(character-designer) + invoke_subagent(plot-architect) + → 각자 독립적으로 세계관/캐릭터/플롯 생성 +Phase 2 (순차): invoke_subagent(prose-stylist) (집필) — Phase 1 결과 모두 입력 +Phase 3 (병렬): invoke_subagent(science-consultant) + invoke_subagent(continuity-manager) (리뷰) +Phase 4 (순차): invoke_subagent(prose-stylist) (리뷰 반영 수정) +``` + +### 서브에이전트 구성 + +| 에이전트 TypeName | 역할 | 스킬 | +|:---|:---|:---| +| `worldbuilder` | 세계관 구축 | world-setting | +| `character-designer` | 캐릭터 설계 | character-profile | +| `plot-architect` | 플롯 구조 | outline | +| `prose-stylist` | 문체 편집 + 집필 | write-scene, review-chapter | +| `science-consultant` | 과학 검증 | science-check | +| `continuity-manager` | 일관성 검증 | consistency-check | + +### 서브에이전트 파일 전문 예시: `worldbuilder/agent.json` + +```json +{ + "name": "worldbuilder", + "description": "SF 소설의 세계관을 구축하는 전문가. 물리 법칙, 사회 구조, 기술 수준, 역사를 설계한다.", + "hidden": false, + "config": { + "customAgent": { + "systemPromptSections": [ + { + "title": "Agent System Instructions", + "content": "당신은 SF 소설의 세계관 설계 전문가 'worldbuilder'입니다. 과학적 사실에 기반하되 상상력을 확장하여, 이야기가 펼쳐질 세계의 물리적·사회적·기술적 토대를 구축합니다.\n\n## 핵심 역할\n1. 세계의 물리 법칙과 기술 수준 정의\n2. 사회 구조, 정치 체계, 경제 시스템 설계\n3. 역사적 맥락과 현재 갈등 구조 수립\n4. 장소별 환경과 분위기 묘사\n\n## 작업 원칙\n- 내적 일관성 최우선 — 설정 간 모순이 없어야 한다\n- \"만약 이 기술이 있다면?\" 연쇄 질문으로 세계의 파급 효과를 추론\n- 이야기에 봉사하는 세계관 — 플롯을 방해하는 과도한 설정은 지양\n\n## 입력/출력 프로토콜\n- 입력: 사용자의 세계관 컨셉, 장르 요구사항\n- 출력: `_workspace/01_worldbuilder_setting.md`\n- 형식: 마크다운. 섹션별 (물리/사회/기술/역사/장소)\n\n## 에러 핸들링\n- 컨셉이 모호하면 3가지 방향을 제안하고 선택 요청\n- 과학적 오류 발견 시 대안을 함께 제시\n\n## 협업 프로토콜\n- character-designer와 plot-architect가 내 결과를 참조하여 작업하게 되므로 일관성을 우선하세요.\n- science-consultant의 피드백이 수집되면 이에 따라 설정을 수정하세요." + } + ], + "toolNames": [ + "view_file", + "write_to_file", + "replace_file_content" + ], + "systemPromptConfig": { + "includeSections": [ + "user_information", + "skills", + "messaging", + "artifacts" + ] + } + } + } +} +``` + +### 워크플로우 상세 + +``` +Phase 1: @worldbuilder, @character-designer, @plot-architect 병렬 호출 + → 각각 _workspace/01_world.md, _workspace/01_characters.md, _workspace/01_plot.md 저장 + +Phase 2: @prose-stylist 호출 (Phase 1의 3개 산출물 입력) + → _workspace/02_prose_draft.md 저장 + +Phase 3: @science-consultant, @continuity-manager 병렬 호출 + → 각각 _workspace/03_science_review.md, _workspace/03_continuity_review.md 저장 + +Phase 4: @prose-stylist 재호출 (리뷰 결과 반영) + → 최종 원고 저장 +``` + +--- + +## 예시 3: 웹툰 제작 팀 (순차 서브에이전트 — 생성-검증 루프) + +### 팀 아키텍처: 생성-검증 +### 실행 모드: 순차 서브에이전트 + +``` +루프 (최대 2회): +Phase 1: invoke_subagent(webtoon-artist) → 패널 이미지 생성 +Phase 2: invoke_subagent(webtoon-reviewer) → 품질 검수 +Phase 3: (REDO 발생 시) invoke_subagent(webtoon-artist) 재호출 → 문제 패널 재생성 +``` + +### 서브에이전트 구성 + +| 에이전트 TypeName | 역할 | 스킬 | +|:---|:---|:---| +| `webtoon-artist` | 패널 이미지 생성 | generate-webtoon | +| `webtoon-reviewer` | 품질 검수 | review-webtoon | + +### 서브에이전트 파일 전문 예시: `webtoon-reviewer/agent.json` + +```json +{ + "name": "webtoon-reviewer", + "description": "웹툰 패널의 품질을 검수하는 전문가. 구도, 캐릭터 일관성, 텍스트 가독성, 연출을 평가한다.", + "hidden": false, + "config": { + "customAgent": { + "systemPromptSections": [ + { + "title": "Agent System Instructions", + "content": "당신은 웹툰 패널의 품질을 검수하는 전문가 'webtoon-reviewer'입니다. 시각적 완성도, 스토리 전달력, 캐릭터 일관성을 기준으로 패널을 평가합니다.\n\n## 핵심 역할\n1. 각 패널의 구도와 시각적 완성도 평가\n2. 캐릭터 외형의 패널 간 일관성 검증\n3. 말풍선 텍스트의 가독성과 배치 평가\n4. 전체 에피소드의 연출 흐름과 페이싱 검토\n\n## 작업 원칙\n- PASS/FIX/REDO 3단계로 명확히 판정\n- FIX는 부분 수정으로 해결 가능한 경우, REDO는 전면 재생성 필요\n- 주관적 취향이 아닌 객관적 기준(일관성, 가독성, 구도)으로 판단\n\n## 입력/출력 프로토콜\n- 입력: `_workspace/panels/` 디렉토리의 패널 파일들\n- 출력: `_workspace/review_report.md`\n- 형식:\n ```\n ## Panel {N}\n - 판정: PASS | FIX | REDO\n - 사유: [구체적 이유]\n - 수정 지시: [FIX/REDO인 경우 구체적 수정 방향]\n ```\n\n## 에러 핸들링\n- 파일 로드 실패 시 해당 패널을 REDO로 판정\n- 2회 재생성 후에도 REDO인 패널은 경고와 함께 PASS 처리\n\n## 협업 프로토콜\n- webtoon-artist에게 수정 지시 전달 (결과 파일 기반)\n- 재생성된 패널을 다시 검수 (최대 2회 루프)" + } + ], + "toolNames": [ + "view_file", + "write_to_file", + "replace_file_content", + "list_dir" + ], + "systemPromptConfig": { + "includeSections": [ + "user_information", + "skills", + "messaging", + "artifacts" + ] + } + } + } +} +``` + +### 에러 핸들링 + +``` +재시도 정책: +- REDO 판정 패널 → webtoon-artist에게 재생성 요청 (구체적 수정 지시 포함) +- 최대 2회 루프 후 강제 PASS +- 전체 패널의 50% 이상이 REDO면 사용자에게 프롬프트 수정 제안 +``` + +--- + +## 예시 4: 코드 리뷰 팀 (병렬 서브에이전트 모드) + +### 팀 아키텍처: 팬아웃/팬인 +### 실행 모드: 병렬 서브에이전트 + +``` +[메인] → invoke_subagent(security-reviewer): 보안 취약점 점검 + → invoke_subagent(performance-reviewer): 성능 영향 분석 + → invoke_subagent(test-reviewer): 테스트 커버리지 검증 + → 메인이 모든 결과 통합 +``` + +### 서브에이전트 구성 + +| 에이전트 TypeName | 역할 | 출력 | +|:---|:---|:---| +| `security-reviewer` | 보안 취약점 점검 | `_workspace/02_security.md` | +| `performance-reviewer` | 성능 영향 분석 | `_workspace/02_performance.md` | +| `test-reviewer` | 테스트 커버리지 검증 | `_workspace/02_test.md` | +| (메인) | 결과 종합 | `리뷰_종합보고서.md` | + +각 서브에이전트는 독립적으로 분석을 수행하고 결과를 파일에 저장한다. 메인이 모든 결과를 Read하여 통합 리뷰 보고서 생성. + +--- + +## 예시 5: 감독자 패턴 — 코드 마이그레이션 팀 (혼합 모드) + +### 팀 아키텍처: 감독자 +### 실행 모드: 순차 + 병렬 서브에이전트 혼합 + +``` +[메인/감독자] + 1. 파일 목록 분석 (직접 실행 — Grep/Glob) + 2. 배치 할당 (직접 실행 — 메인이 분할) + 3. invoke_subagent(migrator-1) (batch A) 병렬 + 4. invoke_subagent(migrator-2) (batch B) 병렬 + 5. invoke_subagent(migrator-3) (batch C) 병렬 + 6. 결과 수집 및 통합 (직접 실행) +``` + +### 서브에이전트 구성 + +| 단계 | 실행 주체 | 역할 | +|:---|:---|:---| +| 분석 | 메인 (직접) | 파일 목록 수집, 복잡도 추정 | +| 분배 | 메인 (직접) | 배치 분할 및 할당 | +| 마이그레이션 | migrator-1~3 (병렬) | 할당된 파일 배치 마이그레이션 | +| 통합 | 메인 (직접) | 통합 테스트 및 결과 보고 | + +### 감독자의 동적 분배 로직 + +``` +1. 메인이 전체 대상 파일 목록 수집 (Glob/Grep 도구) +2. 복잡도 추정 (파일 크기, import 수, 의존성) +3. 균등하게 배치 분할 +4. 각 배치를 migrator에게 병렬 위임 (invoke_subagent 호출) +5. 각 서브에이전트 완료 보고 대기 + - 성공 → 다음 단계 + - 실패 → 1회 재시도, 재실패 시 해당 배치 누락 명시 +6. 모든 작업 완료 → 메인이 통합 테스트 실행 +``` + +--- + +## 산출물 패턴 요약 + +### 플러그인 정의 파일 +위치: `.agents/plugins/{domain}-plugin/plugin.json` + +### 서브에이전트 정의 파일 +위치: `.agents/plugins/{domain}-plugin/agents/{agent-name}/agent.json` + +### 스킬 파일 구조 +위치: `.agents/plugins/{domain}-plugin/skills/{skill-name}/SKILL.md` + +### 통합 스킬 (오케스트레이터) +팀 전체를 조율하는 상위 스킬. 시나리오별 서브에이전트 구성과 워크플로우를 정의. +템플릿: `rules/orchestrator-template.md` 참조. +**실행 패턴을 반드시 명시** — 순차 서브에이전트(기본), 병렬 서브에이전트, 직접 실행, 하이브리드 중 선택. diff --git a/.agents/plugins/remuneration-plugin/agents/calculator-agent/agent.json b/.agents/plugins/remuneration-plugin/agents/calculator-agent/agent.json new file mode 100644 index 0000000..965f36c --- /dev/null +++ b/.agents/plugins/remuneration-plugin/agents/calculator-agent/agent.json @@ -0,0 +1,22 @@ +{ + "name": "calculator-agent", + "description": "Calculation engine agent that processes settlements, handles delta-checks/clawbacks, and triggers n8n workflows.", + "config": { + "customAgent": { + "toolNames": ["read_file", "write_file", "grep_search", "run_command"], + "systemPromptConfig": { + "includeSections": ["ROLES", "WORKSPACE"] + }, + "systemPromptSections": [ + { + "title": "Role & Objectives", + "content": "You are the Calculator Agent. Your objective is to execute settlements, check historical sales updates for retro clawbacks, and coordinate with n8n triggers." + }, + { + "title": "Instructions & Guardrails", + "content": "Enforce transaction idempotency constraints on all operations. For test runs, ensure calls target the /webhook-test endpoints to write strictly to the test database." + } + ] + } + } +} diff --git a/.agents/plugins/remuneration-plugin/agents/planner-agent/agent.json b/.agents/plugins/remuneration-plugin/agents/planner-agent/agent.json new file mode 100644 index 0000000..fa3a42c --- /dev/null +++ b/.agents/plugins/remuneration-plugin/agents/planner-agent/agent.json @@ -0,0 +1,22 @@ +{ + "name": "planner-agent", + "description": "Enterprise compensation planner that creates plans, version configurations, and maps goals.", + "config": { + "customAgent": { + "toolNames": ["read_file", "write_file", "grep_search", "list_dir"], + "systemPromptConfig": { + "includeSections": ["ROLES", "WORKSPACE"] + }, + "systemPromptSections": [ + { + "title": "Role & Objectives", + "content": "You are the Planner Agent. Your objective is to manage compensation plans, version-control rules, and goals setup. Enforce that active plan updates trigger new version entries in the database." + }, + { + "title": "Instructions & Guardrails", + "content": "Always keep plan schemas version-controlled. Do not update active rules in place. Ensure validation check attributes are structured in English." + } + ] + } + } +} diff --git a/.agents/plugins/remuneration-plugin/agents/qa-auditor-agent/agent.json b/.agents/plugins/remuneration-plugin/agents/qa-auditor-agent/agent.json new file mode 100644 index 0000000..c13058c --- /dev/null +++ b/.agents/plugins/remuneration-plugin/agents/qa-auditor-agent/agent.json @@ -0,0 +1,22 @@ +{ + "name": "qa-auditor-agent", + "description": "QA auditor that validates commission runs, checks row-level security boundaries, and verifies immutable audit logs.", + "config": { + "customAgent": { + "toolNames": ["read_file", "write_file", "grep_search", "run_command"], + "systemPromptConfig": { + "includeSections": ["ROLES", "WORKSPACE"] + }, + "systemPromptSections": [ + { + "title": "Role & Objectives", + "content": "You are the QA Auditor Agent. Your objective is to audit calculation outcomes, test RLS constraints, and verify logs redaction compliance." + }, + { + "title": "Instructions & Guardrails", + "content": "Verify that audit logs are never modified or deleted. Test boundaries (e.g. edge-case goals or negative amounts) to ensure the engine fails gracefully." + } + ] + } + } +} diff --git a/.agents/plugins/remuneration-plugin/plugin.json b/.agents/plugins/remuneration-plugin/plugin.json new file mode 100644 index 0000000..807e9e1 --- /dev/null +++ b/.agents/plugins/remuneration-plugin/plugin.json @@ -0,0 +1,5 @@ +{ + "name": "remuneration-plugin", + "version": "1.0.0", + "description": "Orchestrates the Variable Remuneration, Compensation, and Commissions multi-agent team for Hoteles Estelar." +} diff --git a/.agents/plugins/remuneration-plugin/skills/integration-validation/SKILL.md b/.agents/plugins/remuneration-plugin/skills/integration-validation/SKILL.md new file mode 100644 index 0000000..3924082 --- /dev/null +++ b/.agents/plugins/remuneration-plugin/skills/integration-validation/SKILL.md @@ -0,0 +1,12 @@ +--- +name: integration-validation +description: "Manages Excel imports validation and n8n webhook routing setups." +--- + +# Integration Validation + +Defines rules for importing sales results and routing n8n webhooks. + +## Execution Rules +1. **Webhook Branching**: In test environments, route webhook payloads strictly through the `/webhook-test` path to target the dev sandbox. +2. **Idempotence Checks**: Prevent double-upload actions by verifying idempotency keys. diff --git a/.agents/plugins/remuneration-plugin/skills/plan-management/SKILL.md b/.agents/plugins/remuneration-plugin/skills/plan-management/SKILL.md new file mode 100644 index 0000000..80adca1 --- /dev/null +++ b/.agents/plugins/remuneration-plugin/skills/plan-management/SKILL.md @@ -0,0 +1,12 @@ +--- +name: plan-management +description: "Handles compensation plan creation, versioning rules, and commercial goals parameters." +--- + +# Plan Management + +Defines rules for configuring plans, version controls, and quotas. + +## Execution Rules +1. **Never edit an active plan in-place**: Modifying active items must close the active plan and save changes as a new version. +2. **Assign goals by period**: Ensure monthly and quarterly targets are isolated per collaborator. diff --git a/.agents/plugins/remuneration-plugin/skills/reconciliation-auditing/SKILL.md b/.agents/plugins/remuneration-plugin/skills/reconciliation-auditing/SKILL.md new file mode 100644 index 0000000..79a6a06 --- /dev/null +++ b/.agents/plugins/remuneration-plugin/skills/reconciliation-auditing/SKILL.md @@ -0,0 +1,13 @@ +--- +name: reconciliation-auditing +description: "Checks row-level security boundaries, audits logs immutability, and reconciles PMS sales totals." +--- + +# Reconciliation & Auditing + +Defines rules for running data security checks and auditing logs. + +## Execution Rules +1. **RLS Verification**: Test database access filters using transaction user-context parameters. +2. **Audit Redactions**: Mask sensitive pricing or payroll outputs in logs. +3. **Log Immutability**: Ensure log rows are strictly append-only. diff --git a/.agents/plugins/remuneration-plugin/skills/remuneration-orchestrator/SKILL.md b/.agents/plugins/remuneration-plugin/skills/remuneration-orchestrator/SKILL.md new file mode 100644 index 0000000..c060f7b --- /dev/null +++ b/.agents/plugins/remuneration-plugin/skills/remuneration-orchestrator/SKILL.md @@ -0,0 +1,13 @@ +--- +name: remuneration-orchestrator +description: "Coordinates the Variable Remuneration, Compensation, and Commissions workflow across subagents." +--- + +# Remuneration Orchestrator + +Wires the multi-agent pipeline: Planner Agent -> Calculator Agent -> QA Auditor Agent. + +## Orchestration Flow +1. **Initiate**: `planner-agent` verifies plan setups and goals. +2. **Calculate**: `calculator-agent` executes calculations and runs delta adjustment clawbacks. +3. **Verify**: `qa-auditor-agent` reviews the calculation outputs and runs RLS/immutability validation tests. diff --git a/.agents/plugins/remuneration-plugin/skills/settlement-calculation/SKILL.md b/.agents/plugins/remuneration-plugin/skills/settlement-calculation/SKILL.md new file mode 100644 index 0000000..a9d0408 --- /dev/null +++ b/.agents/plugins/remuneration-plugin/skills/settlement-calculation/SKILL.md @@ -0,0 +1,12 @@ +--- +name: settlement-calculation +description: "Executes automated commission calculations and processes retroactive delta/clawback adjustments." +--- + +# Settlement Calculation + +Defines rules for running automated commission runs and retroactive audits. + +## Execution Rules +1. **Delta Checks**: Compare past closed calculations against PMS databases to generate adjustments (clawbacks). +2. **Idempotency keys**: Validate header tokens before saving settlement records. diff --git a/AGENTS.md b/AGENTS.md index fbb8be1..450b3b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ These instructions extend the baseline global `AGENTS.md` rules. When executing * Run `rtk npm run test` instead of `npm run test` * Run `rtk git status` instead of `git status` * Run `rtk prisma migrate dev` instead of `prisma migrate dev` +* You must only use the normal version of the program only after verifying the **`rtk`** version fails. --- @@ -34,3 +35,14 @@ These instructions extend the baseline global `AGENTS.md` rules. When executing ### 2.3. Prisma & PostgreSQL MCP Integration (`@prisma/mcp`) * **Schema Validation**: Introspect database structures and validate table states via MCP query tools prior to executing Next.js prisma schema updates. * **Type-Safety Checks**: Run dry-run checks on schemas after any migrations are applied. + +--- + +## 3. Harness: remuneration-plugin +* **Goal**: Orchestrates the multi-agent team (planner, calculator, qa-auditor) for the Variable Remuneration, Compensation, and Commissions system of Hoteles Estelar. +* **Trigger**: When requests relate to Variable Remuneration, Compensation, or Commission calculation or verification, utilize the `remuneration-orchestrator` skill to delegate tasks to subagents. +* **Changelog**: + | Date | Change | Target | Reason | + | :--- | :--- | :--- | :--- | + | 2026-06-11 | Initial scaffolding | All files | Initial team setup | +