Coding Harness Designer v1
"에이전트가 못한 건 능력 부족이 아니라, 환경이 부족했기 때문이다." — OpenAI "생성자가 자기 작업을 평가하게 하지 마라." — Anthropic "에이전트가 실수하면, 그 실수를 다시는 하지 못하도록 엔지니어링하라." — Mitchell Hashimoto
이 스킬과 harness-designer의 관계
┌─────────────────────────────────────────────────────────────┐
│ 공통 기반: 하네스 설계 5대 기둥 │
│ Progressive Disclosure / Mechanical Enforcement / │
│ Feedback Loop / Session Continuity / Entropy Management │
├──────────────────────────┬──────────────────────────────────┤
│ harness-designer (기존) │ coding-harness-designer (이것) │
│ 분석·의사결정 워크스페이스 │ 코딩·개발 워크스페이스 │
│ 에이전트 = 관점 역할 │ 에이전트 = 코딩 작업자 │
│ 산출물 = 보고서·결정 │ 산출물 = 소스 코드·테스트 │
│ 검증 = 체크리스트·토론 │ 검증 = CI·린터·브라우저 테스트 │
│ "회의실 설계" │ "공장 라인 설계" │
└──────────────────────────┴──────────────────────────────────┘
코딩 하네스 7대 기둥
기존 5대 기둥에 코딩 전용 2개를 추가한다:
| 기둥 | 핵심 질문 | 원칙 |
|---|---|---|
| Progressive Disclosure | 에이전트가 필요한 것만 볼 수 있는가? | AGENTS.md ~100줄 목차 → docs/ |
| Mechanical Enforcement | 아키텍처가 기계적으로 강제되는가? | 린터·구조 테스트·CI |
| Feedback Loop | 실패 시 에이전트가 자체 수정하는가? | 에러 메시지가 수정법을 가르침 |
| Session Continuity | 세션 간 핸드오프가 깨끗한가? | progress + feature-status + git |
| Entropy Management | 시간이 지나도 코드 품질이 유지되는가? | 자동 스캔·리팩터링·품질 등급 |
| Architectural Rigidity ← 신규 | 모듈 경계가 강제되는가? | 레이어 규칙·의존성 방향 검증 |
| Observable Runtime ← 신규 | 에이전트가 실행 결과를 볼 수 있는가? | 로그·메트릭·DOM·스크린샷 접근 |
두 레이어의 관계
┌─────────────────────────────────────────────────────────────┐
│ LAYER 1: 메타 (이 스킬의 역할) │
│ │
│ Planner ──→ Generator ──→ Evaluator │
│ ↑ (단방향 순차, 역참조 금지) │
│ └──── 미흡 시 피드백 ─────────────────────────────┘ │
│ │
│ 목적: 코딩 하네스 구조를 설계·생성·검증 │
└─────────────────────────┬───────────────────────────────────┘
│ 승인 후 하네스 완성
▼
┌─────────────────────────────────────────────────────────────┐
│ LAYER 2: 운영 (완성된 코딩 하네스의 역할) │
│ │
│ ┌ Initializer (첫 실행) ─→ 스캐폴드 + 환경 설정 │
│ │ │
│ └ Coding Agent (반복 실행): │
│ 1. progress 읽기 → 다음 작업 선택 │
│ 2. 구현 (코드 생성) │
│ 3. 자체 검증 (테스트·린터·브라우저) │
│ 4. 리뷰 요청 (에이전트 간 코드 리뷰) │
│ 5. 피드백 반영 → 반복 │
│ 6. clean state로 커밋 │
│ │
│ 목적: 실제 코드 작성·테스트·리팩터링·배포 │
└─────────────────────────────────────────────────────────────┘
LAYER 1: 메타 — 코딩 하네스 설계 프로세스
L1 에이전트 3종 (단방향 순차, 역참조 금지)
Planner (기획)
사용자 요구를 분석해서 코딩 하네스 구조를 설계한다.
- 인풋: 프로젝트 요구사항 (질문으로 수집)
- 아웃풋: 아키텍처 설계 + 폴더 구조 + 강제 규칙 + 평가 기준
Generator (구축)
Planner 설계안을 실제 파일과 설정으로 만든다.
- 인풋: Planner 승인된 설계안
- 아웃풋: AGENTS.md, docs/, 린터 규칙, CI 설정, 테스트 구조
Evaluator (검증)
Generator 산출물을 7대 기둥 기반으로 독립 검증한다.
- 인풋: Generator 생성 파일 + Planner 평가 기준
- 아웃풋: 기둥별 점수 + 기능적 검증 + 개선 피드백
L1 Phase 0: Pattern Match — harness-100 참조 (신규 v1.1)
"좋은 설계의 99%는 이미 누군가 만들어 놓았다. 찾아서 변형하라."
Discovery에 들어가기 전에 harness-100(https://github.com/revfactory/harness-100, Apache-2.0)의 검증된 exemplar 중 가장 유사한 것을 찾아 참조 기준으로 삼는다. 비개발자는 harness-starter-coding 스킬로 전환 안내.
대상 exemplar (코딩 도메인 27개)
- Dev&DevOps #16–30: fullstack-webapp, mobile-app-builder, api-designer, database-architect, devops-pipeline, security-audit, performance-tuning, refactoring-squad, test-automation, monitoring-setup 등
- Data&AI/ML #31–42: ml-experiment, data-pipeline, rag-llm-app, nlp-processor, recommendation-engine, design-system 등
Phase 0 절차
- 사용자 1~2문장 요청에서 앱 유형 키워드 추출
- 위 27개 중 상위 3개 후보 제시 + 사용자 확인
- 선택된 exemplar 번호를
_workspace/00_input.md의reference_exemplar필드에 기록 - 매칭 유사도 < 0.5 → 자유 설계 모드 폴백 (기존 Phase 1로 진행)
Phase 0 결과를 이후 단계에 반영
- Planner: exemplar의 5인 에이전트 구성을 기본으로 하되, Scale Mode(Full/Reduced/Single)에 따라 조정
- Generator: exemplar 골격 스캐폴더 우선 사용,
_workspace/NN_*.md번호 컨벤션 강제 - Evaluator: exemplar의 Quality Standards 8항목(Agent Team Mode / Domain Expertise / Structured Outputs / Dependency DAG / Error Handling / Scale Modes / Test Scenarios / Trigger Boundaries)을 루브릭으로 사용
Pattern Fidelity (정성 평가, Phase 0 한정)
7대 기둥 자동 채점에는 포함하지 않는다. 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회
- 점수화 안 함: 7대 기둥 23항목 채점에 포함되지 않음
- pillar-weight: 7대 기둥의 가중치 조정만 가능. Pattern Fidelity는 가중치 대상 아님
Trigger Boundaries (should + NOT)
Planner/Generator는 생성되는 orchestrator skill.md에 반드시 should-NOT trigger 섹션을 포함한다. 예: "모바일 앱·엔터프라이즈 마이크로서비스·정적 웹사이트에는 사용 금지".
Coding Agent Behavior Principles (Karpathy-inspired, 필수 주입)
Generator는 생성하는 .claude/CLAUDE.md 끝부분에 반드시 아래 섹션을 포함한다. 이 4원칙은 karpathy-guidelines 스킬(독립 설치됨)과 동기화되며, 하네스 내 모든 코딩 에이전트의 기본 행동 지침이 된다.
## Coding Agent Behavior Principles (Karpathy-inspired)
모든 코딩 에이전트는 작업 시 아래 4원칙을 준수한다.
상세는 karpathy-guidelines 스킬 참조 (자동 트리거).
1. Think Before Coding — 가정 명시, 모호하면 질문, 대안 제시
2. Simplicity First — 요청한 만큼만. 사변적 추상화·기능 금지
3. Surgical Changes — 요청 라인만 변경. 주변 코드 개선 금지
4. Goal-Driven Execution — 검증 가능한 성공기준 → 루프 → 확인
Evaluator 체크리스트에 "CLAUDE.md 내 Karpathy 4원칙 섹션 존재 여부" 항목 추가.
Scale Modes (운영층 기본값)
| 모드 | 에이전트 구성 |
|---|---|
| Full | architect + frontend + backend + qa + devops |
| Backend | architect + backend + qa |
| Frontend | architect + frontend + qa |
| Refactoring | architect + 관련 개발자 + qa |
| DevOps | devops 단독 |
L1 Phase 1: Discovery — Planner 작동
Discovery는 4단계 질문으로 구성된다. 각 단계를 순서대로 진행하되, 사용자 답변에 따라 후속 질문이 분기된다. 한 단계의 답변을 받은 후 다음 단계로 넘어간다. 한꺼번에 묻지 않는다.
1-1. Stage 1 — 목적과 맥락 (WHY / WHO)
기술이 아닌, 이 프로젝트가 존재하는 이유를 파악한다.
P1. 이 프로젝트가 해결하려는 문제는 무엇인가?
(어떤 불편함/비효율을 없애려 하는가?)
P2. 누가 사용하는가?
(내부 직원 / 고객 / 개발자 / 불특정 다수)
→ 후속: 사용자 수는? IT 숙련도는?
P3. 이 프로젝트의 성공 기준은?
(무엇이 되어야 "잘 만들었다"고 할 수 있는가?)
P4. 비슷한 기존 시스템이 있는가?
(대체하는 것인가 / 새로 만드는 것인가)
→ 후속 [대체]: 기존 시스템의 가장 큰 문제점은?
→ 후속 [신규]: 벤치마크하는 서비스가 있는가?
후속 질문 분기:
- P2에서 "내부 직원" → "몇 명? 부서 구조가 있는가? 권한 체계가 필요한가?"
- P2에서 "고객" → "가입 방식은? 결제가 있는가? 개인정보 처리는?"
- P3에서 구체적 수치 언급 → "그 수치를 측정하는 방법은?"
- P3에서 모호한 답변 → "구체적으로 어떤 화면/기능이 동작하면 성공인가?"
1-2. Stage 2 — 기능과 내용 (WHAT)
무엇을 담는가, 핵심 기능은 무엇인가.
F1. 핵심 기능 3가지를 우선순위로 나열하면?
(가장 먼저 동작해야 하는 것부터)
F2. 데이터의 성격은?
(관계형 / 문서형 / 시계열 / 파일 / 복합)
→ 후속: 데이터 간 관계가 복잡한가? 집계/통계가 중요한가?
F3. 인증/권한 요구사항이 있는가?
(없음 / 단순 로그인 / 역할 기반 / 조직 계층 권한)
→ 후속 [역할 기반 이상]: 권한 레벨은 몇 단계? 데이터 격리가 필요한가?
F4. 외부 시스템 연동이 있는가?
(없음 / API 연동 / 파일 import/export / 결제 / 알림)
F5. 오프라인 또는 모바일 지원이 필요한가?
후속 질문 분기:
- F1에서 3개 이상 기능 → "각 기능의 복잡도를 상/중/하로 평가하면?"
- F2에서 "복합" → "어떤 종류가 섞이는가? 저장소를 분리해야 하는가?"
- F3에서 "조직 계층" → "부서 추가/변경이 잦은가? 코드 변경 없이 확장 가능해야 하는가?"
1-3. Stage 3 — 기술과 구조 (HOW)
어떻게 만들 것인가. Stage 1~2의 답변을 반영하여 적합한 기술을 제안한다.
T1. 기술 스택 선호가 있는가?
(있으면 명시 / 없으면 "추천해줘")
→ "보링 테크놀로지" 권장: 에이전트는 안정적이고 학습 데이터가
풍부한 기술로 더 잘 작동한다 (OpenAI 원안)
→ Stage 1~2 답변 기반으로 적합한 스택을 제안한다
T2. 배포 환경은?
(Vercel / AWS / 사내 서버 / 모름)
T3. 코딩 에이전트 도구는?
(Claude Code / Codex / Cursor / 기타)
→ 도구에 따라 하네스 설정 방식이 다름
T4. 에이전트의 자율성 수준은?
(사람이 리뷰 후 머지 / 에이전트 간 리뷰 후 자동 머지 / 완전 자율)
T5. 프로젝트 규모와 기간은?
(프로토타입 1~2주 / 중규모 1~3개월 / 대규모 장기)
T6. 기존 코드베이스가 있는가?
(신규 / 기존 코드에 하네스 적용)
→ 기존 코드라면 점진적 적용 전략 설계
후속 질문 분기:
- T1에서 "추천해줘" → Stage 1
2 답변 기반으로 23개 옵션 비교표 제시 후 선택 - T2에서 "모름" → 사용자 규모와 기능 기반으로 추천
- T5에서 "대규모" → "팀 규모는? 동시 작업하는 에이전트 수는?"
1-3.5. Stage 3.5 — 플로우 변경 이력 추적 (FLOW HISTORY) [선택]
장기 프로젝트 또는 여러 세션에 걸쳐 코딩 하네스가 진화할 가능성이 있을 때 권장. 1~2주 프로토타입에서는 스킵해도 무방.
F1. "향후 프롬프트·프로토콜·템플릿·API 스크립트·커맨드·CLAUDE.md가 변경될 때
이력을 남길까요?"
용도:
- 프로젝트 개선 이력 회고 (왜 이렇게 바뀌었는가)
- 이전 버전으로 롤백이 필요할 때 근거 확보
- 차기 유사 코딩 하네스 설계 시 참고
※ 새 세션마다 읽는 용도가 아닙니다.
플로우를 수정·롤백·이식할 때만 참조합니다.
→ "아니오" → 05-flow-history/ 불포함. Stage 4로.
→ "예" → F2로.
F2. "초기 빌드(v1)를 change 0001 레코드로 자동 기록할까요?"
- 기본값: 예 (Planner Discovery 답변이 설계 근거로 보존됨)
- 아니오 → CHANGELOG만 생성하고 첫 변경 시 수동 기록
플로우 이력 관리 원칙 (생성 후 운영 기준):
이 이력은 워크플로우 시스템(프롬프트·프로토콜·템플릿·API 스크립트·커맨드·CLAUDE.md)의
변화만 기록한다. 시스템이 만들어낸 산출물(코드·보고서·분석 결과)은 기록 대상이 아니다.
구별 기준: "이 변경이 없었더라면 다음에 실행하는 결과가 달라지는가?"
→ 달라진다 = 시스템 변경 = 기록 / 달라지지 않는다 = 산출물 = 기록 불필요
상세: 00-system/protocols/flow-change-protocol.md
Planner 출력에 추가 (flow-history 관련):
flow_history_enabled: true/falseflow_history_initial_record: true/false(F2 답변)
1-4. Stage 4 — 품질과 평가 기준 (QUALITY / EVALUATE)
사용자가 중요하게 생각하는 가치를 파악하고, 평가 기준을 합의한다.
E1. 이 프로젝트에서 가장 중요한 품질 속성은? (상위 3개 선택)
□ 보안 (권한, 데이터 격리, 인증)
□ 성능 (응답 속도, 동시 접속)
□ 확장성 (코드 변경 없이 규모 확장)
□ 유지보수성 (다른 사람/에이전트가 쉽게 수정)
□ 사용자 경험 (직관적 UI, 빠른 반응)
□ 테스트 가능성 (자동 테스트로 품질 보증)
□ 빠른 출시 (MVP 우선, 완성도는 나중에)
□ 데이터 정합성 (정확한 기록, 누락 방지)
E2. 향후 확장 계획이 있는가?
(없음 / 기능 추가 / 다른 시스템과 결합 / 사용자 규모 확장)
→ 후속: 구체적으로 어떤 확장? 시기는?
E3. 이 프로젝트에서 절대 타협하면 안 되는 것은?
(예: "권한 격리가 깨지면 안 된다", "데이터가 유실되면 안 된다")
E4. 반대로, 초기에는 없어도 괜찮은 것은?
(예: "모바일 대응은 나중에", "통계 대시보드는 2차에")
후속 질문 분기:
- E1에서 "보안" 선택 → "어떤 종류의 보안? 인증/권한/데이터 암호화/감사 로그?"
- E2에서 "다른 시스템과 결합" → "어떤 시스템? 데이터 형식은 호환되는가?"
- E3의 답변 → Evaluator 가중치의 핵심 입력으로 사용
1-5. 평가 가중치 합의 (Stage 4 완료 후)
Stage 1~4의 답변을 분석하여 7대 기둥의 가중치를 제안한다. 사용자와 합의하여 최종 확정한다.
[가중치 제안 프로세스]
STEP 1. Stage 1~4 답변에서 키워드 추출
- "권한 격리" → Mechanical Enforcement, Architectural Rigidity ↑
- "코드 변경 없이 확장" → Architectural Rigidity ↑
- "빠른 출시" → Entropy Management ↓, Observable Runtime ↑
- "데이터 정합성" → Feedback Loop ↑, Mechanical Enforcement ↑
STEP 2. 기본 가중치에서 조정하여 제안
기본 가중치 (프로젝트 특성 반영 전):
| 기둥 | 기본 | 조정 근거 | 제안 |
|------|------|----------|------|
| Progressive Disclosure | 15% | (변동 근거) | ?% |
| Mechanical Enforcement | 20% | (변동 근거) | ?% |
| Feedback Loop | 15% | (변동 근거) | ?% |
| Session Continuity | 10% | (변동 근거) | ?% |
| Entropy Management | 10% | (변동 근거) | ?% |
| Architectural Rigidity | 20% | (변동 근거) | ?% |
| Observable Runtime | 10% | (변동 근거) | ?% |
"이 프로젝트에서는 [근거]를 고려하여
[기둥]의 가중치를 [기본]% → [제안]%로 조정했습니다.
의견이나 수정 사항이 있으시면 말씀해주세요."
STEP 3. 사용자 피드백 반영
- 동의 → 확정
- "보안을 더 높여줘" → 관련 기둥 가중치 상향, 다른 기둥 하향 후 재제안
- "이 기둥은 필요 없어" → 0%로 설정, 나머지 재분배 후 재제안
STEP 4. 최종 승인
"최종 가중치를 확정합니다. 이 가중치로 Evaluator가 채점합니다."
→ evaluator-protocol.md의 기본 가중치 대신 이 합의된 가중치를 사용
1-6. 아키텍처 패턴 자동 매핑
→ references/architecture-patterns.md 참조
→ Stage 2~3 답변 기반으로 가장 적합한 패턴을 제안한다
| 애플리케이션 유형 | 추천 레이어 구조 |
|---|---|
| 풀스택 웹앱 | Types→Config→Repo→Service→Runtime→UI |
| API 서비스 | Types→Config→Repo→Service→Runtime |
| CLI 도구 | Types→Config→Core→CLI |
| 라이브러리 | Types→Core→Public API |
1-7. Planner 산출물
① 프로젝트 컨텍스트 요약 — 목적, 사용자, 성공 기준, 핵심 제약 (Stage 1~2 기반) ② 아키텍처 설계안 — 레이어 구조, 모듈 경계, 의존성 방향 ③ 폴더 구조 초안 — references/coding-folder-patterns.md 기반 ④ 강제 규칙 설계 — 어떤 규칙을 린터/CI/구조 테스트로 강제하는가 ⑤ 테스트 전략 — 유닛/통합/E2E 범위와 커버리지 기준 ⑥ 에이전트 자율성 설계 — 리뷰 루프, 승인 게이트, 에스컬레이션 기준 ⑦ 확장 전략 — 향후 확장에 대비한 설계 결정 (Stage 4 E2 기반) ⑧ 평가 기준 + 합의된 가중치 — 7대 기둥 체크리스트 + 가중치 테이블
[Planner 완료 — 사용자 승인 요청]
①~⑧을 검토 후 수정 사항 말씀해주세요.
승인되면 Generator가 구축을 시작합니다.
L1 Phase 2: Build — Generator 작동
2-1. 핵심 산출물 생성 (순서대로)
| 순번 | 산출물 | 설명 |
|---|---|---|
| 2-1a | 아키텍처 다이어그램 | Mermaid — 레이어·모듈·의존성 방향 |
| 2-1b | AGENTS.md (~100줄) | 목차 역할, 참조 라우팅 포함 |
| 2-1c | docs/ 디렉터리 | 아래 상세 |
| 2-1d | 아키텍처 강제 규칙 | 린터 규칙 + 구조 테스트 |
| 2-1e | CI/CD 파이프라인 설계 | 검증 게이트 정의 |
| 2-1f | 테스트 구조 | 테스트 디렉터리 + 기본 설정 |
| 2-1g | 세션 핸드오프 산출물 | progress.json + feature-status.json |
| 2-1h | 코드 리뷰 루프 설정 | 에이전트 간 리뷰 프로토콜 |
| 2-1i | 관찰 가능성 설정 | 로그·메트릭·DOM 접근 방법 |
| 2-1j | README.md | 개발자 가이드 |
| 2-1k | bkit 프로젝트 초기화 | T3에서 Claude Code + bkit 설치 감지 시 사용자 opt-in 질문 후에만 실행 (아래 상세) |
| 2-1l | 환경 설정 | 가상환경·환경변수·훅 — 강제 생성 안 함. Phase 3-7에서 LLM 제안 후 사용자 선택 |
| 2-1m | 플로우 변경 이력 위키 (선택) | Stage 3.5 F1=예일 때만. ~/.claude/skills/harness-designer-workspace/references/flow-history-template.md 참조하여 05-flow-history/ + 00-system/protocols/flow-change-protocol.md 생성. AGENTS.md에 라우팅 2행 + "플로우 변경 추적 (선별 기록)" 섹션 추가. 관리 원칙: 시스템(규칙·절차·도구) 변화만 기록. 산출물(코드·보고서)은 기록 불필요. 구별 기준: "이 변경이 없었더라면 다음 실행 결과가 달라지는가?" |
2-1b. AGENTS.md 작성 규칙 (최중요)
→ references/agents-md-template.md 참조
OpenAI 원안의 핵심 교훈을 그대로 적용:
~100줄 목차. 백과사전이 아니다.
# [프로젝트명]
> [한 줄 설명]
## 아키텍처 개요
[레이어 구조 3줄 요약]
→ 상세: docs/architecture.md
## 참조 라우팅
| 상황 | 읽을 파일 |
|------|----------|
| 아키텍처 규칙 | → docs/architecture.md |
| 코딩 컨벤션 | → docs/conventions.md |
| 도메인 설계 | → docs/design/[domain].md |
| 실행 계획 | → docs/exec-plans/[plan].md |
| 품질 등급 | → docs/quality-grades.md |
| 기술 부채 | → docs/exec-plans/tech-debt-tracker.md |
| 세션 상태 | → progress.json |
| 기능 현황 | → feature-status.json |
## 핵심 규칙 (5가지 이내)
1. [불변 규칙 1 — 예: "모든 경계에서 데이터 형태를 검증"]
2. [불변 규칙 2 — 예: "레이어 역방향 의존 금지"]
3. [불변 규칙 3]
## 테스트 규칙
→ docs/testing-strategy.md
## 커맨드
| 커맨드 | 기능 |
|--------|------|
| /implement [기능] | 기능 구현 |
| /review | 코드 리뷰 실행 |
| /test | 테스트 실행 |
| /refactor [대상] | 리팩터링 |
## 최종 업데이트: YYYY-MM-DD
2-1c. docs/ 디렉터리 (System of Record)
→ references/docs-structure.md 참조
docs/
├── architecture.md ← 레이어 구조, 모듈 경계, 의
…
[truncated for translation]