| name | gemini-harness-builder |
| description | Gemini-Harness 프로젝트(revfactory/harness v1.2.0의 LangGraph+Gemini 포트)의 설계·구현·통합·검증을 전문가 팀으로 수행하는 오케스트레이터. LangGraph 런타임 작성(harness_runtime.py), workflow.json 스키마 설계, Gemini CLI(v0.28.0+) 통합, gemini-3.1-pro-preview API 래핑, 메타 에이전트/스킬 템플릿 설계, 6 아키텍처 패턴 포트, self-critique 루프 구현, 통합 QA 등 본 프로젝트 관련 작업에 반드시 이 스킬을 사용. 후속 작업(다시 실행, 부분 수정, 재검증, workflow.json 스키마만 수정, 특정 에이전트만 재호출, 이전 결과 개선, 업데이트, 보완, 원본 하네스 재동기화)에도 이 스킬을 사용. 단순 개념 질문(LangGraph란?)은 제외. |
Gemini-Harness Builder Orchestrator
revfactory/harness v1.2.0 → Gemini + LangGraph 포트를 전문가 팀으로 개발한다.
5명의 팀: harness-architect · langgraph-developer · gemini-integrator · meta-skill-designer · harness-qa
포트 원칙: 원본 구조·출력·철학 보존, 런타임만 교체. 상세는 harness-port-spec 스킬 필수 참조.
모든 Agent/TeamCreate 호출 시 model: "opus" 파라미터를 명시하라.
실행 모드: 하이브리드
- Phase 1~3: 에이전트 팀 (TeamCreate) — 설계·구현 단계는 교차 의견과 실시간 조율이 중요
- Phase 4 (QA): 서브 에이전트 (Agent 직접 호출) — 독립적 검증, 객관성 확보
Phase 0: 컨텍스트 확인
작업 시작 전 기존 산출물 상태 파악:
_workspace/ 디렉토리 존재 여부 확인- 이전 산출물 스캔:
harness_runtime.py, .agents/, _workspace/adr/, _workspace/schema/
- 사용자 요청 분류:
| 상황 | 판정 | 행동 |
|---|
_workspace/ 없음, 첫 구축 요청 | 초기 실행 | Phase 1부터 전체 |
_workspace/ 있음, 특정 영역 수정 요청 | 부분 재실행 | 해당 에이전트만 재호출, 영향 분석 |
_workspace/ 있음, 새 요구사항 | 전면 재실행 | 기존 _workspace/ → _workspace_prev/ 이동 후 Phase 1 |
| 기존 산출물 검증 요청 | QA 전용 | Phase 4만 실행 |
- 사용자에게 판정 결과와 실행 계획 한 줄 보고. 모호하면 확인 질문.
Phase 1: 원본 스펙 내재화 및 설계 계약
실행 모드: 에이전트 팀
TeamCreate(team_name="design-team", members=["harness-architect", "meta-skill-designer"])
작업 순서:
1-0. 원본 스펙 Read (필수, 생략 금지):
팀원 모두 harness-port-spec 스킬을 로드하고, 그 지시에 따라 로컬 캐시 원본을 Read:
~/.claude/plugins/cache/harness-marketplace/harness/1.2.0/skills/harness/SKILL.md (전체 워크플로우).../references/agent-design-patterns.md (6 패턴).../references/orchestrator-template.md (3 템플릿).../references/team-examples.md (실제 예시)- 기타 references는 필요 시 조건부 로드
harness-architect는 원본과 포트의 차이를 유발하는 결정을 식별하고 그 목록을 작성(어느 Claude Code 원시형이 LangGraph 어떤 구조로 매핑되는가).
1-1. 요구사항 정리: harness-architect가 ADR로 → _workspace/adr/0001-*.md. ADR마다 원본의 어느 섹션에 대응하는지 명시(예: source: references/agent-design-patterns.md §1-6).
1-2. 스키마 교차 검토: harness-architect ↔ meta-skill-designer가 SendMessage로 workflow.json v1 스키마와 메타 템플릿 스키마 합의. 6 패턴을 모두 표현 가능한지 검증.
산출물:
_workspace/adr/ — 포트 결정 (원본 섹션 참조 필수)_workspace/schema/workflow.v1.json — 6 패턴 모두 표현 가능_workspace/schema/system_prompt.schema.json, skill.schema.json_workspace/port-mapping.md — Claude Code 원시형 → LangGraph 대응 매핑표
체크포인트: 사용자에게 ADR 제목 리스트 + 스키마 핵심 필드 요약을 보여주고 승인받기. 승인 없이 Phase 2 진입 금지.
Phase 2: 통합 계약 정의
실행 모드: 에이전트 팀 (gemini-integrator 추가)
TaskCreate: gemini-integrator에 할당
- Gemini CLI v0.28.0+ 내장 스킬 API 조사 (context7 MCP로 최신 문서)
- gemini-3.1-pro-preview Python SDK 시그니처 확인
- MCP Server 통신 프로토콜 정리
harness-architect + gemini-integrator가 LangGraph 노드 ↔ Gemini 호출의 인터페이스 계약 합의.
산출물:
_workspace/guide/gemini_integration.md — API 래퍼 인터페이스 명세_workspace/guide/mcp_tools.md — MCP 도구 입출력 스키마
Phase 3: 구현
실행 모드: 에이전트 팀 (팀 재구성)
이전 팀 해체 → 새 팀 생성:
TeamDelete("design-team")
TeamCreate(team_name="impl-team", members=["langgraph-developer", "gemini-integrator", "meta-skill-designer"])
TaskCreate로 병렬 작업 분배:
| 담당 | 작업 |
|---|
| langgraph-developer | runtime/compat.py(LangGraph 어댑터), runtime/state.py, runtime/manager.py, runtime/worker.py, runtime/patterns/{6개}.py, runtime/harness_runtime.py, self-critique 라우팅 |
| gemini-integrator | integrations/gemini_client.py, integrations/cli_bridge.py, integrations/mcp_adapter.py, mcp_server.py, cli.py, pyproject.toml, extension/manifest.json |
| meta-skill-designer | meta/templates/, meta/schemas/, meta/linter.py, meta/examples/ |
각 팀원 공통 요구:
- 최신 LangGraph API 확인: 구현 착수 전 context7 MCP로
langgraph 조회
- 코드에서
from langgraph ... 직접 import는 runtime/compat.py 한 곳만 허용
- 스모크 테스트 포함, SendMessage로 인터페이스 질의·합의 자체 조율
설치형 패키지 산출물 (gemini-integrator):
pyproject.toml — LangGraph 범위 핀 (>=X.Y,<next-major), 스크립트 진입점 (gemini-harness, gemini-harness-mcp)extension/manifest.json — Gemini CLI 익스텐션 매니페스트 (한/영/일 트리거 포함)- MCP 서버 —
harness.audit/build/verify/evolve/run 5개 도구
- 상세 사양:
gemini-cli-extension-packaging 스킬
Phase 4: 통합 QA 및 Self-Critique 측정
실행 모드: 서브 에이전트 (harness-qa 단독)
Agent(subagent_type="general-purpose", model="opus", ...)
harness-qa 작업:
- 경계면 교차 비교 (필수):
- workflow.json 실제 파일 ↔ 런타임 파서 (필드 매칭)
- Gemini API 응답 shape ↔
gemini_client.py 파싱
- 생성된 SYSTEM_PROMPT.md ↔
meta_linter.py 검증 항목
- 원본 동등성 검증 (포트 특화):
harness-port-spec 스킬의 "동등성 검증 시나리오" 섹션의 5개 시나리오를 실행- 각 시나리오에서 기대 패턴(Fan-out/Fan-in, Producer-Reviewer, Supervisor 등)이 실제로 생성되는지 확인
- 원본 하네스와 같은 입력으로 비교 실행하여 팀 분해의 유사성 평가
- End-to-end 실행: PRD 예시 입력("복잡한 Next.js 프로젝트 아키텍처를 짜줘")으로 실행,
.gemini/context.md 실시간 업데이트 확인
- Self-critique A/B 측정 (기본 5개 입력 × 모드 A/B × 3회):
- A (baseline): self-critique 비활성
- B (treatment): self-critique 활성
- 측정: 결함 수, p95 지연, 토큰 비용
- 목표:
(mean(A.defects) - mean(B.defects)) / mean(A.defects) >= 0.8
- 리포트:
_workspace/qa/report-{date}.md + _workspace/qa/metrics/self_critique.csv + _workspace/qa/equivalence.md (원본 동등성)
Phase 5: 수정 루프 (조건부)
QA 실패 시:
- 실패 유형 → 책임 에이전트 식별 (QA 리포트에 명시)
- 해당 에이전트만 서브 에이전트로 호출하여 수정 (팀 재구성 불필요)
- 수정 후 Phase 4 재실행
- 최대 3회 루프, 이후 사용자 에스컬레이션 (
_workspace/qa/escalations/)
데이터 전달 프로토콜
| 전략 | 적용 | 용도 |
|---|
| SendMessage | 팀 모드 | 인터페이스 합의, 질의응답, 실시간 조율 |
| TaskCreate | 팀 모드 | 병렬 작업 분배 (Phase 2, 3) |
파일 기반 (_workspace/) | 전체 | 모든 지속적 산출물 |
| 반환값 | 서브 모드 | Phase 4 QA 결과 메인으로 수집 |
파일명 컨벤션:
_workspace/adr/{NNNN}-{topic}.md_workspace/schema/{name}.v{N}.json_workspace/guide/{feature}.md_workspace/qa/report-{YYYY-MM-DD}.md_workspace/qa/failures/{id}.json_workspace/metrics/calls.jsonl
_workspace/는 보존(사후 감사용), 최종 산출물만 프로젝트 루트 또는 지정 경로에 출력.
에러 핸들링
- 에이전트 실행 실패: 1회 재시도. 재실패 시 해당 산출물 없이 진행, 최종 리포트에 누락 명시.
- Gemini CLI 버전 불일치: gemini-integrator가 경고, 사용자에게
gemini --version >= 0.28.0 업그레이드 권고.
- context7 MCP 문서 조회 실패: 기존 지식으로 진행하되 "최신 검증 필요" 태그, ADR에 기록.
- 팀원 간 의견 충돌: harness-architect가 중재, 결정 사유를 ADR에 기록.
- QA 루프 3회 실패: 사용자에게 전체 로그 대신 핵심 3줄 요약 + 선택지(재시도/수용/수동개입) 제공.
팀 크기
5명 — 중규모 작업 기준에 적합. Phase별 활성 팀원은 2~3명으로 유지(design-team 2, impl-team 3). 조율 오버헤드 최소화.
테스트 시나리오
시나리오 1 (정상 흐름, 초기 실행)
- 입력: "Gemini-Harness 초기 버전을 구현해줘. PRD는 CLAUDE.md 참조"
- 기대: Phase 0 → 초기 실행 판정 → Phase 1~4 순차 →
harness_runtime.py, .agents/ 템플릿, QA 리포트 생성, 80% 결함 감소 측정치 기록.
시나리오 2 (부분 재실행)
- 입력: "workflow.json 스키마에 retry_limit 필드를 추가해줘"
- 기대: Phase 0 → 부분 재실행 판정 → harness-architect + meta-skill-designer만 재호출 → langgraph-developer에게 파서 영향 알림 → 필요 시 파서 수정 → QA 재실행(스키마 관련 테스트만).
시나리오 3 (QA 실패 → 수정 루프)
- 입력: 시나리오 1 실행 중
meta_linter.py가 필수 필드 누락을 감지하지 못함
- 기대: QA 리포트에 재현 스텝 명시 → meta-skill-designer 서브로 호출, 린터 수정 → Phase 4 재실행 → 통과 후 완료.
참고
- 프로젝트 개요·레이아웃:
CLAUDE.md
- 에이전트 정의:
.claude/agents/
- 포트 원본 스펙 (필독):
harness-port-spec 스킬
- 핵심 아키텍처:
langgraph-patterns 스킬 (Manager+Worker+Registry, 6 패턴, 버전 호환)
- 지원 스킬:
gemini-cli-integration(런타임), gemini-cli-extension-packaging(설치·배포), meta-agent-templates, self-critique-verification
- 원본 캐시:
~/.claude/plugins/cache/harness-marketplace/harness/1.2.0/skills/harness/
