charlie-harness

Charlie-Harness — 워크플로우 네이티브 메타 하네스

도메인/프로젝트에 맞는 하네스를, 런타임에 모델이 해석하는 산문 오케스트레이터가 아니라 결정적 JavaScript Workflow 스크립트로 컴파일하는 메타 스킬. v1 harness의 계승 원칙(에이전트/스킬 분리, progressive disclosure, 진화 시스템, pushy 트리거)을 유지하되, 오케스트레이션 자체를 코드·스키마·매니페스트로 고정한다.

이 스킬의 본질: 무거운 빌드 로직은 본 SKILL.md 산문이 아니라 templates/build-harness.js 워크플로우에 있다. 이 스킬이 트리거되면 곧바로 Workflow({name: 'build-harness'})를 호출한다. SKILL.md는 트리거 + 철학 + 호출 규약 + 체크리스트만 담는 얇은 진입점이다.

빌드 철학 — 오케스트레이션은 코드다

v1은 "누가 언제 어떤 순서로 협업하는가"를 산문 마크다운으로 적고 매 실행마다 모델이 재해석했다. 그 결과 비결정적 제어 흐름(L5), 강제력 없는 프로즈 계약(L1), 산문 권고에 그친 검증(L6), 무성 폴백(L2)이 누적됐다. charlie-harness는 이 지점을 정확히 뒤집는다 — 제어 흐름은 pipeline()/parallel()로, 경계 계약은 JSON Schema로, 적대적 검증은 워크플로우 단계로, 폴백은 throw/log()로 코드화한다. "모델이 매번 읽는 지시서"에서 "버전 관리·테스트·재현 가능한 실행 산출물"로의 전환이 전부다.

10원칙 (5 계승 + 5 신규)

v1에서 계승 (불변):

#	원칙	의미
1	에이전트(누가) / 스킬(어떻게) 분리	역할 페르소나와 절차 지식을 별도 파일로
2	Progressive disclosure	3-tier 컨텍스트 (metadata → SKILL.md → references)
3	하네스는 진화 시스템	변경 이력·피드백 루프 유지
4	적극적("pushy") 트리거	description이 유일한 트리거 메커니즘

v2 신규 (워크플로우 도입):

#	원칙	해소하는 v1 한계	코드화 수단
5	오케스트레이션은 코드다	L5 비결정 제어흐름	{domain}.js Workflow 스크립트
6	계약은 스키마다	L1 프로즈 계약 무강제	agent(prompt, {schema})
7	검증은 구조다	L6 검증 권고	적대적 verify 스테이지(코드)
8	모델 티어는 역할별	L3 블랭킷 opus	역할별 agent({model})
9	단일 매니페스트	L4 오케스트레이터 drift	.charlie/manifest.json SSOT
10	큰 소리 실패	L2 무성 degradation	throw + .filter(Boolean) + log()

원칙 J(빌더 자기적용/dogfooding): 빌더 자신이 워크플로우라서, 하네스 생성 과정에도 동일한 스키마 강제·적대적 검증이 적용된다.

v2 산출물 구조

도메인 하네스 1개를 빌드하면 대상 프로젝트에 다음이 생성된다:

프로젝트/
├── .claude/
│   ├── agents/{role}.md                  # 에이전트 페르소나 (워크플로우가 agentType으로 참조)
│   ├── skills/
│   │   ├── {role-skill}/SKILL.md          # 절차 스킬 (선택적, 역할 축소)
│   │   └── {domain}-harness/SKILL.md      # ★ 얇은 트리거 스킬 → Workflow({name}) 호출
│   └── workflows/{domain}.js              # ★ 결정적 오케스트레이터 (산문 오케스트레이터 대체)
├── .charlie/
│   ├── manifest.json                      # ★ SSOT — 에이전트·스킬·워크플로우·스키마 레지스트리
│   └── schemas/{name}.json                # ★ 에이전트 간 산출물 계약 (JSON Schema)
└── CLAUDE.md                              # 하네스 포인터 + 변경 이력

왜 얇은 트리거 스킬인가 (R2 완화)

워크플로우는 키워드로 자동 발동하지 않는다. 따라서 도메인마다 {domain}-harness 스킬을 생성하되 본문은 최소화한다 — "이 도메인 요청이면 Workflow({name: '{domain}'})를 호출하라" + pushy description + 후속 키워드. 무거운 로직은 전부 {domain}.js에 있다. 트리거 스킬은 다리(bridge)일 뿐이다.

