메뉴
Self-critique 루프의 설계·구현·정량 측정. LangGraph conditional edge 기반 구조적 루프, retry counter, diff 평가, A/B 실험으로 결함 감소율 측정. PRD의 80% 결함 감소 acceptance criteria 검증, self-correction 루프 설계, near-miss 트리거 테스트 시 필수.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | self-critique-verification |
| description | Self-critique 루프의 설계·구현·정량 측정. LangGraph conditional edge 기반 구조적 루프, retry counter, diff 평가, A/B 실험으로 결함 감소율 측정. PRD의 80% 결함 감소 acceptance criteria 검증, self-correction 루프 설계, near-miss 트리거 테스트 시 필수. |
Gemini-Harness의 핵심 차별점은 구조적 self-critique 루프다. 이 스킬은 그 루프의 설계·구현·측정 방법론을 정의한다.
나쁜 자가 교정: "코드를 열심히 리뷰하고 버그를 찾아라" 프롬프트 지시만.
좋은 자가 교정: LangGraph 그래프에서 generate → test → route 사이클을 반드시 거치게 하고, test 실패 시 fix 노드로 자동 분기.
이유: 프롬프트는 모델이 무시할 수 있지만, 그래프 토폴로지는 회피 불가능.
entry → generate → test_runner ─PASS─→ END
│
└─FAIL─→ fix_agent → generate (retry++)
│
└─(retry >= limit)─→ escalate
LangGraph 구현 상세는 langgraph-patterns 스킬의 "Self-Critique 조건부 루프" 참조.
실패를 구체적으로 반환해야 fix가 가능하다. "test failed" 한 줄은 쓸모없다.
def test_runner_node(state: HarnessState) -> dict:
result = run_tests(state["artifacts"])
return {
"test_passed": result.success,
"test_output": result.output,
"failed_assertions": [
{"file": f.file, "line": f.line, "expected": f.expected, "actual": f.actual, "message": f.message}
for f in result.failures
],
"coverage": result.coverage,
}
fix 프롬프트에 포함해야 할 것 (하나라도 빠지면 품질 저하):
class HarnessState(TypedDict):
retry_count: int
retry_limit: int
retry_history: Annotated[list[dict], add] # 각 시도의 test_output, diff 요약
router에서 retry_count >= retry_limit 체크 → escalate.
def improved(prev: dict, curr: dict) -> bool:
return len(curr["failed_assertions"]) < len(prev["failed_assertions"])
def critique_router(state: HarnessState) -> str:
if state["retry_count"] >= state["retry_limit"]:
return "escalate"
if state["test_passed"]:
return "END"
# 개선 없이 2회 연속 → 루프 무의미
history = state["retry_history"]
if len(history) >= 2 and not improved(history[-2], history[-1]):
return "escalate"
return "fix_agent"
같은 입력 세트를 두 모드로 실행:
| 모드 | 그래프 구조 | 비교 기준점 |
|---|---|---|
| A (baseline) | generate → END | self-critique 없음 |
| B (treatment) | generate → test → [fix → generate]* → END | self-critique 활성 |
지표:
defects — 생성 산출물의 결함 수 (자동 판정 — 아래 섹션)latency_s — end-to-end 지연tokens_in / tokens_out — 누적 토큰 (_workspace/metrics/calls.jsonl에서 집계)수동 카운트는 느리고 편향된다. 자동 체크:
| 산출물 유형 | 판정 도구 |
|---|---|
| Python 코드 | ruff check + mypy + pytest의 실패 수 |
| workflow.json | meta_linter.py 실패 수 |
| SYSTEM_PROMPT.md / SKILL.md | meta_linter.py 실패 수 |
| 설계 문서 (Markdown) | 링크 유효성, 필수 섹션 존재, 스펠체크 |
_workspace/qa/metrics/self_critique.csv:
run_id,mode,input_id,defects,latency_s,tokens_in,tokens_out,loops
run_001,A,next-js-arch,12,45,23000,5200,0
run_001,B,next-js-arch,2,180,89000,18400,2
run_001,A,fastapi-backend,8,38,19000,4800,0
run_001,B,fastapi-backend,1,155,76000,16200,2
...
PRD Acceptance Criteria 기반 5~10개 (다양한 도메인):
각 입력 × 모드 × 3회 반복 (분산 확인). 단일 샘플은 Gemini stochastic 때문에 신뢰 불가.
def acceptance_passed(df: pd.DataFrame) -> bool:
a = df[df["mode"] == "A"]["defects"].mean()
b = df[df["mode"] == "B"]["defects"].mean()
if a == 0:
return True # baseline 결함 없음 (드문 경우)
reduction = (a - b) / a
return reduction >= 0.8
| 안티패턴 | 문제 | 대안 |
|---|---|---|
| Fix가 원본 요구사항을 잊음 | 테스트 통과만 목표 → 쓰레기 코드 | 매 fix 호출에 원본 spec 포함 |
| Test가 실패 사유 불명확 | Fix가 추측으로 수정 → 악순환 | failed_assertions에 구조화 리턴 |
| retry 상한 없음 | 무한 루프, 비용 폭발 | retry_count + conditional edge |
| 개선 감지 없음 | 같은 실수 반복 | diff 평가, 정체 시 escalate |
| Self-critique 교훈 미보존 | run 간 학습 없음 | _workspace/qa/lessons.md에 요약 누적 |
| A/B 측정 없이 "좋아진 것 같다" | 진짜 개선 여부 불명 | 자동 판정 도구 + 리포트 |
gemini-harness-builder의 description이 의도한 상황에만 트리거되는지 검증.
경계가 모호한 near-miss가 좋은 테스트 케이스다. "피보나치 구현" 같은 명백 무관 쿼리는 테스트 가치 낮음.
3회 실패 또는 정체 감지 시:
_workspace/qa/escalations/{run_id}.md에 사유·이력 기록 (입력, 각 시도의 test_output diff, 최종 상태)단일 Gemini 호출은 확률적이다. 1M 컨텍스트와 강력한 추론도 검증 없이는 신뢰할 수 없다.
PRD의 80% 감소 목표는 $p \approx 0.45$ 기준 루프 1회로 달성 가능하나, 실측으로 검증 필수. A/B 결과가 목표 미달이면 Test Runner 또는 Fix Agent를 튜닝.
Gemini-Harness를 Gemini CLI v0.28.0+ 사용자 환경에 설치 가능한 Python 패키지로 배포하는 방법. pyproject.toml 구조, 익스텐션 매니페스트, MCP 서버와 슬래시/트리거 명령 병행 제공, LangGraph 버전 호환 핀 전략, 진입점, 사용자 설치·업그레이드·제거 흐름, CI 배포. 배포 아티팩트 작성, 설치 경험 설계, LangGraph 업데이트 대비 의존성 관리 시 반드시 참조.
Gemini CLI(v0.28.0+) 내장 스킬과 gemini-3.1-pro-preview Python SDK, MCP Server를 LangGraph 노드에서 호출하는 패턴. subprocess 브리지, API 래퍼, MCP 어댑터, 타임아웃·재시도·command injection 차단. Gemini 관련 통합 코드 작성·디버깅 시 반드시 참조.
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란?)은 제외.
revfactory/harness v1.2.0을 Gemini + LangGraph 스택으로 포팅할 때 보존해야 할 사양과 원시형 매핑. Claude Code 원시형(TeamCreate/SendMessage/TaskCreate/Agent)과 LangGraph 구현의 대응, 6개 아키텍처 패턴의 LangGraph 변환 힌트, 출력 포맷(`.agents/`, workflow.json) 명세. 포팅 결정·원본 스펙 확인·구현 일관성 검토 시 반드시 참조. "원본과 동등한가" 검증 기준 포함.
Gemini-Harness의 핵심 아키텍처 패턴. **Manager + Worker + Registry (Swarm-style)** — 정적 그래프 위에서 State의 agent registry로 런타임 동적 에이전트를 표현하고, 단일 Worker(dispatcher) 노드가 registry 엔트리를 선택 실행한다. Command/Send API, 에이전트 간 통신(inbox), 6 아키텍처 패턴 구현, self-critique 루프, LangGraph 버전 호환 어댑터. harness_runtime.py 설계·구현 시 반드시 참조.
Gemini-Harness 런타임이 동적 생성하는 SYSTEM_PROMPT.md와 SKILL.md의 템플릿·JSON Schema·linter 규칙. workflow.json 스키마 v1 정의, 필수/선택 필드, 금지 패턴, 버전 마이그레이션 전략. 메타 레벨 생성물 형식·검증 작업 시 반드시 참조.