Harness Designer v4은(는) 무엇을 하나요?
원칙: "에이전트에게 지도를 줘라, 1000페이지 매뉴얼 말고." — OpenAI Harness Engineering 원칙: "생성자가 자기 작업을 평가하게 하지 마라." — Anthropic GAN-Inspired Harness
하네스 설계 5대 기둥
이 스킬이 생성하는 모든 워크스페이스는 다음 5가지 기둥을 충족해야 한다:
| 기둥 | 핵심 질문 | 원칙 |
|---|---|---|
| Progressive Disclosure | 에이전트가 필요한 것만 볼 수 있는가? | 목차(~100줄) → 포인터 → 깊은 문서 |
| Mechanical Enforcement | 규칙이 기계적으로 강제되는가? | 문서화만으로는 일관성 유지 불가 |
| Feedback Loop | 실패 시 구조적 개선이 가능한가? | "더 열심히"가 아닌 "어떤 능력이 빠졌는가" |
| Session Continuity | 세션 간 핸드오프가 깨끗한가? | progress + feature-status + git |
| Entropy Management | 시간이 지나도 구조가 유지되는가? | 주기적 정리, 문서 신선도 검증 |
두 레이어의 관계
┌─────────────────────────────────────────────────────┐
│ LAYER 1: 메타 (이 스킬의 역할) │
│ │
│ Planner ──→ Generator ──→ Evaluator │
│ ↑ (단방향 순차, 역참조 금지) │
│ └──── 미흡 시 피드백 ──────────────────────┘ │
│ │
│ 목적: 워크스페이스 구조 자체를 설계·생성·검증 │
└─────────────────────────┬───────────────────────────┘
│ 승인 후 구조 완성
▼
┌─────────────────────────────────────────────────────┐
│ LAYER 2: 운영 (완성된 워크스페이스의 역할) │
│ │
│ ┌ Initializer (첫 실행 전용) ─→ 환경 설정 │
│ │ │
│ └ Operating Agent (반복 실행): │
│ Agent-A ─┐ │
│ Agent-B ─┼──→ Chairman 종합 ──→ 최종 산출물 │
│ Agent-C ─┘ (독립 병렬, 서로 교류 없음) │
│ │
│ 목적: 실제 업무 수행 (분석, 의사결정, 보고서 등) │
└─────────────────────────────────────────────────────┘
LAYER 1: 메타 — 하네스 설계 프로세스
L1 에이전트 3종 (단방향 순차, 역참조 금지)
Planner → Generator → Evaluator 순으로 산출물이 전달된다. 각 에이전트는 이전 단계의 산출물만 받고, 다음 단계 결과를 미리 보지 않는다.
Planner (기획 에이전트)
사용자 의도를 분석해서 하네스 구조를 설계한다.
- 인풋: 사용자 요구사항 (질문을 통해 수집)
- 아웃풋: 에이전트 구성안 + 폴더 구조 초안 + 평가 기준 제안
- 제약: Generator·Evaluator 결과를 보기 전에 설계한다
Generator (구축 에이전트)
Planner 설계안을 실제 파일로 만든다.
- 인풋: Planner 승인된 설계안
- 아웃풋: 실제 .md/.json 파일들 (전체 산출물 목록은 Phase 2 참조)
- 제약: Evaluator 기준을 미리 보지 않고 구축한다
Evaluator (평가 에이전트)
Generator 산출물을 독립적으로 검증한다.
- 인풋: Generator 생성 파일 + Planner 평가 기준
- 아웃풋: 5대 기둥 기반 점수 + 기능적 검증 결과 + 개선 피드백
- 제약: Generator 의도를 고려하지 않고 결과물만 본다
L1 Phase 0: 패턴 매칭 — harness-100 참조 (신규 v4.1)
"좋은 설계의 99%는 이미 누군가 만들어 놓았다. 찾아서 변형하라."
Discovery에 들어가기 전에 harness-100(https://github.com/revfactory/harness-100, Apache-2.0)의 검증된 exemplar 중 가장 유사한 것을 찾아 참조 기준으로 삼는다. 비개발자는 harness-starter-workspace 스킬로 전환 안내.
대상 exemplar (워크스페이스 도메인 73개)
- Content #01–15, Business #43–55, Education #56–65, Legal #66–72, Lifestyle #73–80, Docs #81–88, Operations #89–95, Specialized #96–100
Phase 0 절차
- 사용자 1~2문장 요청에서 도메인 키워드 추출
- 위 73개 중 상위 3개 후보 제시 + 사용자 확인
- 선택된 exemplar 번호를
_workspace/00_input.md의reference_exemplar필드에 기록 - 매칭 유사도 < 0.5 → 자유 설계 모드 폴백 (기존 Phase 1로 진행)
Phase 0 결과를 이후 단계에 반영
- Planner: exemplar의 4~5인 specialist + Reviewer 구성을 기본으로 사용
- Generator: exemplar 골격 스캐폴더,
_workspace/NN_*.md번호 컨벤션 강제 - Evaluator: exemplar의 8개 Quality Standards(Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries)를 루브릭으로 사용
패턴 충실도 (정성 평가, Phase 0 한정)
5대 기둥 자동 채점에는 포함하지 않는다. Phase 0에서 exemplar 매칭 시 정성적으로 평가한다.
Phase 0에서 선택한 harness-100 exemplar의 8개 Quality Standards (Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries)를 Evaluator 채점과 별개로 점검한다.
- 적용 시점: Phase 0(exemplar 선택)에서 1회, Evaluator PASS 후 보고 시 1회
- 점수화 안 함: 5대 기둥 22항목 채점에 포함되지 않음
- pillar-weight: 5대 기둥의 가중치 조정만 가능. Pattern Fidelity는 가중치 대상 아님
Reviewer 필수화
운영층에는 반드시 Reviewer 에이전트(cross-validation 역할)를 포함한다. 기존 Chairman 종합 모델에 Reviewer 교차검증 단계 추가.
Trigger Boundaries (should + NOT)
Planner/Generator는 생성되는 orchestrator skill.md에 반드시 should-NOT trigger 섹션을 포함한다.
도메인 프레임워크 주입
카테고리별로 검증된 프레임워크를 자동 주입:
- Content: AIDA, Pattern Interrupt, CURVE formula
- Business: BMC, TAM/SAM/SOM, Porter's 5 Forces, RICE, Van Westendorp PSM
- Education: Bloom's Taxonomy, ADDIE, CEFR, SM-2, Toulmin Model
- Legal: IRAC, MQM, GDPR/PIPA, IPC/CPC
- Lifestyle: BMR/TDEE, ACSM Guidelines, Compound Interest
- Docs: Diataxis, PREP, STAR, MADR, SemVer
- Operations: SIPOC/RACI, 4C Framework, SMART, NPS/CSAT, BARS
- Specialized: GHG Protocol, Cap Rate/IRR, IMRaD, Georgia-Pacific, Double Materiality
L1 Phase 1: Discovery — Planner 작동
Discovery는 4단계 질문으로 구성된다. 각 단계를 순서대로 진행하되, 사용자 답변에 따라 후속 질문이 분기된다. 한 단계의 답변을 받은 후 다음 단계로 넘어간다. 한꺼번에 묻지 않는다.
1-1. Stage 1 — 목적과 맥락 (WHY / WHO)
구조가 아닌, 이 워크스페이스가 존재하는 이유를 파악한다.
W1. 이 워크스페이스가 해결하려는 문제는 무엇인가?
(어떤 의사결정/분석/판단이 지금 잘 안 되고 있는가?)
W2. 누가 사용하는가?
(에이전트만 / 에이전트+사람 / 사람이 결과를 소비)
→ 후속: 사용자의 도메인 전문성 수준은?
W3. 이 워크스페이스의 성공 기준은?
(어떤 결과가 나오면 "잘 만들었다"고 할 수 있는가?)
W4. 비슷한 기존 프로세스가 있는가?
(대체하는 것인가 / 새로 만드는 것인가)
→ 후속 [대체]: 기존 프로세스의 가장 큰 문제점은?
→ 후속 [신규]: 벤치마크하는 시스템이 있는가?
후속 질문 분기:
- W2에서 "사람이 결과 소비" → "결과를 받는 사람의 직급/역할은? 어떤 형식을 선호?"
- W3에서 모호한 답변 → "구체적으로 어떤 산출물이 나오면 성공인가?"
1-2. Stage 2 — 산출물과 구조 (WHAT)
무엇을 만드는가, 어떤 관점이 필요한가.
S1. 최종 산출물은?
(보고서 / 의사결정 기록 / 분석 리포트 / 기획안)
S2. 반복되는 핵심 작업 패턴은?
(인풋 → 분석 → 의사결정 → 기록 → 지식 축적)
S3. 필요한 관점·역할은 몇 가지? 각각 어떤 성격?
(예: 낙관/비관/데이터/경험/규제 — 서로 충돌·보완)
→ 후속: 관점 간 우선순위가 있는가? 동등한가?
S4. Chairman(종합 역할)이 필요한가?
(메인 세션 담당 / 별도 에이전트 / 불필요)
→ 후속 [필요]: 에이전트 모델 구성은?
→ references/agent-archetypes.md 참조 후 제안
S5. 인풋 형태는?
(텍스트 직접 입력 / 파일 업로드 / URL / 복합)
S6. 남아야 할 아웃풋은?
(세션 파일 / 의사결정 기록 / 지식 축적 / deep-research)
후속 질문 분기:
- S3에서 5개 이상 관점 → "이 관점들을 그룹으로 묶을 수 있는가? 순차 vs 병렬?"
- S4에서 "별도 에이전트" → "Chairman의 판단 프레임워크는? Go/Pivot/No-Go?"
1-2.5. Stage 2.5 — 지식 관리 (KNOWLEDGE) [조건부]
멀티 어젠다 연구 워크스페이스에서 기존 연구를 체계적으로 참조하기 위한 wiki 옵션. 단일 어젠다 또는 비연구 워크스페이스에서는 스킵.
K1. "여러 어젠다(연구 주제)를 진행하며 기존 연구를 후속 연구에서 참조할 필요가 있습니까?"
→ "아니오" → wiki 불포함. Stage 3으로.
→ "예" → K2로.
K2. /graphify 스킬 설치 확인 (자동 감지)
- ~/.claude/skills/graphify/ 또는 .claude/skills/graphify/ 존재 확인
- 설치됨 → K3로.
- 미설치 → 설명 제공:
┌─────────────────────────────────────────────────┐
│ wiki는 /graphify 스킬로 생성됩니다. │
│ 이 스킬이 없으면 wiki를 생성할 수 없습니다. │
│ │
│ /graphify란? │
│ - 문서·보고서를 분석하여 지식 그래프 생성 │
│ - 개념 간 연결을 자동 발견하고 시각화 │
│ - 커뮤니티 기반 wiki 문서 자동 생성 │
└─────────────────────────────────────────────────┘
"graphify를 설치하시겠습니까?"
- 전역 설치 (~/.claude/skills/) [모든 프로젝트에서 사용]
- 프로젝트 설치 (.claude/skills/) [이 프로젝트에서만]
- 설치하지 않음 → ⚠️ "wiki 기능은 비활성됩니다.
45-wiki/ 폴더는 생성되지만 빈 상태입니다.
나중에 /graphify 설치 후 /wiki-update로 생성 가능합니다."
→ wiki 구조만 포함, 비활성. Stage 3으로.
K3. "wiki 저장소를 어디에 둘까요?"
- 프로젝트 내부 (45-wiki/) [기본]
- 외부 경로 지정
K4. "새 리서치 시작 시 wiki를 자동 탐색할까요?"
- 자동 탐색 + 사용자 승인 후 참조 [기본]
- 수동 호출(/wiki-ref)만 허용
Planner 출력에 추가 (wiki 관련):
wiki_enabled: true/falsewiki_location: "45-wiki/" 또는 사용자 지정 경로wiki_auto_ref: true/falsegraphify_installed: true/falsegraphify_scope: "global" | "project" | "none"
⚠️ wiki 참조의 독립성 보호:
- Phase A(독립 리서치) 에이전트에 wiki 내용 주입 절대 금지
- Phase B(Creative Thinker) / Phase C(Chairman)에서만 사용자 승인 후 참조 허용
- 참조 시 결론이 아닌 프레임워크/방법론/데이터 포인트만 전달
- 산출물에 wiki_ref, ref_approved_by, ref_approval_date 기록 필수
1-2.6. Stage 2.6 — 플로우 변경 이력 추적 (FLOW HISTORY) [선택]
워크플로우가 시간에 따라 개선될 것으로 예상되는 프로젝트에 권장. 1회성 분석·단발 프로젝트에서는 스킵해도 무방.
F1. "향후 워크플로우가 개선되거나 변경될 때 이력을 남길까요?"
용도:
- 프로젝트 개선 이력 회고 (왜 이렇게 바뀌었는가)
- 이전 버전으로 롤백이 필요할 때 근거 확보
- 차기 유사 프로젝트 설계 시 참고
※ 새 세션마다 읽는 용도가 아닙니다.
플로우를 수정·롤백·이식할 때만 참조합니다.
→ "아니오" → 05-flow-history/ 불포함. Stage 3으로.
→ "예" → F2로.
F2. "초기 빌드(v1)를 change 0001 레코드로 자동 기록할까요?"
- 기본값: 예 (Planner Discovery 답변이 그대로 설계 근거로 보존됨)
- 아니오 → CHANGELOG만 생성하고 첫 변경 시 수동 기록
플로우 이력 관리 원칙 (생성 후 운영 기준):
이 이력은 워크플로우 시스템(규칙·절차·도구·프롬프트·커맨드·스크립트·CLAUDE.md)의
변화만 기록한다. 시스템이 만들어낸 산출물(리서치 결과·보고서·분석·어젠다 등록)은
기록 대상이 아니다.
구별 기준: "이 변경이 없었더라면 다음에 실행하는 결과가 달라지는가?"
→ 달라진다 = 시스템 변경 = 기록 / 달라지지 않는다 = 산출물 = 기록 불필요
상세: 00-system/protocols/flow-change-protocol.md
Planner 출력에 추가 (flow-history 관련):
flow_history_enabled: true/falseflow_history_initial_record: true/false(F2 답변)
1-3. Stage 3 — 환경과 도구 (HOW)
어떤 환경에서 어떻게 운영할 것인가.
H1. 사용하는 AI 도구는?
(Claude Code / Desktop Claude / 기타)
→ 도구에 따라 하네스 설정 방식이 다름
H2. 세션 간 연속성이 필요한가?
(단발 분석 / 장기 프로젝트 / 멀티 세션)
→ "장기"라면 세션 핸드오프 산출물 포함
H3. 에이전트 모델 구성은?
→ 웹 검색으로 현재 최신 Claude 모델을 확인 후 제안
→ 모델명을 하드코딩하지 않는다. 항상 사용자가 결정
H4. 에이전트의 자율성 수준은?
(사람이 매번 확인 / 에이전트 자율 판단 + 보고 / 완전 자율)
후속 질문 분기:
- H2에서 "장기" → "예상 세션 수는? 지식 축적이 중요한가?"
- H4에서 "완전 자율" → "에스컬레이션 기준은? 어떤 상황에서 사람에게 물어야 하는가?"
1-4. Stage 4 — 품질과 평가 기준 (QUALITY / EVALUATE)
사용자가 중요하게 생각하는 가치를 파악하고, 평가 기준을 합의한다.
E1. 이 워크스페이스에서 가장 중요한 품질 속성은? (상위 3개 선택)
□ 분석 깊이 (표면적이지 않은 통찰)
□ 독립성 (에이전트 간 영향 없는 독립 분석)
□ 출처 명시 (근거 기반 결론)
□ 일관성 (세션 간 품질 유지)
□ 빠른 반응 (짧은 처리 시간)
□ 확장성 (에이전트/역할 추가 용이)
□ 문서화 (과정과 결과의 추적 가능성)
□ 사용자 접근성 (비전문가도 결과 이해)
E2. 향후 확장 계획이 있는가?
(없음 / 관점 추가 / 다른 도메인 적용 / 자동화 강화)
E3. 이 워크스페이스에서 절대 타협하면 안 되는 것은?
(예: "에이전트가 서로 영향을 주면 안 된다", "출처 없는 결론은 안 된다")
E4. 반대로, 초기에는 없어도 괜찮은 것은?
후속 질문 분기:
- E1에서 "독립성" → "어떤 수준? 결과 공유도 금지? 아니면 분석만 독립?"
- E3의 답변 → Evaluator 가중치의 핵심 입력으로 사용
1-5. 평가 가중치 합의 (Stage 4 완료 후)
Stage 1~4의 답변을 분석하여 5대 기둥의 가중치를 제안한다. 사용자와 합의하여 최종 확정한다.
[가중치 제안 프로세스]
STEP 1. Stage 1~4 답변에서 키워드 추출
- "독립성 필수" → Mechanical Enforcement ↑
- "장기 프로젝트" → Session Continuity ↑, Entropy Management ↑
- "빠른 반응" → Progressive Disclosure ↑
- "출처 명시" → Mechanical Enforcement ↑
STEP 2. 기본 가중치에서 조정하여 제안
기본 가중치 (프로젝트 특성 반영 전):
| 기둥 | 기본 | 조정 근거 | 제안 |
|------|------|----------|------|
| Progressive Disclosure | 20% | (변동 근거) | ?% |
| Mechanical Enforcement | 25% | (변동 근거) | ?% |
| Feedback Loop | 20% | (변동 근거) | ?% |
| Session Continuity | 15% | (변동 근거) | ?% |
| Entropy Management | 20% | (변동 근거) | ?% |
"이 프로젝트에서는 [근거]를 고려하여
[기둥]의 가중치를 [기본]% → [제안]%로 조정했습니다.
의견이나 수정 사항이 있으시면 말씀해주세요."
STEP 3. 사용자 피드백 반영
- 동의 → 확정
- "독립성을 더 높여줘" → Mechanical Enforcement 상향, 다른 기둥 하향 후 재제안
STEP 4. 최종 승인
→ evaluator-protocol-workspace.md의 기본 가중치 대신 합의된 가중치를 사용
1-6. 패턴 자동 매핑
Stage 2 답변으로 폴더 패턴을 자동 추천한다:
| 사용자 답변 키워드 | 추천 패턴 | 참조 |
|---|---|---|
| 분석, 투자, 의사결정, 판단 | 패턴 A (분석·의사결정형) | folder-patterns.md |
| 시공, 공정, 내역서, 건설 | 패턴 B (건설·프로젝트관리형) | folder-patterns.md |
| 리서치, 콘텐츠, 보고서 | 패턴 C (리서치·콘텐츠형) | folder-patterns.md |
| 장기 코딩, 자동화 빌드 | 패턴 D (장기 에이전트형) | folder-patterns.md |
1-7. Planner 산출물
① 프로젝트 컨텍스트 요약 — 목적, 사용자, 성공 기준, 핵심 제약 (Stage 1~2 기반) ② 에이전트 구성안 — 역할, 성격, 모델 배치 ③ 폴더 구조 초안 — 패턴 매핑 + 커스터마이징 ④ 세션 연속성 설계 — 핸드오프 방식 결정 (단발 / progress.json 사용) ⑤ 확장 전략 — 향후 확장에 대비한 설계 결정 (Stage 4 E2 기반) ⑥ 평가 기준 + 합의된 가중치 — 5대 기둥 체크리스트 + 가중치 테이블
[Planner 완료 — 사용자 승인 요청]
①~⑥을 검토 후 수정 사항 말씀해주세요.
승인되면 Generator가 구축을 시작합니다.
L1 Phase 2: Build — Generator 작동
Planner 산출물 승인 후 아래 순서로 파일 생성. Generator는 폴더 구조 + 파일 내용물 모두 생성한다.
2-1. 워크플로우 다이어그램 (Mermaid)
두 레이어를 모두 표현하는 다이어그램. Evaluator→Planner 재설계 루프 포함:
flowchart TD
USER[사용자] -->|요구사항| P
subgraph L1[Layer 1: 메타]
P[Planner] --> G[Generator]
G --> E[Evaluator]
E -->|미흡 70~89%| G
E -->|재설계 70%미만| P
E -->|승인 90%+| DONE[구조 완성]
end
DONE --> INIT
subgraph L2[Layer 2: 운영]
INIT[Initializer\n첫 실행 전용] --> OP
subgraph OP[Operating Agent 반복 실행]
INPUT[인풋] --> SPLIT[ ]
SPLIT --> A1[Agent-A]
SPLIT --> A2[Agent-B]
SPLIT --> A3[Agent-C]
A1 --> CH[Chairman 종합]
A2 --> CH
A3 --> CH
CH --> OUT[아웃풋 + 상태 저장]
end
end
2-2. 핵심 산출물 생성 (순서대로)
| 순번 | 산출물 | 참조 파일 | 비고 |
|---|---|---|---|
| 2-2a | WORKSPACE_TREE.md | folder-patterns.md | 폴더 구조 확정 |
| 2-2b | CLAUDE.md (~100줄) | claude-md-template.md | 목차 역할, 참조 라우팅 테이블 필수 |
| 2-2c | AGENTS.md | (본 스킬 내 가이드) | 에이전트 운영 규칙 + model_config |
| 2-2d | 에이전트 역할 파일 | agent-archetypes.md | 00-system/prompts/*.md |
| 2-2e | 프로토콜 5종 | (본 스킬 내 가이드) | 00-system/protocols/ |
| 2-2f | 세션 핸드오프 산출물 | session-handoff.md | progress.json + feature-status.json |
| 2-2g | 강제 규칙 | enforcement-patterns.md | 구조 검증 가능한 규칙 |
| 2-2h | 슬래시 커맨드 | (Planner 설계 기반) | .claude/commands/*.md |
| 2-2i | README.md | (사용자 가이드) | 빠른 시작 + 커맨드 + 트러블슈팅 |
| 2-2j | 플로우 변경 이력 위키 (선택) | flow-history-template.md | Stage 2.6에서 F1=예일 때만 |
2-2b. CLAUDE.md 작성 규칙 (최중요)
→ references/claude-md-template.md 참조. 반드시 100줄 이내.
CLAUDE.md는 에이전트의 **진입점(entry point)**이다. 너무 긴 instruction은 "비안내(non-guidance)"가 된다:
- 컨텍스트가 작업과 코드를 밀어낸다
- 에이전트가 의도적 탐색 대신 로컬 패턴 매칭에 빠진다
- 모놀리식 문서는 즉시 낡는다
반드시 포함하는 것:
- 워크스페이스 정체성 (3줄)
- 에이전트 구성 테이블
- 참조 라우팅 테이블 ← Progressive Disclosure 핵심
- 독립성 원칙 포인터
- 커맨드 목록
참조 라우팅 테이블 형식:
## 참조 라우팅
| 상황 | 읽을 파일 |
|------|----------|
| 에이전트 역할 확인 | → 00-system/prompts/[role].md |
| 토론 진행 규칙 | → 00-system/protocols/council-protocol.md |
| 독립성 원칙 상세 | → 00-system/protocols/independence-protocol.md |
| 세션 상태 확인 | → progress.json |
| 기능 완료 현황 | → feature-status.json |
2-2c. AGENTS.md 작성 규칙
반드시 포함:
- Layer 2 에이전트 목록 테이블 (역할 / 모델 / 활성화 조건)
- model_config 섹션 (사용자 선택 모델 + 재검토 트리거)
- Chairman 종합 방식 + 결정 프레임워크 (Go/Pivot/No-Go)
- 독립성 원칙 요약
- 컨텍스트 관리 규
…
[translation truncated]