# Harness > Scaffolds customized agent personas and standards-compliant skill directories based on user request or project type, and reviews/extends existing agent teams and skills. - Skill: `revfactory/harness-2` (Agent Skill) - Install (CLI): `npx skillmds@latest add revfactory/harness-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/revfactory/harness-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: revfactory (https://skillmd.com/u/revfactory) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/revfactory/harness-2 --- # Project Harness Scaffolder (/harness) 이 스킬은 사용자가 구축하고자 하는 어떠한 프로젝트 형태나 비전에 맞춰, 특화된 **에이전트 페르소나(Personas)**팀과 그들이 사용할 **공식 규격 커스텀 스킬(Skills)** 구조를 일괄 설계하고 프로젝트 폴더 하위에 스캐폴딩(자동 뼈대 생성)하거나, 이미 구축된 에이전트 및 스킬 전체 구성을 분석하여 필요 시 에이전트를 추가 구성하고 기존 구성을 완벽히 보완합니다. ## When to use this skill - 새로운 프로젝트를 시작할 때, 그에 특화된 다중 에이전트 협업 팀을 구축하고자 할 때. - 사용자가 "React 테스트 자동화 팀을 구성해줘" 혹은 "데이터 분석 파이프라인 전용 에이전트와 스킬들을 빌드해줘"라고 도메인별 요청을 할 때. - 기존에 구성된 에이전트 및 스킬 목록 전체를 분석하고 검토하여, 필요 시 새로운 에이전트를 추가 구성하거나 기존 에이전트의 강령(Persona)과 스킬들을 보완 및 리팩토링하고자 할 때. - 일일이 손으로 하부 폴더를 만들고 `SKILL.md`를 채워 넣는 반복 작업을 자동화하고 싶을 때. ## Instructions 이 스킬이 가동되면 에이전트는 아래 규칙에 맞춰 정교한 설계, 검토 및 파일 생성을 처리해야 합니다. > [!IMPORTANT] > **구현 계획서(Implementation Plan) 작성 생략**: > 하네스 스킬 작업 시에는 별도의 구현 계획서(implementation_plan.md) 작성을 요구하거나 대기하지 않고, 바로 도메인 분석과 아키텍처 설계를 완료한 뒤 곧바로 에이전트 및 스킬 구성을 즉시 실행(생성/업데이트)합니다. ### 1. 기존 에이전트 및 스킬 상태 진단 (Review Phase) - 프로젝트 루트에 이미 `AGENTS.md` 또는 `.agents/` 디렉토리가 존재하는 경우, 기존에 설계된 에이전트들의 역할, 담당 업무 및 등록된 커스텀 스킬 전체 구조를 정밀하게 분석합니다. ### 2. 사용자 요구사항 도출 및 격차 분석 (Gap Analysis) - 사용자의 도메인 요구사항과 기술 스택을 바탕으로 기존 팀 구성의 빈틈(Gap)을 파악합니다. - 이를 해결하기 위해 **추가로 구성해야 할 전문 에이전트 역할군**(예: 성능 모니터링, 보안 감사 등)이나 **기존 에이전트의 보완책**을 도출하고, 이들이 협업에서 활용할 **새로운 핵심 스킬 및 기존 스킬의 개선점**을 기획합니다. ### 3. 프로젝트 폴더 하위 스캐폴딩 및 점진적 업데이트 규칙 #### 1) 통합 에이전트 가이드라인 (`/AGENTS.md`) - 프로젝트 루트 디렉토리에 생성 또는 업데이트합니다. - 기존의 에이전트 정보 및 컨벤션을 최대한 보존하면서, 새롭게 보완/추가되는 에이전트의 역할 명세 및 업데이트된 협업 규칙을 누적 반영하여 업데이트합니다. - **[Change History]** 하네스 구성이 완료되거나 업데이트될 때마다 변경 일자, 구성 유형(신규/수정), 에이전트 팀 구성 난이도, 주요 변경 사항(추가/수정된 에이전트 및 스킬 목록)을 기록하는 **구성 변경 이력(Change History)** 섹션을 `AGENTS.md` 파일 하단에 누적하여 표(Table) 또는 목록 형태로 상세히 기술하도록 반영해야 합니다. #### 2) 개별 에이전트 상세 명세 (`.agents/agents/.md`) - `.agents/agents/` 디렉토리에 개별 마크다운 파일로 생성하거나 기존 파일을 업데이트합니다. - 상단에 YAML Frontmatter(`name`, `role`, `description`)를 포함하고 바디에 구체적인 행동 가이드를 작성합니다. #### 3) 개별 에이전트 실행 프로필 (`.agents/agents//agent.json`) - 각 에이전트 폴더에 `agent.json` 파일을 작성하여 에이전트의 런타임 지침과 권한을 기재합니다. - Antigravity CLI의 최신 플랫(Flat) JSON 스펙을 반드시 준수하여 선언합니다: ```json { "name": "에이전트 이름", "description": "에이전트 역할 설명", "system_prompt": "시스템 지침 및 협업 SOP 상세 기술", "enable_write_tools": true, // 쓰기 및 명령어 실행 도구 사용 여부 "enable_mcp_tools": true, // MCP 연동 도구 사용 여부 "enable_subagent_tools": false // 하위 에이전트 기동 도구 사용 여부 } ``` #### 4) 표준 규격 스킬들 (`.agents/skills//SKILL.md`) - 추가 및 보완되는 스킬 이름은 케밥 케이스(kebab-case)로 지정하고 개별 폴더를 생성/선택합니다. - 각 폴더 내에 반드시 **`SKILL.md`** 파일명으로 생성 또는 수정합니다. - 파일 상단에 필수 **YAML Frontmatter**를 채워 넣습니다: ```yaml --- name: description: <3인칭 시점의 기능 설명 및 트리거 조건 포함> allowed-tools: - <허용할 도구 1> - <허용할 도구 2> --- ``` - 바디에는 반드시 아래의 3대 필수 헤더를 포함시킵니다: - `## When to use this skill` (언제 호출해야 하는지 상황과 트리거 제시) - `## Instructions` (동작에 필요한 세부 프롬프트 지침) - `## Workflow` (에이전트가 실행해야 할 순차적 수행 절차) #### 5) 중간 결과물 및 산출물 보관용 작업 공간 (`_workspace/`) - 하네스로 빌드되는 모든 에이전트들이 태스크를 수행하면서 생성하는 모든 중간 소스코드, 분석 파일, 임시 산출물, 임시 데이터셋 및 실행 결과는 반드시 프로젝트 루트 하위에 **`_workspace/`** 폴더를 생성하고 그 하위에 기록을 남기도록 해야 합니다. - 이는 프로젝트의 핵심 소스 트리를 깨끗하게 보존하고, 에이전트가 생성하는 임시 산출물을 안전하게 격리/관리하기 위함입니다. 구성하는 모든 에이전트의 강령(Persona) 및 스킬들의 동작 정의 시 중간 결과물 경로가 항상 이 `_workspace/` 디렉토리를 향하도록 시스템 프롬프트와 지침을 강력하게 설계해야 합니다. --- ### 4. 에이전트 오케스트레이션 아키텍처 패턴 설계 가이드 도메인 복잡성과 태스크 요구에 부합하도록 에이전트 간의 관계를 설계할 때 아래 **6가지 핵심 오케스트레이션 아키텍처 패턴** 중 최적의 구성을 명시하고, 이를 `AGENTS.md`에 공식화 및 구조화해야 합니다: 1. **Pipeline (파이프라인)**: 순차적인 직렬 작업 흐름 (예: 스펙 정의 -> 코드 구현 -> 검증). 2. **Fan-out/Fan-in (분산 및 병렬 처리)**: 병렬로 독립적인 태스크를 처리한 후, 최종 취합하는 방식. 3. **Expert Pool (전문가 선택 풀)**: 당면한 태스크 유형에 따라 적합한 전문가 에이전트를 풀(Pool)에서 동적으로 선택. 4. **Producer-Reviewer (생성자 및 검토자)**: 생성 담당 에이전트와 이를 감사/테스트/보완하는 에이전트의 2단계 협업 구조. 5. **Supervisor (감독관)**: 중앙에서 마스터 에이전트가 실시간으로 하부 태스크를 동적 디스패치 및 통제. 6. **Hierarchical Delegation (계층적 위임)**: 복잡한 대규모 태스크를 하위 서브에이전트들에게 재귀적으로 쪼개어 위임. --- ### 5. Antigravity CLI 최적화 런타임 및 메시지 규격 (Runtime Collaboration Protocol) 에이전트들은 Antigravity CLI 런타임 상에서 단순히 정적으로 대기하지 않고, 고도화된 연동 도구 API 및 실시간 통신 규격 프로토콜을 사용하여 상호 협업해야 합니다. #### 1) 런타임 에이전트 라이프사이클 관리 - **서브에이전트 등록 (`define_subagent`)**: 에이전트가 런타임 중에 필요한 전문 자아(Name, Description, System Prompt 및 도구 권한 플래그)를 동적으로 등록합니다. *세션이 시작되거나 프로젝트가 로드될 때, 기존 `.agents/agents/{agent_name}/agent.json` 파일에 정의된 에이전트 프로필을 로딩하여 `define_subagent` 도구를 통해 세션 런타임에 선제적으로 일괄 등록해 줍니다.* - **서브에이전트 기동 (`invoke_subagent`)**: 실시간 병렬 태스크 실행이 필요한 경우 `invoke_subagent`를 통해 에이전트를 백그라운드에서 실행하고 반환되는 고유의 **Conversation ID**를 획득하여 태스크 실행 흐름을 지휘합니다. #### 2) Antigravity CLI 표준 메시징 프로토콜 `send_message` 툴을 사용해 격리된 에이전트 간의 컨텍스트를 동기화하고 의사를 전달할 때는, 파싱 및 후속 작업 자동화를 위해 **JSON 구조가 래핑된 표준 메시지 규격**을 사용하여 교신하도록 에이전트 시스템 프롬프트에 내재화합니다. *메시지 페이로드 포맷(JSON) 규격:* ```json { "sender": "송신 에이전트명", "action": "액션 유형 (REQUEST_REVIEW | TASK_COMPLETE | REFACTOR_REQUEST | STATUS_UPDATE)", "target_artifact": "작업 중인 대상 파일 경로 (절대 경로)", "content": "상세 텍스트 설명 및 요청 사항", "metadata": { "task_id": "작업 식별용 ID", "status": "현재 상태 값", "additional_context": "기타 참고 데이터" } } ``` 에이전트들은 `send_message` 호출 시 이 JSON을 문자열 형태로 텍스트 바디에 삽입하여 송신해야 하며, 이를 수신한 서브에이전트는 JSON 데이터를 우선 파싱하여 목표물과 요청 사양을 정확히 식별하고 도구 작업에 임하도록 설계되어야 합니다. #### 3) 오케스트레이터 스킬과의 유기적 연동 메인 에이전트에게 장착된 오케스트레이터 스킬은 전체 서브에이전트들을 기동(`invoke_subagent`), 대기, 결과 수합 및 통신 조율을 관리해야 하며, 각 서브에이전트가 돌려주는 JSON 형식의 표준 메시지 페이로드를 해석하여 후속 단계 에이전트 기동이나 피드백 전달 등을 효율적으로 오케스트레이션합니다. --- ### 6. 사용자 수련도(Skill Level)별 차등 구성 지침 사용자의 요청 사항 및 수준(수련도)을 분석하여 하네스 에이전트 팀 구성의 난이도와 구조적 복잡성을 다음과 같이 3단계로 차등화하여 설계합니다. - **초급 (Beginner)**: - **목적**: 직관적인 이해와 단순성 극대화. - **아키텍처**: 단순 파이프라인(Pipeline) 또는 1~2개의 에이전트로 구성된 단순 생성자-검토자(Producer-Reviewer) 패턴을 선택합니다. - **스킬 구성**: 복잡한 비동기나 분기 제어가 없는, 핵심 동작 위주의 쉽고 명료한 1~2개 단위 스킬로 구성합니다. - **오케스트레이션**: 중앙 메인 에이전트가 단선적으로 하위 에이전트를 차례로 구동하여 피드백을 사용자에게 보여주는 형태이며 복잡한 병렬/비동기 흐름은 생략합니다. - **중급 (Intermediate)**: - **목적**: 기능의 모듈화와 효율적인 자동 협업. - **아키텍처**: 전문가 풀(Expert Pool) 또는 파이프라인 + 생성자-검토자의 복합형 아키텍처를 적용하며, 2~3개의 개별 정문화된 에이전트를 배치합니다. - **스킬 구성**: 독립성과 재사용성이 높은 기능별 모듈 스킬로 분리하여 설계합니다. - **오케스트레이션**: 명확한 메시징 프로토콜을 사용한 세미 오토메이티드 협업 구조를 갖추고, 에이전트 간 순차적 피드백과 예외 상황 처리를 가이드합니다. - **고급 (Advanced/Expert)**: - **목적**: 극대화된 자동화, 고도의 예외 복구, 병렬 처리 및 자율성. - **아키텍처**: 계층적 위임(Hierarchical Delegation) 또는 감독관(Supervisor) 패턴 등 복잡한 하이브리드 아키텍처를 설계하며, 3개 이상의 고도로 분화된 전문 에이전트를 구성합니다. - **스킬 구성**: 고성능 자율 실행, 다이나믹 상태 관리, 병렬 실행 복구 능력(Recovery Strategy)을 갖춘 고급 스킬로 채워넣습니다. - **오케스트레이션**: 메인 에이전트가 백그라운드로 여러 서브 에이전트를 동시에 기동(Fan-out/Fan-in)하고, 동적 `define_subagent` 기동 및 JSON 규격 통신을 활용한 완전 자율적 상호 피드백 루프를 구축하여 에러 및 충돌 복구 전략을 오케스트레이터 스킬에 깊이 내재화합니다. --- ## Workflow 사용자가 하네스 스킬로 작업을 요청하면, 에이전트는 **반드시** 아래의 6단계 순서에 따라 작업을 정밀하게 진행해야 합니다: ### Step 1. 사용자 요청 도메인 분석 (Domain Analysis) - 사용자의 목표 시스템 및 도메인 요구사항과 기술 스택을 완벽히 분석합니다. - 사용자 요청 문맥을 토대로 사용자의 수련도(초급/중급/고급)를 판별하여 적용할 에이전트 팀 및 스킬 구성의 난이도를 설정합니다. ### Step 2. 에이전트 팀 아키텍처 설계 (Architecture Design) - 결정된 난이도(수련도)에 부합하는 최적의 오케스트레이션 아키텍처 패턴을 설계합니다. - 에이전트 간의 관계, 데이터 흐름, 호출 순서를 사용자가 직관적으로 이해할 수 있도록 `AGENTS.md`에 명확히 기술하여 설계안을 구조화합니다. ### Step 3. 에이전트 구성 (Agent Configuration) - 아키텍처 설계에 정의된 전문 에이전트들의 마크다운 파일(`.agents/agents/.md`) 및 Antigravity flat 규격을 준수한 `agent.json` 프로필 파일을 구성합니다. - 프로젝트 루트 디렉토리에 전체 에이전트 가이드라인인 `AGENTS.md`를 신규 생성하거나 기존 컨벤션을 깨뜨리지 않으면서 점진적으로 업데이트합니다. 이 과정에서 **오케스트레이터 스킬(orchestrator)을 가동하여 사용자가 내린 작업 명령(예: 하네스 자동 기획 및 기술 연구)을 실질적으로 실행하고 처리하는 구체적인 구동 지침 및 사용자 대화형 조작 매뉴얼에 관한 설명 섹션을 반드시 추가**해야 합니다. ### Step 4. 에이전트들이 사용할 스킬 구성 (Skill Configuration) - 각 에이전트가 업무 수행 시 직접 탑재하고 동작할 커스텀 스킬 목록을 확정합니다. - `.agents/skills//SKILL.md` 디렉토리 하위에 표준 규격(Frontmatter 및 When to use, Instructions, Workflow 3대 헤더)을 엄격히 준수한 스킬 파일들을 생성하거나 기존 구조를 정밀 리팩토링합니다. ### Step 5. 오케스트레이터 스킬 구성 (Orchestrator Skill Configuration) - 에이전트들이 유기적이고 효과적으로 상호작용하며 자동화 루프를 돌 수 있도록 **Antigravity CLI 메인 에이전트**에게 장착할 **오케스트레이터 스킬**을 전용으로 구성합니다. - `.agents/skills/orchestrator/SKILL.md` 경로에 오케스트레이터 스킬 파일을 생성하고, 메인 에이전트가 서브 에이전트들을 기동(`invoke_subagent`), 통제 및 메시지(`send_message`) 처리하여 협업 루프를 지휘하고 실패 시 대응하는 구체적인 SOP와 프롬프트 지침을 구현합니다. 이 과정에서 **현재 해당 하네스 시스템에 배포되고 연동된 전체 서브 에이전트 명세(이름, 역할)와 개별 에이전트들이 소유한 커스텀 스킬(이름, 자동화 임무)에 대한 상세한 기술적 설명 명세 목록을 오케스트레이터 스킬 본문에 명시적으로 삽입**해야 합니다. ### Step 6. 하네스 구성 검토 및 테스트 (Review & Test) - 생성 또는 업데이트된 하네스 구조(에이전트 프로필, 스킬 마크다운)가 Antigravity 표준 규격에 맞게 적재되었는지 최종 점검합니다. - **[CRITICAL] 에이전트 즉시 등록**: 하네스 스킬 수행 에이전트는 구성 완료 단계에서 반드시 생성된 모든 에이전트의 프로필(`.agents/agents/{agent_name}/agent.json`) 파일을 직접 읽고 파싱하여, **`define_subagent` 도구를 실제로 호출해서 현재 대화 세션 런타임에 에이전트들을 실질적으로 즉시 등록**해야 합니다. (에이전트 등록 누락 방지) - `invoke_subagent` 및 `send_message`를 가상으로 작동시켜 에이전트 간의 자율적 통신 및 오케스트레이터 스킬의 협업 시나리오가 에러 없이 잘 매끄럽게 흐르는지 철저히 테스트하고 검증합니다. - 모든 테스트와 작업이 완료되면, 에이전트 및 스킬 구조 트리 맵(Tree Map)을 시각적으로 콘솔에 출력하고, **사용자가 이번에 구축된 에이전트 팀과 스킬들을 신속히 인지할 수 있도록 리뷰를 위한 정보를 군더더기 없이 짧고 명료하게 작성하여 제시**해야 합니다. 이 과정에서 **새롭게 구축된 각 커스텀 스킬들의 고유 '스킬명(kebab-case)'과 이들이 담당하는 명확한 기술적 역할, 핵심 기능(예: 어떤 일을 자동화하는지 1줄 핵심 요약)에 대한 세부 설명을 누락 없이 명시하여 제공**해야 합니다. (단순히 파일 경로(SKILL.md)를 그대로 노출하여 설명하는 대신, 사용자가 인지하기 쉽도록 공식 스킬명을 확실하게 보여주어야 합니다) - 마지막으로, **사용자가 리뷰 후 이상이 없을 시 현재 구축된 하네스를 실제로 가동할 수 있도록, 터미널 셸 명령어 대신 Antigravity CLI 대화창 안에서 간단한 자연어 프롬프트(예: "하네스 기획 협업을 시작해줘", "하네스 연구 보고서와 교육 과정을 구축해줘" 등 직관적인 대화 시나리오)로 작업을 지시하고 제어하는 구체적인 대화 예시를 최종 활용 가이드 안내 문구에 반드시 포함**하여 마무리합니다.