빌드 프로세스 — build-harness.js 워크플로우 실행

이 스킬이 트리거되면 산문으로 단계를 흉내 내지 말고 곧바로 빌드 워크플로우를 호출한다:

Workflow({ name: 'build-harness', args: { domain, projectRoot, request, runMode } })

빌드 워크플로우(templates/build-harness.js)의 meta.phases는 다음 6단계를 정의한다(각 phase는 코드로 박혀 있으며 산문 재해석 대상이 아니다). 실제로 실행되는 phase 셋은 Audit 결과의 분기 모드(신규/확장/유지보수)가 선택한다 — 아래 분기 규칙 참조:

phase	역할	핵심 수단	모델 티어
Audit	기존 .charlie/manifest.json·.claude 스캔 → 신규/확장/유지보수 분기, drift 감지	파일 스캔 + log()로 drift 명시	haiku
Analyze	도메인 분해: roles[], data_flow, execution_pattern, model_tiers	agent({schema: harness-spec})	sonnet→opus
Design	judge-panel: N개 아키텍처 후보 → 점수 → 최적 선택	perspective-diverse agent, parallel 합의	opus
Generate	에이전트.md / 워크플로우.js / 스키마 / 트리거 스킬 동시 생성 → manifest로 fan-in	parallel(thunks) 배리어(정당: 전 산출물이 단일 manifest 등록·정합성 검사로 cross-item 합류)	sonnet (생성)
Verify	각 산출물 정적 검증 + 적대적 리뷰 → 발견 verify	pipeline(artifacts, lint, refute)	opus (검증)
Register	manifest.json·CLAUDE.md 갱신, 변경 이력 기록	파일 쓰기 + SSOT 등록	haiku

분기 규칙 (Audit 결과 — 어느 phase가 실행되는지 결정):

• 신규: manifest 없음 → 6단계(Audit→Analyze→Design→Generate→Verify→Register) 전부 실행.
• 확장: manifest 존재 + 새 역할 추가 → 6단계 실행하되, Analyze는 충돌/중복 검토, Generate는 신규 산출물만 생성, Register는 변경 이력 append.
• 유지보수/감사: 수정·동기화·drift 점검 요청 → Audit 중심, Analyze·Design·Generate 건너뛰고 Verify+Register로 drift 해소.

실패 내성: 빌드 중 1개 산출물 생성만 실패해도 resumeFromRunId로 실패 지점부터 재개, 나머지는 저널 캐시 재사용(L7 해소). 동일 도메인+args 재실행은 100% 캐시 히트 → 동일 에이전트 수·단계 수·파일 셋(결정성 가설 검증).

워크플로우 스크립트 규약 (생성물이 지켜야 할 계약)

빌드가 생성하는 모든 {domain}.js는 다음을 지키며, Verify phase가 이를 정적 검증한다:

• meta는 순수 리터럴 (변수/함수호출/스프레드 금지). meta.phases 제목 = phase() 호출 제목.
• 금지 API: 벽시계 시각 호출·난수 호출·인자 없는 날짜 생성자 (resume 깨짐). 타임스탬프는 args 주입 또는 인덱스 기반 변형.
• 기본은 pipeline(items, ...stages) — 단계 간 배리어 없음. parallel(thunks) 배리어는 cross-item 의존(dedup/merge/early-exit/상호참조)일 때만, 주석으로 정당화.
• 모든 cross-agent 산출물은 agent(prompt, {schema}) — 스키마는 JSON Schema 객체, 검증된 객체 반환.
• 모델 티어는 역할별: 수집/추출/포맷 → haiku·sonnet; 합성/검증/설계 → opus. 생략 시 세션 모델 상속 — 더 싼 티어가 명백히 맞을 때만 명시.
• 모든 생성물에 적대적 verify 스테이지 (다수결 refute 또는 perspective-diverse). 검증은 산문 권고가 아니라 코드.
• 드롭/캡은 log()로 명시 (무성 truncation 금지).
• 동적 루프는 budget.total 가드 (target 없으면 remaining()은 Infinity).

상세는 references/ 참조:

