코딩 하네스 디자이너 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 ← 레이어 구조, 모듈 경계, 의존성 방향
├── conventions.md ← 코딩 네이밍, 포맷팅, lint 규칙 설명
├── design/ ← 도메인 설계 문서 (필요한 만큼)
│ ├── database.md
│ ├── api.md
│ └── [...].md
├── exec-plans/ ← 실행 계획 + 기술 부채 추적
│ ├── [plan-name].md
│ └── tech-debt-tracker.md
├── flows/ ← 운영 플로우 (온보딩, CI, 릴리스 등)
├── quality-grades.md ← 품질 등급 정의 + 현재 점수
├── runbooks/ ← 운영 가이드
└── testing-strategy.md ← 테스트 전략
2-1k. bkit 프로젝트 초기화 (조건부)
T3에서 Claude Code + bkit 설치 감지 시:
**bkit 프로젝트 초기화** (Phase 2-1k)
bkit(`~/.local/bkit`)이 감지되었습니다.
프로젝트에 기본 bkit 설정(`.bkit/config.yaml`)을 초기화하시겠습니까?
- bkit은 빌드·테스트 스크립트를 통합 관리하는 도구입니다.
- 현재 작업 공간에서는 `_workspace/` 아래의 bkit만 영향을 받습니다.
→ "예" → 다음 명령 실행:
cd _workspace && ~/.local/bkit/bkit project-init
→ "아니오" 또는 건너뛰기 → 2-1k를 완료로 표시하고 2-1l로 진행
L1 Phase 3: Evaluate — Evaluator 작동
3-1. Generator 산출물 수집
Generator가 생성한 모든 파일 목록을 확인한다. 빠진 산출물이 있다면 Generator로 돌아가 보완을 요청한다.
3-2. 7대 기둥 채점
각 기둥을 3~4개의 세부 항목으로 채점한다.
채점 양식 (기둥별):
## [기둥명] (가중치: XX%)
### 점수: X.Y / 5.0
| # | 항목 | 점수 | 근거 | 개선 제안 |
|---|------|------|------|----------|
| 1 | 항목 설명 | /5 | | |
| 2 | 항목 설명 | /5 | | |
| 3 | 항목 설명 | /5 | | |
총점: (항목 합계 / 항목 수)
가중 적용: 총점 × (가중치 / 100)
3-3. 건별 검증 (가중치 없음)
Generator가 생성한 파일을 건별로 열어 기능적 완전성을 검증한다.
| 검증 항목 | 통과 여부 | 비고 |
|---|---|---|
| AGENTS.md가 모든 참조 라우팅을 포함하는가? | ✅/❌ | |
| docs/architecture.md가 레이어 구조를 설명하는가? | ✅/❌ | |
| docs/quality-grades.md가 정의되어 있는가? | ✅/❌ | |
| progress.json과 feature-status.json이 있는가? | ✅/❌ | |
| CI/CD 설정에 검증 게이트가 정의되어 있는가? | ✅/❌ | |
| 코드 리뷰 루프 프로토콜이 설정되어 있는가? | ✅/❌ | |
| 테스트 구조가 정의되어 있는가? | ✅/❌ | |
| Link Check (참조 무결성): AGENTS.md의 모든 링크 목적지가 존재하는가? | ✅/❌ | |
| Gap Analysis: 참조 패턴 대비 누락된 영역? | ✅/❌ | |
| Pattern Fidelity (Phase 0 선택 시): 8개 Quality Standards 준수? | ✅/❌ | |
| CLAUDE.md 내 Karpathy 4원칙 섹션 존재? | ✅/❌ | |
| 플로우 변경 이력 위키 (Stage 3.5 선택 시) 완전성? | ✅/❌ |
3-4. 오케스트레이터 skill.md 생성 (선택, 내부 POC용)
Phase 2-1k에서 bkit project-init이 실행되었고 사용자의 opt-in이 "예"인 경우에만 진행.
목적: POC 과정에서 10개 스킬을 설계·생성·적용할 때 orchestration이 필요하다면,
Generator가 아래 템플릿으로 orchestrator.skill.md를 생성한다.
비-POC에서는 생략한다.
# Orchestrator: [프로젝트명] Skill Coordinator
## Agent Team
| 역할 | 담당 에이전트 (CLI 명시) |
|------|-------------------------|
| Architect | claude -p ... architect |
| Frontend | claude -p ... frontend |
| Backend | claude -p ... backend |
| QA | claude -p ... qa |
| DevOps | claude -p ... devops |
## Scale Mode
[Full / Reduced / Single]
## Coordination Protocol
1. Architect가 실행 계획 작성
2. 각 에이전트가 할당된 작업 실행
3. QA가 테스트 실행 및 결과 보고
4. Architect가 결과 검토 및 후속 작업 할당
## should-NOT trigger
[하네스가 적용되지 말아야 할 도메인/상황]
## 의존성 DAG
[에이전트 간 의존성 방향 명시]
Evaluator 점수 기준
| 등급 | 최소 점수 | 의미 |
|---|---|---|
| S | 4.5 / 5.0 | 생산 준비 완료 |
| A | 4.0 / 5.0 | 경미한 개선 필요 |
| B | 3.0 / 5.0 | 구조적 개선 필요 |
| C | 2.0 / 5.0 | 재설계 필요 |
| D | < 2.0 | 미흡 - 재작업 요망 |
3-5. Evaluator 완료 — 피드백 제공
Evaluator가 채점을 완료하면 다음을 제공한다:
- 7대 기둥별 점수표 — 점수 + 근거 + 개선 제안
- 건별 검증 결과 — 통과/실패 + 비고
- 종합 점수 — 가중 적용 총점 + 등급
- 개선 권장 사항 — 우선순위별 목록
[Evaluator 완료 — 검토 요청]
종합 점수: X.X / 5.0 (등급: X)
개선이 필요한 항목이 있다면 Generator가 수정합니다.
전체 통과(PASS) 시 하네스가 완성됩니다.
LAYER 2: 운영 — 코딩 하네스의 역할
Layer 1(메타)이 설계·생성·검증한 코딩 하네스는 Layer 2(운영)에서 실제 코딩 에이전트에 의해 사용된다. Layer 2의 동작은 하네스 구조에 의해 결정되며, 스킬 자체의 역할은 아니다. 여기서는 Layer 2가 어떻게 동작하는지 설명한다.
L2 운영 프로세스
초기화 (최초 1회)
- Initializer가 하네스 구조 로드
- 환경 설정 (가상 환경, 의존성 설치, 환경 변수)
- 커맨드 유효성 검증
반복 개발 사이클
┌──────────────────────────────────────────────┐
│ 1. Read progress │
│ → feature-status.json, progress.json │
├──────────────────────────────────────────────┤
│ 2. Select next task │
│ → AGENTS.md 참조 → docs/exec-plans/ │
├──────────────────────────────────────────────┤
│ 3. Implement (code generation) │
│ → 아키텍처 규칙 준수 → 의존성 방향 유지 │
├──────────────────────────────────────────────┤
│ 4. Self-verify │
│ → 테스트 실행 → 린터 검사 → 브라우저 │
├──────────────────────────────────────────────┤
│ 5. Request review (peer agent) │
│ → 코드 리뷰 루프 → 피드백 반영 │
├──────────────────────────────────────────────┤
│ 6. Commit clean state │
│ → progress 업데이트 → feature-status │
└──────────────────────────────────────────────┘
L2 핵심 메커니즘
세션 핸드오프
- 각 세션 종료 시: progress.json 업데이트 + git commit
- 각 세션 시작 시: git pull + progress.json 확인 + feature-status.json 로드
- 지시 불변: "프로젝트 컨텍스트를 잃었습니다. progress.json을 읽고 재개하세요."
자체 수정 (Self-Correction)
- 에러 발생 시 → 에러 메시지 해석 → 수정 코드 생성 → 재시도
- 3회 연속 실패 시 → 리뷰 요청 (사람 또는 상위 에이전트)
- 테스트 실패 시 → 테스트 통과할 때까지 수정 루프
품질 관리
- quality-grades.md에 정의된 기준으로 코드 품질 자가 평가
- 기술 부채는 tech-debt-tracker.md에 기록
- 정기적인 리팩터링 세션 (quality-grades.md가 등급 하락 시)
아키텍처 강제
- 린터/CI 단계에서 의존성 방향 검증
- 모듈 간 참조 규칙 위반 시 빌드 실패 (Mechanical Enforcement)
- 제3자가 규칙을 위반해도 CI에서 차단
참조
- harness-100 exemplar library
- [karpathy-guidelines 스킬]
- [harness-designer (analysis workspace)]
- OpenAI: "클로드가 성공하려면 정확한 프롬프트와 잘 구조화된 환경이 필요하다"
- Anthropic: "코딩 에이전트를 위한 명시적 구조의 중요성"
변경 이력
| 버전 | 날짜 | 변경 내용 |
|---|---|---|
| v1.0 | 초기 | 코딩 하네스 디자이너 v1 생성 |
| v1.1 | 현재 | Phase 0 Pattern Match + Karpathy 원칙 + Architect Rigidity/Observable Runtime 기둥 + Scale Modes + Trigger Boundaries + bkit 초기화 절차 + 2-1l 환경 설정/2-1m 플로우 변경 이력 + Stage 3.5 + 3-4 오케스트레이터 + CI/CD + 테스트 구조 + 세션 핸드오프 + 코드 리뷰 루프 + 관찰 가능성 + 참조 라우팅 + 건별 검증 개선 |