• references/WORKFLOW-CONTRACT.md — 정본 규약(SSOT): {domain}.js 작성 형식 C1~C16 (meta 리터럴, 톱레벨 본문, 앰비언트 글로벌, await 강제, 금지 API). 모든 생성물·패턴 문서가 따른다.
• references/workflow-orchestration-patterns.md — pipeline/parallel/budget 관용구, v1 6패턴 → 워크플로우 매핑
• references/schema-contracts.md — 스키마 라이브러리(harness-spec/agent-def/finding/verdict)
• references/verification-patterns.md — 적대적 검증 템플릿(majority-refute, judge-panel, loop-until-dry)
• references/agent-and-skill-design.md — v1 핵심 계승(압축): 에이전트 분리 기준, pushy description, progressive disclosure
• references/migration-from-v1.md — 산문 오케스트레이터 → 워크플로우 점진 이전 경로

산출물 체크리스트

빌드 완료 후 Register phase가 확인 (워크플로우가 코드로 검증):

• .claude/agents/{role}.md — 에이전트 정의 파일 필수 생성 (빌트인 타입이라도 파일 생성)
• .claude/workflows/{domain}.js — meta 순수 리터럴, phases 제목 일치, 금지 API 없음
• .claude/skills/{domain}-harness/SKILL.md — 얇은 트리거 스킬, 본문이 Workflow({name}) 호출 지시
• .charlie/schemas/*.json — 모든 cross-agent 경계가 스키마로 정의됨
• .charlie/manifest.json — 에이전트·스킬·워크플로우·스키마 전부 등록 (SSOT, drift 0)
• 워크플로우에 적대적 verify 스테이지 존재 (모든 생성물 대상)
• 모델 티어가 역할별로 분화 — 블랭킷 opus 없음
• 기본 pipeline(), 배리어는 주석으로 정당화된 parallel()만
• 드롭/캡이 log()로 가시화 — 무성 truncation 없음
• .claude/commands/ — 아무것도 생성하지 않음
• 트리거 스킬 description이 pushy + 후속 키워드(다시/재실행/업데이트/수정/보완) 포함
• 각 SKILL.md 본문 500줄 이내, 초과분 references/ 분리
• CLAUDE.md에 하네스 포인터(트리거 규칙) + 변경 이력 등록
• 빌드 재실행 시 동일 입력 → 동일 산출물 셋 (결정성 확인)

테스트 시나리오

정상 흐름 — 신규 research-harness 빌드

입력: "리서치 도메인 하네스 워크플로우로 구축해줘" (대상 프로젝트에 .charlie/manifest.json 없음).

1. 스킬 트리거 → Workflow({name:'build-harness', args:{domain:'research', projectRoot, request, runMode:'new'}}) 호출.
2. Audit: manifest 부재 확인 → runMode='new' 확정, log("신규 빌드: 기존 매니페스트 없음").
3. Analyze: agent({schema: harness-spec}) → roles=[collector, extractor, verifier, synthesizer], execution_pattern='producer-verifier', model_tiers={collector:'haiku', synthesizer:'opus', verifier:'opus'}.
4. Design: judge-panel 3후보 점수화 → pipeline+적대적 verify 채택.
5. Generate: parallel로 agents/.md + workflows/research.js + schemas/.json + skills/research-harness/SKILL.md + manifest.json 동시 생성.
6. Verify: pipeline(artifacts, lint, refute) → research.js의 meta 리터럴·금지 API·pipeline-default·스키마·verify 스테이지 정적 통과.
7. Register: manifest 등록 + CLAUDE.md 포인터·변경 이력 append. 기대: 위 체크리스트 전 항목 통과. 재실행 시 동일 파일 셋.

에러 흐름 — 누락 의존성에서 큰 소리 실패

입력: "research 하네스 verifier 에이전트만 다시 만들어줘" 인데 .charlie/manifest.json이 손상/부재.

1. Audit: 부분 재실행 의도지만 SSOT 매니페스트 부재 감지.
2. 무성 폴백(단일 에이전트로 조용히 진행) 금지 — 워크플로우가 명시적으로 throw: "manifest.json 부재 — 부분 재실행 불가. 전체 빌드(runMode:'new') 또는 매니페스트 복구 필요."
3. 사용자에게 복구 경로 2개 제시: (a) 전체 재빌드, (b) resumeFromRunId로 직전 성공 빌드 저널에서 매니페스트 재생.
4. Generate 중 특정 산출물 생성 실패 시 해당 thunk는 null → .filter(Boolean)로 제외하고 log("drop: <artifact> 생성 실패") — 나머지는 진행하되 드롭을 가시화. 기대: 조용한 성공 가장(假裝) 없음. 실패는 throw 또는 log()로 표면화.