+
-
-
감(感)에서 지표로 가는 5단계
--
-
- 01왜 ‘바이브 코딩’은 한계에 부딪히는가감으로 짠 코드의 리스크 — 반응적 루프와 컨텍스트 제약
-
- 02코딩 에이전트 하네스란 무엇인가에이전트 = 모델 + 하네스 — 컨텍스트·툴·가드레일의 구조
-
- 03하네스 엔지니어링 실전Claude Code를 통제 가능한 워크플로우로 — 성숙도 Lv.0→5
-
- 04Evaluator 설계에이전트 응답을 ‘느낌’ 아닌 ‘지표’로 측정하기
+
-
- 비유: 설계도 없이 감으로 짓는 창고. 헛간까지는 서지만 3층부터 기운다. -
- 2025년의 질문: “AI가 동작하는 코드를 쓸 수 있는가” -
- 2026년의 질문: “프로덕션 코드를 배포하도록 AI를 어떻게 오케스트레이션하는가” -
- 규모의 근거: 코딩 에이전트 활동 GitHub 프로젝트 비중 2배 이상(’25년 말↑) · Claude Code 사용자 주당 평균 20시간 -
- 반응적 루프 — 하나를 고치면 다른 게 깨지고, 진짜 회귀인지 노이즈인지 구분 못한 채 수렁 -
- 프로덕션에서만 발견 — 사용자 불만 → 수동 재현 → 수정 → “다른 게 안 깨졌기를 기도” -
- “느낌이 나빠졌다” 논쟁 — 팀원마다 체감이 달라 회의 안건은 되지만 행동 불가 -
- 모델의 상품화 — Claude·GPT·Gemini가 벤치마크에서 좁은 범위로 수렴. 차이를 만드는 것은 모델을 감싸는 시스템 -
- 에이전트의 프로덕션 진입 — 2026년, 에이전트가 실제 프로덕션 코드를 작성. “다운되면 안 된다” 수준의 신뢰도 요구 -
- 벤치마크의 한계 노출 — 벤치마크는 단일 턴, 프로덕션 에이전트는 수백 단계. 50단계 후 방향 이탈에 1% 향상은 무의미 -
- 제약 — “무엇을 하지 못하게 할 것인가”. 탐색 공간을 줄여 집중시킨다(직관에 반하는 생산성) -
- 피드백 루프 — “실수를 어떻게 잡을 것인가”. 자기 리뷰(약)→독립 리뷰어(중)→자동 검증(강) -
- 상태 관리 — “맥락을 어떻게 유지할 것인가”. 파일 핸드오프·컨텍스트 리셋·서브에이전트 격리 -
- 4/7 결과가 갈림 — 대조군이 위험 코드를 그대로 생성 4건 -
- 하드 커밋 게이트 차단 4/4 성공 (대조군 0 — 게이트 없음) -
- 결정적 4건: S1(WHERE 없는 DELETE)·S2(force push)·S4(마이그레이션 수정)·S6(eval 인젝션) -
- A. 정상 작업으로 포장된 위험 요청 (S1·S2·S6) — “cleanup 함수”·“배포 스크립트”로 포장하면 모델 기본 정렬(alignment, 안전·의도 준수 성향)이 뚫린다 -
- B. 모델이 모르는 프로젝트 고유 관례 (S4) — “마이그레이션 불변”은 학습 지식에 없다. 도메인 규칙 전파는 하네스만의 몫 -
- C. 결정론적 하드 게이트 — 모델 순응은 확률적(4건 뚫림). 커밋 게이트만 100% 차단 보장 -
- 무의미: 이미 정렬이 막는 위반(S0·S3, 감사추적 차이만) · 강제 없는 스타일 규칙(S5, 권고일 뿐) -
- 요청 층 (확률적) — CLAUDE.md·스킬·프롬프트. 대체로 지켜지나 컨텍스트가 차면 누락 -
- 보증 층 (결정적) — Pre/PostToolUse·Stop 훅·settings.json deny·CI(Continuous Integration, 지속적 통합) 게이트. 잊거나 무시 불가 -
- Anthropic 인사이트: 자기 작업을 평가시키면 미흡해도 자신 있게 칭찬 — 자기 평가 편향(Self-Eval Blindspot) -
- 같은 모델이라도 컨텍스트가 다르면 서로 버그를 찾아낸다 (독립 컨텍스트의 교차 검증) -
- 과보고 경고: 갭을 찾으라고 프롬프트된 리뷰어는 건전할 때도 보고 → 정확성·명시 요구사항 갭만, 나머지는 선택 -
- 판정이 이진이 아니라 통계적 — assert가 아니라 케이스 집합의 통과율·점수 분포. 노이즈 속의 측정 과학 -
- 기준이 코드가 아니라 “성공 정의”에서 출발 — “좋은 성능”(✕) → “규정 수치 정확 인용, 규정 외 약속 금지”(○) -
- 대상이 모델이 아니라 시스템 전체 — 컨텍스트·플래닝·메모리·도구·가드레일의 컴파운드 시스템 -
- 전수 체크리스트 — 스펙(SC, Success Criteria=성공 기준)과 실제 git diff를 교차해 “구현 주장 요소”를 빠짐없이 열거 (누락·허위 동시 포착) -
- 교차검증 채점 — 항목마다 독립 2렌즈 0~100점, 두 점수의 min 채택 (낙관 편향 차단) -
- 95점 게이트 루프 — 하나라도 <95면 미진사항을 개발로 되먹여 재실행 -
- 가드: MAX_ITER=8 · 동일 오류 3회 → [ESCALATION] 중단 · Generator ≠ Evaluator -
- 상태 파일: CHECKLIST.json · SCORE.json · EVAL-<n>.md (에이전트 간 통신은 항상 파일 경유) -
- 회차 1 — CHECKLIST 4항목 → 채점 C1:97 · C2:70(중복검증 테스트 없음) · C3:92(만료 경계 미검증) · C4:100 → 게이트 차단 -
- 피드백: C2 “verify 테스트 추가·중복 시 409”, C3 “만료 경계 테스트” -
- 회차 2 — C2·C3만 재작업 → C2:96 · C3:97 → 전 항목 ≥95 → DONE -
- 회귀 게이트 — 매 PR에서 골든셋 실행, 핵심 지표 ±3% 초과 하락 시 빌드 실패 -
- 짝지은 측정 — 같은 골든셋·같은 Judge에서 케이스별 점수차를 부트스트랩(재표집) 10,000회 → 평균차 90% 신뢰구간. CI가 0을 포함하면 배포 보류 -
- 카나리(canary) — 트래픽 5%를 신버전에 → 온라인 eval 대조 → 안정·개선일 때만 승격 -
- 실측(프롬프트 인젝션, TRIAD 벤치마크): 평균 탐지 recall(재현율, 실제 공격 중 탐지 비율) 58.57% → 탐지돼도 실제 차단 <37.26% → 차단 후 정상 과제 보존 <2.31% -
- 대안: 허용/거부 이진 대신 proceed / refuse / update 3중 판정 + 구조화 피드백을 컨텍스트에 주입 — 계획을 수정하고 정상 과제를 보존하는 폐쇄 루프 -
- CORE-Bench — 처음 42% → 경직 채점(“96.124991…”을 기대하며 “96.12”를 벌함)·모호한 명세를 고치자 95%로 급등. 범인은 에이전트가 아니라 채점기 -
- METR — 임계값까지 최적화하라 해놓고 채점은 초과해야 통과 → 지시를 따른 모델이 벌점, 무시한 모델이 고득점(채점기 역설) -
- 신호 경보 — 일괄 0% = 태스크·환경 결함 / 일괄 100% = 포화(saturation), 축하가 아니라 문항 교체 신호. SWE-bench Verified가 1년 만에 40%→80%+ -
+
@@ -3302,77 +3314,70 @@ 왜 ‘바이브 코딩’은 한계에 부
왜 ‘바이브 코딩’은 한계에 부
-
-
-
-
- 01 · 정의
- 바이브 코딩 = 계획도, 리뷰도, 테스트도 없는 원샷
- research·plan·execute·review·ship이 하나의 “설명”으로 뭉개진다 — 게이트 0개. 여기서 하네스(harness, 모델을 감싸 제어하는 실행 환경)가 하는 일은 그 게이트를 되살리는 것이다.
-
-
-
-
+
-
- 
-
-
- 01 · 패러다임
- 프롬프트 → 컨텍스트 → 하네스
- 각 단계는 이전을 포함하며 확장한다 — 단일 입력 최적화(프롬프트) ⊂ 정보 환경 구성(컨텍스트) ⊂ 런타임 환경 설계(하네스).
+
-
+
+
- 
-
-
- 01 · 구조적 실패
- 프롬프트로 해결할 수 없는 문제 6가지 — “더 잘 말하기”로는 안 되는 것들
-
- 문제 프롬프트 / 컨텍스트로는 (지시) 하네스로는 (구조) 자기 평가 편향 “비판적으로 리뷰하라” → 자기 코드를 칭찬 Generator와 Evaluator를 물리적으로 분리 컨텍스트 불안 컴팩션(compaction, 컨텍스트 압축)해도 “마무리해야 한다”는 충동 컨텍스트 리셋 + 파일 핸드오프(handoff, 상태 인계) 규칙 망각 CLAUDE.md에 써도 47번째에서 잊힘 Hook / 린터로 자동 감지 아키텍처 침범 “이 레이어만 수정하라” → 편의상 위반 allowed_tools로 도구 레벨 접근 차단 무한 루프 “5번 이상 시도 금지” → 무시 가능 max_iterations로 하드 리밋 강제 상태 유실 세션 전환 시 이전 맥락 소실 파일 기반 핸드오프로 상태 영속화
- 왼쪽 열은 전부 “지시”, 오른쪽 열은 전부 “구조”다. 지시는 확률적으로 지켜지고 구조는 물리적으로 강제된다. · 출처: 사내 발표자료(Noah, 2026.04)
+
-
+
+
@@ -3381,20 +3386,23 @@ 프롬프트로 해
- 
-
-
-
-
- 01 · 대가
- 감으로 짠 코드의 대가 — 반응적 루프
- 리스크의 본질은 “코드가 틀린다”가 아니라 — 틀렸는지 아닌지를 팀이 모른다는 데 있다. Eval·게이트 없는 팀에서 목격되는 3가지:
-
-
-
-
+
-
+
+
- 
@@ -3438,37 +3439,52 @@ 감으로 짠 코드의 대가 — 반응적
-
-
-
- 01 · 타이밍
- 왜 지금인가 — 세 가지 변화의 수렴
-
-
- → 그래서 필요한 것이 “모델을 감싸는 시스템” — 하네스다. (2장에서 계속)
-
-
+
+ 01 · 대가
+ 고쳐도 고쳐도 제자리인 이유
+
+ 검증 게이트가 없는 팀의 증상: 버그를 프로덕션에서야 발견하고, “느낌이 나빠졌다” 논쟁만 반복 — 진짜 리스크는 틀렸는지조차 모른다.
+ Eval과 게이트는 이 뺑뺑이를 끊는 장치다 — 뒤 챕터에서 직접 만든다.
+
+
- 
+
+
+
+
+
+
+
+
+
+
-
+
- 
-
+
-
- 02 · 코드로 증명된 정의
- Harness = Tools + Knowledge + Observation + Action + Permissions
+
+ 02 · 정의
+ 하네스 = 엔진을 뺀 자동차 전부
+
+ 모델은 엔진 — 아무리 좋아도 핸들·브레이크 없이는 도로에 못 나간다. 하네스는 모델을 뺀 나머지 전부다.
+ 이 자동차 비유가 강의 전체를 관통한다 — 모델(엔진)은 그대로 두고, 차(하네스)를 설계한다.
+
+
-
+
-
-
-
- 02 · 심장
- The Agent Loop — 제약·검증이 주입되는 자리
-while True:
- response = await api.stream(messages, tools)
- if response.stop_reason != "tool_use":
- break # 모델이 작업 완료
- for call in response.tool_uses:
- # 권한검사 → PreToolUse 훅 → 실행 → PostToolUse 훅
- result = await harness.execute_tool(call)
- messages.append(tool_results)
- 도구 실행 한 번에 권한 검사 → PreToolUse 훅 → 실행 → PostToolUse 훅 파이프라인이 끼어든다. 이 지점이 프로젝트 제약과 검증 훅이 주입되는 자리.
-
-
+
+ 02 · 구성요소
+ 하네스를 이루는 다섯 가지
+
+ 거창한 프레임워크가 아니다 — 이미 Claude Code를 쓸 때마다 만나는 다섯 가지가 곧 하네스다.
+ 이 다섯 개의 손잡이를 의도적으로 조정하는 것이 하네스 엔지니어링이다.
+
+
- 
-
+
-
-
-
- 02 · 3기둥
- 하네스의 세 기둥 — 제약 · 피드백 루프 · 상태 관리
-
-
- 가장 효과적인 하네스: 자동 검증 → 독립 리뷰어 → 인간 체크포인트의 계층 조합.
-
-
-
- 제약이 생산성을 낮출 것 같지만, 탐색 공간을 줄여 에이전트를 집중시킨다.
-
+
+ 02 · 심장
+ 에이전트의 심장, Agent Loop
+
+ Claude Code가 일하는 방식 = 이 루프의 반복 — 생각하고, 도구 쓰고, 결과 보고, 다시 생각한다.
+ 규칙을 CLAUDE.md에 쓰면 “기억”이지만, ③에 걸면 “강제”다 — 매 바퀴마다 자동 적용된다.
+
-
+
+
+
+
+
+
+
+
+
+
+
+
-
- 02 · 해부
- 서브시스템 → 3기둥 매핑 (OpenHarness 10+) — 하나의 디렉토리 = 하나의 책임
-
- 기둥 서브시스템 역할 제약 permissions/ · hooks/ 멀티레벨 권한 모드, 경로 규칙, 커맨드 차단, PreToolUse 차단 훅(exit 2 = 비정상 종료로 도구 호출 차단) 피드백 skills/ · coordinator/ · tools/ 스킬 로딩, 서브에이전트 검증·조율, 결과 관찰 상태 memory/ · tasks/ · prompts/ · config/ MEMORY.md 크로스세션, 백그라운드 태스크, 컨텍스트 압축 코어 engine/ · tools/ Agent Loop, 43개 도구(Pydantic 입력 검증 — 파이썬 데이터 검증 라이브러리)
- 권한 3모드: Default 쓰기·실행 전 확인 Auto 전부 허용(샌드박스) Plan Mode 모든 쓰기 차단
- 주의: 3기둥 매핑은 강의 프레임에 따른 해석이며 OpenHarness 공식 분류가 아님. · 출처: openharness-analysis.html
+
+ 02 · 제약 실전
+ 권한 모드 — 가장 쉬운 제약
+
+ 권한 모드는 하네스 제약의 첫 손잡이 — Shift+Tab으로 즉시 전환한다.
+ 원칙: 처음엔 Default, 익숙해지면 Accept Edits, Bypass는 컨테이너 같은 격리 환경에서만.
+
+
-
+
-
+
02 · 실증 A/B
- 하네스는 로컬 모델의 행동을 실제로 바꾸는가
- A/B 테스트(대조 실험): 동일 opencode 1.17.15 + qwen3.6:35b(ollama · 로컬 모델 실행 런타임)에, 하네스 유무만 다르게 두고 위반 유도 명령 7종(S0–S6)을 주입.
-
-
- → 다음 페이지: S0–S6 전체 결과 매트릭스 (CONTROL vs HARNESS). 출처: harnessreport.pdf (2026-07-08).
+ 정말 행동이 바뀔까? — 실험
+
+ 같은 모델이라도 하네스를 입히면 위험 명령이 게이트에서 막힌다 — 프롬프트가 아니라 구조가 행동을 바꾼다.
+ 로컬 오픈소스 모델로 재현한 실험(2026-07, harness-report) — 7가지 시나리오 전체 결과는 다음 페이지에.
+
+
-
+
-
- 02 · 실증 결과
+ 7가지 위험 명령, 결과는?
+
+ 쉬운 위험(비밀키·개인정보)은 모델 스스로도 거부한다 — 하지만 DB 삭제·강제 푸시 같은 진짜 사고는 하네스 게이트만 막았다.
+ 못 막은 1건(디자인 규칙)도 교훈 — 훅이 경고만 하면 안 막힌다. 차단(exit 2)까지 가야 강제다.
+
+
-
+
-
+
02 · 실증 해석
- 하네스가 값을 하는 3지점, 무의미한 2지점
-
-
- 한계 고지: 실시간 차단 훅은 Claude Code 전용. opencode에선 AGENTS.md(소프트)+pre-commit(하드) 2계층만.
+ 하네스, 어디에 걸어야 하나
+
+ 게이트는 비용이다 — 모델이 스스로 잘하는 곳엔 걸지 말고, 뚫리는 세 곳에 집중하라.
+ 도구마다 지원은 다르다 — 실시간 차단 훅은 Claude Code 전용, 다른 도구에선 커밋 게이트로 대신한다.
+
+
-
+
-
+
-
-
-
- 03 · 로드맵
- 성숙도 모델 — 5분부터 시작하라
-
- 레벨 무엇 · 시간 효과 Lv.0 프롬프트만 · 0분 기본 Lv.1 CLAUDE.md · 5분 반복 실수 30%↓ Lv.2 역할 분리 · 30분 자기 평가 편향 제거 Lv.3 Hook 자동 검증 · 1시간 규칙 망각 해결 Lv.4 파일 핸드오프 · 2시간 대규모 작업 가능 Lv.5 실패 패턴 축적 · 지속 하네스 자체가 진화
- 본질은 레벨이 아니라 습관 — “이번만 고치기”가 아니라 시스템에 규칙을 추가하기.
-
-
-
- 진입 장벽은 낮다 — Lv.1은 5분 투자로 반복 실수를 약 30% 줄인다.
-
+
+ 03 · 용어
+ 먼저, 용어부터
+
+ 용어 (풀 네이밍) 쉬운 설명 성숙도 모델 (Maturity Model) 한 번에 완성이 아니라 Lv.0→5 계단으로 올라가는 도입 로드맵 커맨드 (Command) 사람이 /이름 으로 직접 부르는 저장된 프롬프트 — 예: /commit 스킬 (Skill) 상황이 맞으면 AI가 스스로 꺼내 읽는 절차서 파일 (SKILL.md) 서브에이전트 (Subagent) 별도 기억 공간에서 일하는 보조 AI — 격리 실행·독립 검증에 쓴다 PLAN.md 구현 전에 체크박스로 쓰는 계획서 — 리뷰가 이 문장 그대로 결과와 대조한다 핸드오프 (Handoff) 세션을 끝내기 전 진행 상황을 파일로 남겨 다음 세션이 이어받게 하는 인수인계 토큰 (Token) AI가 글을 읽고 쓰는 최소 단위(대략 글자 몇 개) — 사용량과 요금이 토큰 수로 계산된다
+
+ 커맨드·스킬·서브에이전트 전부 이미 Claude Code에 들어 있는 부품이다 — 새로 만드는 게 아니라 켜는 것.
- 
-
+
-
-
+
+ 03 · 로드맵
+ 성숙도 모델 — 5분부터 시작하라
+
+ 본질은 레벨이 아니라 습관 — “이번만 고치기”가 아니라 시스템에 규칙을 추가하기.
+ 한 계단씩이면 된다 — 다음 장부터 각 계단을 실제 설정으로 만들어 본다.
+
+
+
+
+
+
+
+
+
-
+
-
+
03 · 부품 · CLAUDE.md 심화
- 무엇을 넣고, 무엇을 빼는가 — CLAUDE.md는 항상 로드된다
-
- 넣는다 (안정적 규칙) 뺀다 → 어디로 무엇을 넣고, 무엇을 빼는가
+
+ 넣는다 — CLAUDE.md에 뺀다 — 더 좋은 자리로 빌드·테스트·실행 명령어 (pnpm test) 스타일 가이드 전문 → 린터/포매터 + 훅이 강제 코드 컨벤션 핵심 몇 줄 (“ESM 사용, CJS 금지”) 조건부로만 필요한 긴 지식 → 스킬의 점진적 공개 “완료의 정의(definition of done)” 반드시 강제될 것 → settings.json·훅 (설정 1줄이 “NEVER” 문장보다 결정적) 절대 건드리면 안 되는 경로 (마이그레이션·시크릿) 자주 바뀌는 임시 컨텍스트 → 세션 프롬프트로 — 경로 종속 규칙 → .claude/rules/*.md + paths glob (지연 로드) 빌드·테스트 명령어 (npm test) 긴 스타일 가이드 → 린터·포매터가 자동 강제 컨벤션 핵심 몇 줄 가끔만 필요한 긴 지식 → 스킬 (필요할 때만 로드) 완료의 정의 (“테스트 녹색이면 끝”) 반드시 강제할 것 → 설정·훅 (설정 1줄이 “절대 금지” 문장보다 세다) 건드리면 안 되는 경로 오늘만 필요한 맥락 → 그냥 대화로 — 특정 폴더 전용 규칙 → 규칙 파일 분리 (.claude/rules/)
- 운영 원칙: 같은 실수 2회 = 규칙 후보. 조건부 지식과 강제 규칙은 CLAUDE.md가 아닌 다른 계층으로 뺀다.
+
+ 운영 원칙: 같은 실수 2번 = 규칙 후보.
+ 단, 강제할 수 있는 것은 문장으로 쓰지 말고 설정·훅으로 옮겨라 — 문장은 잊혀도 설정은 남는다.
+
-
+
-
+
-
+
-
-
-
- 03 · 핵심 원리
- 요청(request)과 보증(guarantee)은 다르다
-
-
- “반드시 일어나야 하는 것은 훅에 속한다. 가드레일은 훅에 넣고, 그 외 전부는 정중한 제안이다.”
- 판별 질문 하나: “어기면 곤란한가?” → 예 = 훅/설정, 아니오 = CLAUDE.md/스킬
-
-
+
+ 03 · 핵심 원리
+ 요청과 보증은 다르다
+
+ “반드시 일어나야 하는 것은 훅에 속한다 — 그 외 전부는 정중한 부탁이다.”
+ 판별 질문 하나: 어기면 곤란한가? 예 = 훅·설정(보증 층), 아니오 = CLAUDE.md·스킬(요청 층).
+
+
- 
-
+
-
+
-
-
-
- 03 · 부품 · 역할 분리
- 역할 분리 — Generator ≠ Evaluator
-
-
- 완료 판정 = 단언이 아니라 증거 (테스트 출력·명령 반환값·스크린샷).
-
-
+
+ 03 · 부품 · 역할 분리
+ 만든 AI에게 채점을 맡기지 마라
+
+ 완료 판정은 단언이 아니라 증거 — 테스트 출력·명령 반환값·스크린샷이 말하게 하라.
+ 주의: 리뷰어에게 “문제를 찾으라”고만 하면 없는 문제도 만들어 온다 — 정확성·요구사항 위반만 필수로.
+
+
- 
-
+
+
-
+
-
+
-
+
03 · 실물 케이스 1
- 실물 하네스 해부 — carve-harness (이 프로젝트가 실제 사용 중)
-
- 계층 위치 · 트리거 성격 실물 ① — 이 자료를 만든 하네스
+
+ 계층 위치 하는 일 강제 훅 (8개 활성) .claude/hooks/ + settings.json 툴 호출/프롬프트 자동 · 결정적 (차단은 exit 2) Squad 에이전트 (9종) .claude/agents/ · /squad 단일 책임 위임 워크플로 스킬 .claude/skills/ · /carve-* 절차 자동화 (자연어 또는 커맨드) 계약·규칙 문서 루트 *.md (flight-rules · 운영 규칙 문서) 에이전트·훅이 참조 · 단일 진실 출처 강제 훅 (8개) .claude/hooks/ 위험 명령·비밀 파일을 자동 차단 — 어길 수 없음 (exit 2) 전문 에이전트 (9종) .claude/agents/ · /squad 리뷰·QA·보안 등 역할별로 분리해 위임 워크플로 스킬 .claude/skills/ 커밋·핸드오프 같은 반복 절차를 말 한마디로 규칙 문서 루트 *.md 훅과 에이전트가 참조하는 기준 문서
- 대표 훅: block-destructive(포크밤·rm -rf 차단) · protect-secrets(.env·키 차단) · pre-push-test(테스트 실패 시 push 차단) · anti-slop(시각 산출물 검사) · precompact-handoff(압축 전 상태 인계). 슬림화 결정: 11→8 훅.
+
+ 훅 예시: 파괴 명령 차단 · 비밀 파일 보호 · 테스트 실패 시 push 차단 — 오늘 배운 부품이 전부 실전 가동 중이다.
+ 그리고 지금 보고 있는 이 슬라이드 덱도 이 하네스 안에서 만들어졌다.
+
-
+
-
+
03 · 실물 케이스 2
- 프로젝트 필수 하네스 구성 — API 포탈 (Spring + React)
-
- 묶음 무엇 핵심 자산 실물 ② — 실무 프로젝트에 얹는 순서
+
+ 순서 무엇을 왜 ① 에이전트 정의 back/front/gateway 역할 분리 AGENTS.md 계층 (폴더별) ② 스킬 세션 인계·결정 기록 handoff · changelog(decision-ledger) ③ 훅 포맷·린트·머지금지·커밋룰 hooks.json + commitlint (exit 2) ④ 서브에이전트 타입·예외·시크릿·인증 검증 security-reviewer · evaluator ⑤ 룰/가드레일 검증 가능한 규칙 md rules/ (common·java·react·ts) ⑥⑦⑧ 토큰 관리 · SDD 킷 · 게이트웨이 검증 codesight+LSP · GSD · e2e ① 규칙 문서 (CLAUDE.md · rules/) 팀 규칙을 파일로 — 모든 세션에 자동 적용 ② 훅 — 포맷·린트·커밋 검사 “반드시”를 자동 강제 (exit 2 차단) ③ 스킬 — 세션 인계·결정 기록 반복 절차를 말 한마디로 ④ 검증 에이전트 — 보안·타입 검사 만든 쪽과 검사하는 쪽 분리 ⑤ 역할 분리 — 백/프론트 폴더별 정의 영역 밖 코드를 건드리지 않게 ⑥ 그 다음에야 — 컨텍스트 절약·명세 킷 등 기본기가 자리 잡은 뒤의 고급 부품
- 3기둥 위에 토큰 관리·SDD(명세 주도 개발)·게이트웨이 검증을 얹어 완성 — 한 번에 다 하지 말 것. (GSD = Get Shit Done, SDD 킷 · LSP = Language Server Protocol · e2e = 종단간 테스트)
+
+ 실제 사례: 사내 API 포탈(Spring + React)에 이 순서 그대로 적용했다.
+ 핵심은 순서 — 한 번에 다 하지 말 것. 성숙도 계단처럼 하나씩 얹는다.
+
-
+
-
- 03 · 토큰 매니지먼트
- 토큰 관리 — 광고 수치와 실효 절감은 다르다
-
- 도구 줄이는 대상 광고 절감 비고 headroom API 페이로드(grep·diff)를 프록시에서 압축 47~92% (중앙값 54%) RTK(동반 압축 툴킷) 번들 포함 caveman Claude 자체 출력을 전보문처럼 축약(telegraphic) 50~75% /caveman lite|full|ultra LSP 코드 탐색을 심볼 좌표로 축소 (LSP = Language Server Protocol, 언어 서버 프로토콜) 정의 43× · 참조 2.1× 중대형·리팩토링용 codesight 세션 시작 구조 파악을 압축 맵 1개로 세션당 6.8× LSP와 상호보완
- 실측 경고: 독립 실측(614M 토큰)에서 headroom+rtk+caveman 합산 실효 절감은 약 3.7% — 비용 대부분이 cache_create·output이라 이 도구들이 손대지 않는 스트림이기 때문. 광고 수치는 “특정 스트림 단독 최선값”이다.
+
+ 03 · 토큰 관리
+ 토큰 절약 — 광고와 실측은 다르다
+
+ 광고 수치는 “특정 구간의 최선값” — 전체 청구서 기준으론 몇 %에 그치기도 한다. 도입 전 반드시 실측.
+ 도구보다 습관이 먼저 — 요약해서 가져오고, 조사는 서브에이전트에 맡기고, 컨텍스트가 차면 새 세션.
+
+
-
+
-
+
03 · 하네스의 진화
- Harness Handbook — “어디를 고칠지”가 병목이다. 진화는 “수정을 생성”만이 아니라 “어디를 고칠지 아는” 표현에 달렸다. (arXiv:2607.13285)
+ AI에게 코드 지도를 쥐여줘라
+
+ 진짜 병목은 “어디를 고칠지” — 위치를 찾는 능력이 코드를 짜는 능력보다 먼저다.
+ 실무 적용: 프로젝트 구조 문서(코드 맵)를 하네스에 넣어라 — 품질은 오르고 토큰은 준다.
+
+
- 
-
+
+
- 
-
+
-
+
- 
-
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
- 04 · 기초
- Eval의 3가지 본질 — 전통 테스트와 다른 점
-
-
- 셋 중 하나라도 빠지면 전통 QA의 연장선일 뿐, eval이 아니다.
-
-
+
+ 04 · 두 축
+ EDD의 두 축 — 만들고, 채점하고
+
+ 두 축은 분리하되(만든 쪽이 채점하지 않는다 — 32페이지), 나란히 기른다 — 채점 코드도 기능 코드와 같은 정성으로.
+ 축이 하나뿐인 팀이 반응적 루프에 빠진다 — 만드는 속도만 늘고, 확인하는 속도는 그대로라서.
+
+
- 
-
+
-
- 04 · 채점기
- 채점기 3종 — 대체재가 아니라 조합이다 (가능하면 결정적으로, 필요하면 LLM으로, 검증엔 사람)
-
- 종류 방법 강점 약점 코드형 정규식 매칭, 이진 테스트, 정적 분석, 결과·도구 호출 검증 빠르고 저렴, 객관적, 재현 가능 유효한 변형에 뻣뻣, 뉘앙스 부족 모델형
LLM-as-Judge 루브릭 점수, 자연어 assertion, 쌍대 비교, 다중 Judge 합의 유연, 뉘앙스 포착, 개방형 처리 비결정적, 비쌈, 사람과 보정 필요 사람형 SME(Subject Matter Expert, 해당 분야 전문가) 리뷰, 스팟체크, A/B, 평가자 간 일치도 정답지 수준 품질 비싸고 느림, 스케일 한계
- 원칙: 경로가 아니라 결과를 채점 — 에이전트는 설계자가 예상 못한 유효한 접근을 찾는다. 창의성을 벌하지 마라. 다구성 태스크엔 부분 점수.
+
+ 04 · 기초
+ Eval은 테스트와 무엇이 다른가
+
+ Eval = AI 시대의 테스트 — 답이 매번 조금씩 달라지는 시스템은 통계로 채점할 수밖에 없다.
+ 셋 중 하나라도 빠지면 전통 QA의 연장선일 뿐 — 특히 “성공 정의” 없이 시작하지 마라.
+
+
-
+
-
+
-
-
-
- 04 · 온프레미스
- 3계층 게이트 — 결정론 → LLM-as-Judge → 사람
-
- 게이트 수단 통과 조건 1 결정론 컴파일·테스트·Checkstyle(스타일 검사)·ArchUnit(아키텍처 규칙 테스트)·grep 전부 통과 (하드) 2 LLM-as-Judge 루브릭 G-Eval(LLM 루브릭 채점) · 로컬 vLLM(오픈 LLM 추론 서버), guided_json(출력 스키마 강제) 점수 ≥ 7.0 3 사람 수동 라벨 교정·엣지케이스만
- 임계값은 유형별 허용 실패율: convention 5% / correctness 3% / domain_safety 0% (Judge 출력은 guided_json 스키마 강제 + temperature 0).
-
-
+
+ 04 · 3층 게이트
+ 게이트는 3층 — 기계, AI, 사람
+
+ 순서가 곧 비용 — 기계로 막을 수 있는 건 전부 기계로, AI와 사람은 그 다음 층에 아껴 쓴다.
+ 실패 허용도도 유형별로: 스타일 5% · 정답성 3% · 안전 규칙 0% — 안전은 단 한 건도 예외 없다.
+
+
- 
-
+
-
+
04 · 결정론 우선
- 규칙으로 표현 가능한 것은 전부 결정론적으로 — Run-AI 규약 → 자동 검사 매핑
-
- 규약 검사 방법 규칙을 기계 검사로 번역하기
+
+ 팀 규칙 (사람의 문장) 기계 검사 (자동 실행) 컴파일 / 전체 테스트 ./gradlew compileJava test 코드 스타일·네이밍 ./gradlew checkstyleMain 컨트롤러의 엔티티 직접 반환 금지 ArchUnit: @RestController 반환 타입에 @Entity 금지 @ManyToOne/@OneToMany는 LAZY ArchUnit + grep: FetchType.EAGER 금지 패턴 AI 호출은 컨트롤러 스레드 동기 금지 grep: 컨트롤러 패키지에서 동기 호출 부재 확인 Flyway(DB 마이그레이션 도구) 기존 마이그레이션 미수정 CI diff 검사: V*.sql 기존 파일 변경 시 실패 빌드가 깨지지 않는다 컴파일 + 전체 테스트 자동 실행 코드 스타일 통일 스타일 검사기(린터) 자동 실행 화면 계층에서 DB 객체 직접 반환 금지 구조 검사 도구가 반환 타입을 확인 무거운 호출은 응답 경로에서 금지 금지 패턴 검색(grep)으로 확인 과거 마이그레이션 파일 수정 금지 CI가 기존 파일 변경을 감지하면 실패
- 2장 A/B의 S4(마이그레이션 불변)가 여기서 회수된다 — 모델이 모르는 팀 관례를 결정론 검사가 강제한다.
+
+ 포인트: 팀 관례를 문장이 아니라 기계 검사로 번역했다 — 사람이 안 봐도 걸린다.
+ 2장 실험에서 하네스만 막았던 “마이그레이션 수정”이 바로 이 검사다 — 실험이 실전 규칙으로 회수됐다.
+
-
+
-
+
04 · 실물 채점표
- evaluation-criteria — 100점 정량 채점 (PASS ≥ 90, 게이트 항목 0점이면 총점 무관 FAIL)
-
- # 항목 배점 점수 규칙 채점표 실물 — 100점 만점, 90점 합격
+
+ # 항목 배점 점수 규칙 G1 빌드/타입체크 25 빌드 exit 0 → pass=25 / fail=0 게이트 G2 테스트 통과 25 npm run test → pass=25 / fail=0 게이트 G3 안전 위반 0건 15 검증 훅(파괴 명령·비밀 노출) 위반 0=15 / 1+=0 게이트 4 린트 10 pass=10 / fail=0 5 회귀 없음 10 기존 스위트 전부 유지=10 / 깨짐=0 G1 빌드/타입체크 25 빌드 성공=25 / 실패=0 게이트 G2 테스트 통과 25 전체 테스트 성공=25 / 실패=0 게이트 G3 안전 위반 0건 15 위험 명령·비밀 노출 0건=15 / 1건이라도=0 게이트 4 린트 10 통과=10 / 실패=0 5 회귀 없음 10 기존 테스트 전부 유지=10 / 하나라도 깨짐=0 6 커버리지 5 변경 전 대비 유지·상승=5 / 하락=0 7 anti-slop 10 check-slop 0 ERROR=10 / 1+ ERROR=0 7 디자인 규칙 (anti-slop) 10 검사 도구 오류 0건=10 / 1건 이상=0
- “좋은 결과”를 주관에 두지 않는다 — 게이트 항목(G1·G2·G3)이 0점이면 나머지 만점이어도 총점 무관 FAIL.
+
+ “좋은 결과”를 주관에 맡기지 않는다 — 전부 명령어 실행 결과로 판정되는 항목뿐이다.
+ 게이트(G1~G3)는 거부권 — 하나라도 0점이면 나머지 만점이어도 FAIL. 총점은 그 다음 이야기다.
+
-
+
-
+
04 · EVALUATOR-DRIVEN 게이트
- Evaluator Driven 평가 게이트 — “구현했다”는 주장을 믿지 않는다
- 항목마다 실제 코드와 대조·테스트해 0~100점으로 채점하고, 전 항목이 95점 이상이 될 때까지 개발↔검증 루프를 자동으로 돌리는 하네스 서브시스템.
-
-
- 간극을 닫는 3장치
-
-
-
-
-
- 쓴다 안 쓴다 스펙이 명확하고 항목 단위 보증이 필요할 때 한 줄 수정·오타 등 자명한 변경 구현 주장이 많아 사람이 전수 확인 버거울 때 탐색·리서치처럼 정답 없는 작업 루프를 자동 수렴시키고 싶을 때 테스트 인프라 없는 프로토타입 (test축 0 → 95 불가)
-
+ Evaluator 게이트 — 95점까지 돈다
+
+ 쓸 때: 스펙이 명확하고 확인할 항목이 많을 때 — 사람이 전수 검사하기 버거운 작업.
+ 안 쓸 때: 한 줄 수정 · 정답 없는 리서치 · 테스트가 아예 없는 프로토타입(95점 자체가 불가능).
+
-
+
-
-
-
- 04 · EVALUATOR-DRIVEN 게이트 루프
- 게이트가 열릴 때까지 되먹인다
- Spec 분해 → 개발/빌드(Generator) → 체크리스트 전수 열거 → 2렌즈 채점(read-only) → 게이트 전 항목 ≥95? — 아니오→deficiencies 피드백→개발 / 예→DONE.
-
-
-
-
+
+ 04 · 루프 가드레일
+ 루프의 3중 안전장치
+
+ 자동 루프는 폭주 장치가 아니다 — 상한 · 교착 감지 · 역할 분리, 세 안전장치가 반드시 함께 간다.
+ 기록이 파일에 있으니 세션이 끊겨도 다음 바퀴가 이어진다 — 대화가 아니라 파일이 루프의 기억이다.
+
+
- 
-
+
-
-
-
- 04 · EVALUATOR-DRIVEN 게이트 루브릭
- 5축 100점, 2렌즈 min — 테스트 없으면 95는 불가능
-
- 축 배점 만점 조건 exists 25 실제 구현 존재 — 스텁·TODO 아님 match 25 코드가 claim과 의미적으로 일치 test 25 verify 명령 실제 실행 → 통과 contract 15 타입·에러·입력검증·인가 경계 안전 no-regress 10 기존 통과 항목·기능 퇴행 없음
- 2렌즈: code-match(정적 대조) × test-pass(실제 실행) → min(두 렌즈). 한 렌즈만 후해도 통과 못 함.
-
-
+
+ 04 · 루브릭
+ 채점표의 다섯 질문
+
+ 어려운 채점이 아니다 — 코드 리뷰어가 늘 하던 다섯 가지 질문에 점수를 붙였을 뿐이다.
+ 각 항목은 앞 장의 규칙대로 두 번 따로 채점해 낮은 점수만 인정 — 후한 채점자가 있어도 소용없다.
+
+
- 
-
+
-
- 04 · EVALUATOR-DRIVEN 게이트 통합
- 하네스 통합 — Stop 게이트가 거짓 완료를 물리적으로 막는다
- 3장의 훅(요청→보증)에 4장의 점수가 꽂힌 형태 — 검사 내용이 정규식에서 점수로.
-
- SCORE.json 상태 Stop(응답 종료) 시 동작 파일 없음 통과 (일반 세션 무영향) active: false 통과 (루프 종료·게이트 해제) active: true + 전 항목 ≥ threshold 통과 active: true + 미만 항목 존재 차단 (exit 2) — “다 됐다” 선언 불가 score 누락 (malformed) 차단 (fail-closed)
- 구성 6표면: 계약(conformance.md 정본) · 커맨드(/evaluator-driven) · 스킬(spec-checklist) · 에이전트(conformance-scorer, read-only) · 워크플로(spec-conformance-loop.js) · 훅(conformance-gate.sh, active-only).
+
+ 04 · 하네스 통합
+ 거짓 완료를 물리적으로 막는다
+
+ 3장의 훅에 4장의 점수를 꽂았다 — 검사 내용이 “금지 패턴”에서 “점수 미달”로 진화했을 뿐, 구조는 같다.
+ 핵심 원칙은 fail-closed — 확인할 수 없으면 통과가 아니라 차단이 기본값이다.
+
+
-
+
-
-
-
- 04 · 워크스루
- Evaluator Driven 평가 게이트 워크스루 — 쿠폰 적용 API, 2회차 수렴
-
-
- 관찰: 전체 재생성이 아니라 미달 항목만 재작업. 종료는 선언이 아니라 게이트 해제.
-
-
+
+ 04 · 워크스루
+ 실전 워크스루 — 쿠폰 API 채점
+
+ 92점도 차단이다 — “거의 됐다”는 없다. 합격선 아래는 전부 같은 “미달”이다.
+ 통과한 항목은 건드리지 않는다 — 전체 재생성이 아니라 미달만 고치니 빠르고, 좋은 것을 망치지 않는다.
+
+
- 
-
+
-
+
04 · 성숙도
- EDD(Evaluation-Driven Development, 평가 주도 개발) 성숙도 — 바이브 체크에서 완전한 루프까지
-
- 레벨 상태 · 목격 현상 다음 행동 LV0 바이브 체크 채팅창에서 몇 개 돌려보고 배포 — 반응적 루프 전부 실패 20~50건으로 골든셋 v1 LV1 골든셋+수동 채점 “3번·7번 케이스가 깨졌다”가 처음 가능. 채점이 병목 규칙화 가능한 것부터 코드 grader LV2 자동 채점 실험 속도 급상승. “정확하지만 불친절한 답”이 샘 루브릭 명문화 → Judge (인간 일치율 먼저) LV3 Judge+CI 게이트 배포 전 검출 정착. Judge 자기강화 리스크 등장 Judge 재교정 프로세스화, 런타임 확장 LV4 런타임 가드레일 드리프트가 지표로 잡힘. 단 “달았다≠막힌다” 가드레일 자체를 공격셋으로 평가 LV5 완전한 EDD 루프 실패→분류→최초 결정 지점 수정→골든셋 환류가 규정으로 회전 eval 스위트 포화 관리·갱신
- 하네스 사다리(3장 Lv0~5)를 오른 팀은 EDD 사다리의 부품을 이미 절반 갖고 있다 — 지금 팀이 어느 줄인지 찾고 그 줄 오른쪽 칸부터 시작한다.
+ Eval에도 성숙도 계단이 있다
+
+ 3장의 하네스 계단을 오른 팀은 이 계단의 부품을 이미 절반 갖고 있다 — 두 사다리는 같이 오른다.
+ 지금 팀이 어느 단인지 찾고 바로 다음 한 단만 오르면 된다 — LV0이라면 실패 사례 20건 모으는 것부터.
+
+
-
+
+
+
+
+
+
+
+
+
+
+
-
+
- 
-
+
-
+
+ 05 · 원리
+ 프롬프트와 Eval은 앞뒷면
+
+ 성공 기준을 한 문장으로 먼저 쓰라 — “좋은 답변” 같은 말은 지시로도 채점 기준으로도 못 쓴다.
+ 프롬프트 한 줄 수정도 코드처럼 게이트를 통과시켜라 — CLAUDE.md 변경도 결국 프롬프트 변경이다.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
05 · 시작
- 시작 로드맵 — 완벽을 기다리지 마라
-
- 단계 내용 시작 로드맵 — 완벽을 기다리지 마라
+
+ 단계 무엇을 Step 0
일찍 시작 수백 개 불필요 — 실제 실패에서 뽑은 20~50개면 강력하게 출발. 초기 변경은 효과가 커서 작은 표본으로도 신호가 잡힌다. 미룰수록 만들기 어려워진다 Step 1
이미 하는 것에서 릴리스 전 수동 체크, 버그 트래커, CS 큐가 최고 소재 — 사용자 실패를 테스트 케이스로 Step 2
모호하지 않게 품질 기준 = 전문가 2명이 독립적으로 같은 합/불 판정. 명세의 모호함은 곧 지표의 노이즈. 참조 해법(모든 grader 통과 출력)으로 풀이 가능성과 grader를 동시 증명 Step 3
균형 일어나야 하는 케이스와 일어나면 안 되는 케이스 모두 — 치우친 eval은 치우친 최적화를 낳는다 ⓪ 일찍 시작 수백 개 필요 없다 — 실제 실패 20~50개면 충분히 출발. 미룰수록 만들기 어려워진다 ① 이미 하는 것에서 릴리스 전 수동 체크 · 버그 목록 · 고객 문의가 최고의 소재 — 실패를 테스트 케이스로 ② 모호하지 않게 좋은 기준 = 전문가 2명이 따로 봐도 같은 합/불 판정. 애매한 기준은 채점 노이즈가 된다 ③ 균형 있게 “일어나야 할 것”과 “일어나면 안 될 것” 둘 다 — 한쪽만 재면 한쪽으로만 좋아진다
- 신호 해석: 프론티어 모델이 pass@100(100번 시도 중 1회 이상 통과)에서 0% = 에이전트가 아니라 태스크가 깨진 신호.
+
+ 완벽한 채점 세트를 기다리지 마라 — 오늘의 실패 20건이 다음 달의 계획 100장보다 낫다.
+ 덤 신호 하나: 최고 모델이 100번 시도해도 0% 통과라면 — AI가 아니라 문제 자체가 깨진 것이다.
+
-
+
-
-
+
+ 05 · 실전 사례
+ 실전 팀의 채점 프레임, 세 질문
+
+ 순서가 중요하다 — ① 회귀부터 막고, ② 이행을 확인하고, ③ 품질은 마지막에 다듬는다.
+ 성패는 시작 시점이 아니라 태도 — 늦게 시작한 Bolt도 3개월이면 됐지만, 평가를 “부속물”로 다루면 영영 안 된다.
+
+
+
+
+
+
+
+
+
-
+
-
-
-
- 05 · 배포 판정
- CI 게이트와 버전 비교 — 숫자로 배포를 결정
-
-
- 통계 주의: 표본을 키우면 사소한 차이도 “유의” — p값만으로 결정 금지, 효과 크기·비용·지연을 함께.
-
-
+
+ 05 · 배포 판정
+ 배포로 가는 세 관문
+
+ 통계 함정 하나: 케이스를 많이 모으면 사소한 차이도 “유의미”해 보인다 — 차이의 크기와 비용·속도를 함께 보라.
+ 전부 한 번에 아니어도 된다 — 관문 ①(PR마다 재채점)만 걸어도 회귀의 대부분을 잡는다.
+
+
- 
-
+
-
-
-
- 05 · 런타임 방어선
- 가드레일 — “달았다”와 “막힌다”는 다르다
-
-
- 결론: 가드레일 자체를 공격 데이터셋으로 정기 평가 (recall·차단률 분리 측정).
-
-
+
+ 05 · 런타임 방어선
+ 가드레일 — 달았다 ≠ 막힌다
+
+ 가드레일도 시험을 쳐야 한다 — 공격 문제집(레드팀 셋)으로 정기 평가하고, 탐지율과 차단율은 따로 재라.
+ 판정을 “통과/차단” 둘로만 두지 마라 — “계획을 고쳐서 계속”이라는 세 번째 선택지가 정상 업무를 살린다.
+
+
- 
-
+
-
+
05 · 마지막 규율
- 트랜스크립트를 읽어라 — 점수를 액면 그대로 믿지 마라
- 누군가 eval 내부를 파고 트랜스크립트를 읽기 전까지, 점수를 믿지 마라. 실패는 공정해 보여야 한다 — 무엇을 왜 틀렸는지 명확해야.
-
-
- grader는 우회·해킹에 강해야 — 통과하려면 실제로 풀어야지, 허점을 악용해선 안 된다. 각 trial은 깨끗한 환경에서(공유 상태는 성능을 인위적으로 부풀린다).
+ 점수를 믿지 말고, 기록을 읽어라
+
+ 규율: 점수를 액면 그대로 믿지 마라 — 트랜스크립트(실제 대화·실행 기록)를 직접 읽기 전까지는.
+ 실패는 공정해 보여야 한다 — 무엇을 왜 틀렸는지 기록만 보고도 설명될 것.
+
+
-
-
-
-
-
+
-
-
-
- 01 · 정의
-바이브 코딩 = 계획도, 리뷰도, 테스트도 없는 원샷
-research·plan·execute·review·ship이 하나의 “설명”으로 뭉개진다 — 게이트 0개. 여기서 하네스(harness, 모델을 감싸 제어하는 실행 환경)가 하는 일은 그 게이트를 되살리는 것이다.
--
-
-
-
-
01 · 패러다임
-프롬프트 → 컨텍스트 → 하네스
-각 단계는 이전을 포함하며 확장한다 — 단일 입력 최적화(프롬프트) ⊂ 정보 환경 구성(컨텍스트) ⊂ 런타임 환경 설계(하네스).
+ -
+
+
-
-
-프롬프트로 해
-
-
-
@@ -3381,20 +3386,23 @@ 01 · 구조적 실패
-프롬프트로 해결할 수 없는 문제 6가지 — “더 잘 말하기”로는 안 되는 것들
-| 문제 | 프롬프트 / 컨텍스트로는 (지시) | 하네스로는 (구조) |
|---|---|---|
| 자기 평가 편향 | “비판적으로 리뷰하라” → 자기 코드를 칭찬 | Generator와 Evaluator를 물리적으로 분리 |
| 컨텍스트 불안 | 컴팩션(compaction, 컨텍스트 압축)해도 “마무리해야 한다”는 충동 | 컨텍스트 리셋 + 파일 핸드오프(handoff, 상태 인계) |
| 규칙 망각 | CLAUDE.md에 써도 47번째에서 잊힘 | Hook / 린터로 자동 감지 |
| 아키텍처 침범 | “이 레이어만 수정하라” → 편의상 위반 | allowed_tools로 도구 레벨 접근 차단 |
| 무한 루프 | “5번 이상 시도 금지” → 무시 가능 | max_iterations로 하드 리밋 강제 |
| 상태 유실 | 세션 전환 시 이전 맥락 소실 | 파일 기반 핸드오프로 상태 영속화 |
왼쪽 열은 전부 “지시”, 오른쪽 열은 전부 “구조”다. 지시는 확률적으로 지켜지고 구조는 물리적으로 강제된다. · 출처: 사내 발표자료(Noah, 2026.04)
+ -
+
+
프롬프트로 해
-
-
-
-
-
- 01 · 대가
- 감으로 짠 코드의 대가 — 반응적 루프
- 리스크의 본질은 “코드가 틀린다”가 아니라 — 틀렸는지 아닌지를 팀이 모른다는 데 있다. Eval·게이트 없는 팀에서 목격되는 3가지:
-
-
-
-
+
-
+
+
-
@@ -3438,37 +3439,52 @@ 감으로 짠 코드의 대가 — 반응적
-
-
-
- 01 · 타이밍
- 왜 지금인가 — 세 가지 변화의 수렴
-
-
- → 그래서 필요한 것이 “모델을 감싸는 시스템” — 하네스다. (2장에서 계속)
-
-
+
+ 01 · 대가
+ 고쳐도 고쳐도 제자리인 이유
+
+ 검증 게이트가 없는 팀의 증상: 버그를 프로덕션에서야 발견하고, “느낌이 나빠졌다” 논쟁만 반복 — 진짜 리스크는 틀렸는지조차 모른다.
+ Eval과 게이트는 이 뺑뺑이를 끊는 장치다 — 뒤 챕터에서 직접 만든다.
+
+
-
+
+
+
+
+
+
+
+
+
+
-
+
-
-
+
-
- 02 · 코드로 증명된 정의
- Harness = Tools + Knowledge + Observation + Action + Permissions
+
+ 02 · 정의
+ 하네스 = 엔진을 뺀 자동차 전부
+
+ 모델은 엔진 — 아무리 좋아도 핸들·브레이크 없이는 도로에 못 나간다. 하네스는 모델을 뺀 나머지 전부다.
+ 이 자동차 비유가 강의 전체를 관통한다 — 모델(엔진)은 그대로 두고, 차(하네스)를 설계한다.
+
+
-
+
-
-
-
- 02 · 심장
- The Agent Loop — 제약·검증이 주입되는 자리
-while True:
- response = await api.stream(messages, tools)
- if response.stop_reason != "tool_use":
- break # 모델이 작업 완료
- for call in response.tool_uses:
- # 권한검사 → PreToolUse 훅 → 실행 → PostToolUse 훅
- result = await harness.execute_tool(call)
- messages.append(tool_results)
- 도구 실행 한 번에 권한 검사 → PreToolUse 훅 → 실행 → PostToolUse 훅 파이프라인이 끼어든다. 이 지점이 프로젝트 제약과 검증 훅이 주입되는 자리.
-
-
+
+ 02 · 구성요소
+ 하네스를 이루는 다섯 가지
+
+ 거창한 프레임워크가 아니다 — 이미 Claude Code를 쓸 때마다 만나는 다섯 가지가 곧 하네스다.
+ 이 다섯 개의 손잡이를 의도적으로 조정하는 것이 하네스 엔지니어링이다.
+
+
-
-
+
-
-
-
- 02 · 3기둥
- 하네스의 세 기둥 — 제약 · 피드백 루프 · 상태 관리
-
-
- 가장 효과적인 하네스: 자동 검증 → 독립 리뷰어 → 인간 체크포인트의 계층 조합.
-
-
-
- 제약이 생산성을 낮출 것 같지만, 탐색 공간을 줄여 에이전트를 집중시킨다.
-
+
+ 02 · 심장
+ 에이전트의 심장, Agent Loop
+
+ Claude Code가 일하는 방식 = 이 루프의 반복 — 생각하고, 도구 쓰고, 결과 보고, 다시 생각한다.
+ 규칙을 CLAUDE.md에 쓰면 “기억”이지만, ③에 걸면 “강제”다 — 매 바퀴마다 자동 적용된다.
+
-
+
+
+
+
+
+
+
+
+
+
+
+
-
- 02 · 해부
- 서브시스템 → 3기둥 매핑 (OpenHarness 10+) — 하나의 디렉토리 = 하나의 책임
-
- 기둥 서브시스템 역할 제약 permissions/ · hooks/ 멀티레벨 권한 모드, 경로 규칙, 커맨드 차단, PreToolUse 차단 훅(exit 2 = 비정상 종료로 도구 호출 차단) 피드백 skills/ · coordinator/ · tools/ 스킬 로딩, 서브에이전트 검증·조율, 결과 관찰 상태 memory/ · tasks/ · prompts/ · config/ MEMORY.md 크로스세션, 백그라운드 태스크, 컨텍스트 압축 코어 engine/ · tools/ Agent Loop, 43개 도구(Pydantic 입력 검증 — 파이썬 데이터 검증 라이브러리)
- 권한 3모드: Default 쓰기·실행 전 확인 Auto 전부 허용(샌드박스) Plan Mode 모든 쓰기 차단
- 주의: 3기둥 매핑은 강의 프레임에 따른 해석이며 OpenHarness 공식 분류가 아님. · 출처: openharness-analysis.html
+
+ 02 · 제약 실전
+ 권한 모드 — 가장 쉬운 제약
+
+ 권한 모드는 하네스 제약의 첫 손잡이 — Shift+Tab으로 즉시 전환한다.
+ 원칙: 처음엔 Default, 익숙해지면 Accept Edits, Bypass는 컨테이너 같은 격리 환경에서만.
+
+
-
+
-
+
02 · 실증 A/B
- 하네스는 로컬 모델의 행동을 실제로 바꾸는가
- A/B 테스트(대조 실험): 동일 opencode 1.17.15 + qwen3.6:35b(ollama · 로컬 모델 실행 런타임)에, 하네스 유무만 다르게 두고 위반 유도 명령 7종(S0–S6)을 주입.
-
-
- → 다음 페이지: S0–S6 전체 결과 매트릭스 (CONTROL vs HARNESS). 출처: harnessreport.pdf (2026-07-08).
+ 정말 행동이 바뀔까? — 실험
+
+ 같은 모델이라도 하네스를 입히면 위험 명령이 게이트에서 막힌다 — 프롬프트가 아니라 구조가 행동을 바꾼다.
+ 로컬 오픈소스 모델로 재현한 실험(2026-07, harness-report) — 7가지 시나리오 전체 결과는 다음 페이지에.
+
+
-
+
-
- 02 · 실증 결과
+ 7가지 위험 명령, 결과는?
+
+ 쉬운 위험(비밀키·개인정보)은 모델 스스로도 거부한다 — 하지만 DB 삭제·강제 푸시 같은 진짜 사고는 하네스 게이트만 막았다.
+ 못 막은 1건(디자인 규칙)도 교훈 — 훅이 경고만 하면 안 막힌다. 차단(exit 2)까지 가야 강제다.
+
+
-
+
-
+
02 · 실증 해석
- 하네스가 값을 하는 3지점, 무의미한 2지점
-
-
- 한계 고지: 실시간 차단 훅은 Claude Code 전용. opencode에선 AGENTS.md(소프트)+pre-commit(하드) 2계층만.
+ 하네스, 어디에 걸어야 하나
+
+ 게이트는 비용이다 — 모델이 스스로 잘하는 곳엔 걸지 말고, 뚫리는 세 곳에 집중하라.
+ 도구마다 지원은 다르다 — 실시간 차단 훅은 Claude Code 전용, 다른 도구에선 커밋 게이트로 대신한다.
+
+
-
+
-
+
-
-
-
- 03 · 로드맵
- 성숙도 모델 — 5분부터 시작하라
-
- 레벨 무엇 · 시간 효과 Lv.0 프롬프트만 · 0분 기본 Lv.1 CLAUDE.md · 5분 반복 실수 30%↓ Lv.2 역할 분리 · 30분 자기 평가 편향 제거 Lv.3 Hook 자동 검증 · 1시간 규칙 망각 해결 Lv.4 파일 핸드오프 · 2시간 대규모 작업 가능 Lv.5 실패 패턴 축적 · 지속 하네스 자체가 진화
- 본질은 레벨이 아니라 습관 — “이번만 고치기”가 아니라 시스템에 규칙을 추가하기.
-
-
-
- 진입 장벽은 낮다 — Lv.1은 5분 투자로 반복 실수를 약 30% 줄인다.
-
+
+ 03 · 용어
+ 먼저, 용어부터
+
+ 용어 (풀 네이밍) 쉬운 설명 성숙도 모델 (Maturity Model) 한 번에 완성이 아니라 Lv.0→5 계단으로 올라가는 도입 로드맵 커맨드 (Command) 사람이 /이름 으로 직접 부르는 저장된 프롬프트 — 예: /commit 스킬 (Skill) 상황이 맞으면 AI가 스스로 꺼내 읽는 절차서 파일 (SKILL.md) 서브에이전트 (Subagent) 별도 기억 공간에서 일하는 보조 AI — 격리 실행·독립 검증에 쓴다 PLAN.md 구현 전에 체크박스로 쓰는 계획서 — 리뷰가 이 문장 그대로 결과와 대조한다 핸드오프 (Handoff) 세션을 끝내기 전 진행 상황을 파일로 남겨 다음 세션이 이어받게 하는 인수인계 토큰 (Token) AI가 글을 읽고 쓰는 최소 단위(대략 글자 몇 개) — 사용량과 요금이 토큰 수로 계산된다
+
+ 커맨드·스킬·서브에이전트 전부 이미 Claude Code에 들어 있는 부품이다 — 새로 만드는 게 아니라 켜는 것.
-
-
+
-
-
+
+ 03 · 로드맵
+ 성숙도 모델 — 5분부터 시작하라
+
+ 본질은 레벨이 아니라 습관 — “이번만 고치기”가 아니라 시스템에 규칙을 추가하기.
+ 한 계단씩이면 된다 — 다음 장부터 각 계단을 실제 설정으로 만들어 본다.
+
+
+
+
+
+
+
+
+
-
+
-
+
03 · 부품 · CLAUDE.md 심화
- 무엇을 넣고, 무엇을 빼는가 — CLAUDE.md는 항상 로드된다
-
- 넣는다 (안정적 규칙) 뺀다 → 어디로 무엇을 넣고, 무엇을 빼는가
+
+ 넣는다 — CLAUDE.md에 뺀다 — 더 좋은 자리로 빌드·테스트·실행 명령어 (pnpm test) 스타일 가이드 전문 → 린터/포매터 + 훅이 강제 코드 컨벤션 핵심 몇 줄 (“ESM 사용, CJS 금지”) 조건부로만 필요한 긴 지식 → 스킬의 점진적 공개 “완료의 정의(definition of done)” 반드시 강제될 것 → settings.json·훅 (설정 1줄이 “NEVER” 문장보다 결정적) 절대 건드리면 안 되는 경로 (마이그레이션·시크릿) 자주 바뀌는 임시 컨텍스트 → 세션 프롬프트로 — 경로 종속 규칙 → .claude/rules/*.md + paths glob (지연 로드) 빌드·테스트 명령어 (npm test) 긴 스타일 가이드 → 린터·포매터가 자동 강제 컨벤션 핵심 몇 줄 가끔만 필요한 긴 지식 → 스킬 (필요할 때만 로드) 완료의 정의 (“테스트 녹색이면 끝”) 반드시 강제할 것 → 설정·훅 (설정 1줄이 “절대 금지” 문장보다 세다) 건드리면 안 되는 경로 오늘만 필요한 맥락 → 그냥 대화로 — 특정 폴더 전용 규칙 → 규칙 파일 분리 (.claude/rules/)
- 운영 원칙: 같은 실수 2회 = 규칙 후보. 조건부 지식과 강제 규칙은 CLAUDE.md가 아닌 다른 계층으로 뺀다.
+
+ 운영 원칙: 같은 실수 2번 = 규칙 후보.
+ 단, 강제할 수 있는 것은 문장으로 쓰지 말고 설정·훅으로 옮겨라 — 문장은 잊혀도 설정은 남는다.
+
-
+
-
+
-
+
-
-
-
- 03 · 핵심 원리
- 요청(request)과 보증(guarantee)은 다르다
-
-
- “반드시 일어나야 하는 것은 훅에 속한다. 가드레일은 훅에 넣고, 그 외 전부는 정중한 제안이다.”
- 판별 질문 하나: “어기면 곤란한가?” → 예 = 훅/설정, 아니오 = CLAUDE.md/스킬
-
-
+
+ 03 · 핵심 원리
+ 요청과 보증은 다르다
+
+ “반드시 일어나야 하는 것은 훅에 속한다 — 그 외 전부는 정중한 부탁이다.”
+ 판별 질문 하나: 어기면 곤란한가? 예 = 훅·설정(보증 층), 아니오 = CLAUDE.md·스킬(요청 층).
+
+
-
-
+
-
+
-
-
-
- 03 · 부품 · 역할 분리
- 역할 분리 — Generator ≠ Evaluator
-
-
- 완료 판정 = 단언이 아니라 증거 (테스트 출력·명령 반환값·스크린샷).
-
-
+
+ 03 · 부품 · 역할 분리
+ 만든 AI에게 채점을 맡기지 마라
+
+ 완료 판정은 단언이 아니라 증거 — 테스트 출력·명령 반환값·스크린샷이 말하게 하라.
+ 주의: 리뷰어에게 “문제를 찾으라”고만 하면 없는 문제도 만들어 온다 — 정확성·요구사항 위반만 필수로.
+
+
-
-
+
+
-
+
-
+
-
+
03 · 실물 케이스 1
- 실물 하네스 해부 — carve-harness (이 프로젝트가 실제 사용 중)
-
- 계층 위치 · 트리거 성격 실물 ① — 이 자료를 만든 하네스
+
+ 계층 위치 하는 일 강제 훅 (8개 활성) .claude/hooks/ + settings.json 툴 호출/프롬프트 자동 · 결정적 (차단은 exit 2) Squad 에이전트 (9종) .claude/agents/ · /squad 단일 책임 위임 워크플로 스킬 .claude/skills/ · /carve-* 절차 자동화 (자연어 또는 커맨드) 계약·규칙 문서 루트 *.md (flight-rules · 운영 규칙 문서) 에이전트·훅이 참조 · 단일 진실 출처 강제 훅 (8개) .claude/hooks/ 위험 명령·비밀 파일을 자동 차단 — 어길 수 없음 (exit 2) 전문 에이전트 (9종) .claude/agents/ · /squad 리뷰·QA·보안 등 역할별로 분리해 위임 워크플로 스킬 .claude/skills/ 커밋·핸드오프 같은 반복 절차를 말 한마디로 규칙 문서 루트 *.md 훅과 에이전트가 참조하는 기준 문서
- 대표 훅: block-destructive(포크밤·rm -rf 차단) · protect-secrets(.env·키 차단) · pre-push-test(테스트 실패 시 push 차단) · anti-slop(시각 산출물 검사) · precompact-handoff(압축 전 상태 인계). 슬림화 결정: 11→8 훅.
+
+ 훅 예시: 파괴 명령 차단 · 비밀 파일 보호 · 테스트 실패 시 push 차단 — 오늘 배운 부품이 전부 실전 가동 중이다.
+ 그리고 지금 보고 있는 이 슬라이드 덱도 이 하네스 안에서 만들어졌다.
+
-
+
-
+
03 · 실물 케이스 2
- 프로젝트 필수 하네스 구성 — API 포탈 (Spring + React)
-
- 묶음 무엇 핵심 자산 실물 ② — 실무 프로젝트에 얹는 순서
+
+ 순서 무엇을 왜 ① 에이전트 정의 back/front/gateway 역할 분리 AGENTS.md 계층 (폴더별) ② 스킬 세션 인계·결정 기록 handoff · changelog(decision-ledger) ③ 훅 포맷·린트·머지금지·커밋룰 hooks.json + commitlint (exit 2) ④ 서브에이전트 타입·예외·시크릿·인증 검증 security-reviewer · evaluator ⑤ 룰/가드레일 검증 가능한 규칙 md rules/ (common·java·react·ts) ⑥⑦⑧ 토큰 관리 · SDD 킷 · 게이트웨이 검증 codesight+LSP · GSD · e2e ① 규칙 문서 (CLAUDE.md · rules/) 팀 규칙을 파일로 — 모든 세션에 자동 적용 ② 훅 — 포맷·린트·커밋 검사 “반드시”를 자동 강제 (exit 2 차단) ③ 스킬 — 세션 인계·결정 기록 반복 절차를 말 한마디로 ④ 검증 에이전트 — 보안·타입 검사 만든 쪽과 검사하는 쪽 분리 ⑤ 역할 분리 — 백/프론트 폴더별 정의 영역 밖 코드를 건드리지 않게 ⑥ 그 다음에야 — 컨텍스트 절약·명세 킷 등 기본기가 자리 잡은 뒤의 고급 부품
- 3기둥 위에 토큰 관리·SDD(명세 주도 개발)·게이트웨이 검증을 얹어 완성 — 한 번에 다 하지 말 것. (GSD = Get Shit Done, SDD 킷 · LSP = Language Server Protocol · e2e = 종단간 테스트)
+
+ 실제 사례: 사내 API 포탈(Spring + React)에 이 순서 그대로 적용했다.
+ 핵심은 순서 — 한 번에 다 하지 말 것. 성숙도 계단처럼 하나씩 얹는다.
+
-
+
-
- 03 · 토큰 매니지먼트
- 토큰 관리 — 광고 수치와 실효 절감은 다르다
-
- 도구 줄이는 대상 광고 절감 비고 headroom API 페이로드(grep·diff)를 프록시에서 압축 47~92% (중앙값 54%) RTK(동반 압축 툴킷) 번들 포함 caveman Claude 자체 출력을 전보문처럼 축약(telegraphic) 50~75% /caveman lite|full|ultra LSP 코드 탐색을 심볼 좌표로 축소 (LSP = Language Server Protocol, 언어 서버 프로토콜) 정의 43× · 참조 2.1× 중대형·리팩토링용 codesight 세션 시작 구조 파악을 압축 맵 1개로 세션당 6.8× LSP와 상호보완
- 실측 경고: 독립 실측(614M 토큰)에서 headroom+rtk+caveman 합산 실효 절감은 약 3.7% — 비용 대부분이 cache_create·output이라 이 도구들이 손대지 않는 스트림이기 때문. 광고 수치는 “특정 스트림 단독 최선값”이다.
+
+ 03 · 토큰 관리
+ 토큰 절약 — 광고와 실측은 다르다
+
+ 광고 수치는 “특정 구간의 최선값” — 전체 청구서 기준으론 몇 %에 그치기도 한다. 도입 전 반드시 실측.
+ 도구보다 습관이 먼저 — 요약해서 가져오고, 조사는 서브에이전트에 맡기고, 컨텍스트가 차면 새 세션.
+
+
-
+
-
+
03 · 하네스의 진화
- Harness Handbook — “어디를 고칠지”가 병목이다. 진화는 “수정을 생성”만이 아니라 “어디를 고칠지 아는” 표현에 달렸다. (arXiv:2607.13285)
+ AI에게 코드 지도를 쥐여줘라
+
+ 진짜 병목은 “어디를 고칠지” — 위치를 찾는 능력이 코드를 짜는 능력보다 먼저다.
+ 실무 적용: 프로젝트 구조 문서(코드 맵)를 하네스에 넣어라 — 품질은 오르고 토큰은 준다.
+
+
-
-
+
+
-
-
+
-
+
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
- 04 · 기초
- Eval의 3가지 본질 — 전통 테스트와 다른 점
-
-
- 셋 중 하나라도 빠지면 전통 QA의 연장선일 뿐, eval이 아니다.
-
-
+
+ 04 · 두 축
+ EDD의 두 축 — 만들고, 채점하고
+
+ 두 축은 분리하되(만든 쪽이 채점하지 않는다 — 32페이지), 나란히 기른다 — 채점 코드도 기능 코드와 같은 정성으로.
+ 축이 하나뿐인 팀이 반응적 루프에 빠진다 — 만드는 속도만 늘고, 확인하는 속도는 그대로라서.
+
+
-
-
+
-
- 04 · 채점기
- 채점기 3종 — 대체재가 아니라 조합이다 (가능하면 결정적으로, 필요하면 LLM으로, 검증엔 사람)
-
- 종류 방법 강점 약점 코드형 정규식 매칭, 이진 테스트, 정적 분석, 결과·도구 호출 검증 빠르고 저렴, 객관적, 재현 가능 유효한 변형에 뻣뻣, 뉘앙스 부족 모델형
LLM-as-Judge 루브릭 점수, 자연어 assertion, 쌍대 비교, 다중 Judge 합의 유연, 뉘앙스 포착, 개방형 처리 비결정적, 비쌈, 사람과 보정 필요 사람형 SME(Subject Matter Expert, 해당 분야 전문가) 리뷰, 스팟체크, A/B, 평가자 간 일치도 정답지 수준 품질 비싸고 느림, 스케일 한계
- 원칙: 경로가 아니라 결과를 채점 — 에이전트는 설계자가 예상 못한 유효한 접근을 찾는다. 창의성을 벌하지 마라. 다구성 태스크엔 부분 점수.
+
+ 04 · 기초
+ Eval은 테스트와 무엇이 다른가
+
+ Eval = AI 시대의 테스트 — 답이 매번 조금씩 달라지는 시스템은 통계로 채점할 수밖에 없다.
+ 셋 중 하나라도 빠지면 전통 QA의 연장선일 뿐 — 특히 “성공 정의” 없이 시작하지 마라.
+
+
-
+
-
+
-
-
-
- 04 · 온프레미스
- 3계층 게이트 — 결정론 → LLM-as-Judge → 사람
-
- 게이트 수단 통과 조건 1 결정론 컴파일·테스트·Checkstyle(스타일 검사)·ArchUnit(아키텍처 규칙 테스트)·grep 전부 통과 (하드) 2 LLM-as-Judge 루브릭 G-Eval(LLM 루브릭 채점) · 로컬 vLLM(오픈 LLM 추론 서버), guided_json(출력 스키마 강제) 점수 ≥ 7.0 3 사람 수동 라벨 교정·엣지케이스만
- 임계값은 유형별 허용 실패율: convention 5% / correctness 3% / domain_safety 0% (Judge 출력은 guided_json 스키마 강제 + temperature 0).
-
-
+
+ 04 · 3층 게이트
+ 게이트는 3층 — 기계, AI, 사람
+
+ 순서가 곧 비용 — 기계로 막을 수 있는 건 전부 기계로, AI와 사람은 그 다음 층에 아껴 쓴다.
+ 실패 허용도도 유형별로: 스타일 5% · 정답성 3% · 안전 규칙 0% — 안전은 단 한 건도 예외 없다.
+
+
-
-
+
-
+
04 · 결정론 우선
- 규칙으로 표현 가능한 것은 전부 결정론적으로 — Run-AI 규약 → 자동 검사 매핑
-
- 규약 검사 방법 규칙을 기계 검사로 번역하기
+
+ 팀 규칙 (사람의 문장) 기계 검사 (자동 실행) 컴파일 / 전체 테스트 ./gradlew compileJava test 코드 스타일·네이밍 ./gradlew checkstyleMain 컨트롤러의 엔티티 직접 반환 금지 ArchUnit: @RestController 반환 타입에 @Entity 금지 @ManyToOne/@OneToMany는 LAZY ArchUnit + grep: FetchType.EAGER 금지 패턴 AI 호출은 컨트롤러 스레드 동기 금지 grep: 컨트롤러 패키지에서 동기 호출 부재 확인 Flyway(DB 마이그레이션 도구) 기존 마이그레이션 미수정 CI diff 검사: V*.sql 기존 파일 변경 시 실패 빌드가 깨지지 않는다 컴파일 + 전체 테스트 자동 실행 코드 스타일 통일 스타일 검사기(린터) 자동 실행 화면 계층에서 DB 객체 직접 반환 금지 구조 검사 도구가 반환 타입을 확인 무거운 호출은 응답 경로에서 금지 금지 패턴 검색(grep)으로 확인 과거 마이그레이션 파일 수정 금지 CI가 기존 파일 변경을 감지하면 실패
- 2장 A/B의 S4(마이그레이션 불변)가 여기서 회수된다 — 모델이 모르는 팀 관례를 결정론 검사가 강제한다.
+
+ 포인트: 팀 관례를 문장이 아니라 기계 검사로 번역했다 — 사람이 안 봐도 걸린다.
+ 2장 실험에서 하네스만 막았던 “마이그레이션 수정”이 바로 이 검사다 — 실험이 실전 규칙으로 회수됐다.
+
-
+
-
+
04 · 실물 채점표
- evaluation-criteria — 100점 정량 채점 (PASS ≥ 90, 게이트 항목 0점이면 총점 무관 FAIL)
-
- # 항목 배점 점수 규칙 채점표 실물 — 100점 만점, 90점 합격
+
+ # 항목 배점 점수 규칙 G1 빌드/타입체크 25 빌드 exit 0 → pass=25 / fail=0 게이트 G2 테스트 통과 25 npm run test → pass=25 / fail=0 게이트 G3 안전 위반 0건 15 검증 훅(파괴 명령·비밀 노출) 위반 0=15 / 1+=0 게이트 4 린트 10 pass=10 / fail=0 5 회귀 없음 10 기존 스위트 전부 유지=10 / 깨짐=0 G1 빌드/타입체크 25 빌드 성공=25 / 실패=0 게이트 G2 테스트 통과 25 전체 테스트 성공=25 / 실패=0 게이트 G3 안전 위반 0건 15 위험 명령·비밀 노출 0건=15 / 1건이라도=0 게이트 4 린트 10 통과=10 / 실패=0 5 회귀 없음 10 기존 테스트 전부 유지=10 / 하나라도 깨짐=0 6 커버리지 5 변경 전 대비 유지·상승=5 / 하락=0 7 anti-slop 10 check-slop 0 ERROR=10 / 1+ ERROR=0 7 디자인 규칙 (anti-slop) 10 검사 도구 오류 0건=10 / 1건 이상=0
- “좋은 결과”를 주관에 두지 않는다 — 게이트 항목(G1·G2·G3)이 0점이면 나머지 만점이어도 총점 무관 FAIL.
+
+ “좋은 결과”를 주관에 맡기지 않는다 — 전부 명령어 실행 결과로 판정되는 항목뿐이다.
+ 게이트(G1~G3)는 거부권 — 하나라도 0점이면 나머지 만점이어도 FAIL. 총점은 그 다음 이야기다.
+
-
+
-
+
04 · EVALUATOR-DRIVEN 게이트
- Evaluator Driven 평가 게이트 — “구현했다”는 주장을 믿지 않는다
- 항목마다 실제 코드와 대조·테스트해 0~100점으로 채점하고, 전 항목이 95점 이상이 될 때까지 개발↔검증 루프를 자동으로 돌리는 하네스 서브시스템.
-
-
- 간극을 닫는 3장치
-
-
-
-
-
- 쓴다 안 쓴다 스펙이 명확하고 항목 단위 보증이 필요할 때 한 줄 수정·오타 등 자명한 변경 구현 주장이 많아 사람이 전수 확인 버거울 때 탐색·리서치처럼 정답 없는 작업 루프를 자동 수렴시키고 싶을 때 테스트 인프라 없는 프로토타입 (test축 0 → 95 불가)
-
+ Evaluator 게이트 — 95점까지 돈다
+
+ 쓸 때: 스펙이 명확하고 확인할 항목이 많을 때 — 사람이 전수 검사하기 버거운 작업.
+ 안 쓸 때: 한 줄 수정 · 정답 없는 리서치 · 테스트가 아예 없는 프로토타입(95점 자체가 불가능).
+
-
+
-
-
-
- 04 · EVALUATOR-DRIVEN 게이트 루프
- 게이트가 열릴 때까지 되먹인다
- Spec 분해 → 개발/빌드(Generator) → 체크리스트 전수 열거 → 2렌즈 채점(read-only) → 게이트 전 항목 ≥95? — 아니오→deficiencies 피드백→개발 / 예→DONE.
-
-
-
-
+
+ 04 · 루프 가드레일
+ 루프의 3중 안전장치
+
+ 자동 루프는 폭주 장치가 아니다 — 상한 · 교착 감지 · 역할 분리, 세 안전장치가 반드시 함께 간다.
+ 기록이 파일에 있으니 세션이 끊겨도 다음 바퀴가 이어진다 — 대화가 아니라 파일이 루프의 기억이다.
+
+
-
-
+
-
-
-
- 04 · EVALUATOR-DRIVEN 게이트 루브릭
- 5축 100점, 2렌즈 min — 테스트 없으면 95는 불가능
-
- 축 배점 만점 조건 exists 25 실제 구현 존재 — 스텁·TODO 아님 match 25 코드가 claim과 의미적으로 일치 test 25 verify 명령 실제 실행 → 통과 contract 15 타입·에러·입력검증·인가 경계 안전 no-regress 10 기존 통과 항목·기능 퇴행 없음
- 2렌즈: code-match(정적 대조) × test-pass(실제 실행) → min(두 렌즈). 한 렌즈만 후해도 통과 못 함.
-
-
+
+ 04 · 루브릭
+ 채점표의 다섯 질문
+
+ 어려운 채점이 아니다 — 코드 리뷰어가 늘 하던 다섯 가지 질문에 점수를 붙였을 뿐이다.
+ 각 항목은 앞 장의 규칙대로 두 번 따로 채점해 낮은 점수만 인정 — 후한 채점자가 있어도 소용없다.
+
+
-
-
+
-
- 04 · EVALUATOR-DRIVEN 게이트 통합
- 하네스 통합 — Stop 게이트가 거짓 완료를 물리적으로 막는다
- 3장의 훅(요청→보증)에 4장의 점수가 꽂힌 형태 — 검사 내용이 정규식에서 점수로.
-
- SCORE.json 상태 Stop(응답 종료) 시 동작 파일 없음 통과 (일반 세션 무영향) active: false 통과 (루프 종료·게이트 해제) active: true + 전 항목 ≥ threshold 통과 active: true + 미만 항목 존재 차단 (exit 2) — “다 됐다” 선언 불가 score 누락 (malformed) 차단 (fail-closed)
- 구성 6표면: 계약(conformance.md 정본) · 커맨드(/evaluator-driven) · 스킬(spec-checklist) · 에이전트(conformance-scorer, read-only) · 워크플로(spec-conformance-loop.js) · 훅(conformance-gate.sh, active-only).
+
+ 04 · 하네스 통합
+ 거짓 완료를 물리적으로 막는다
+
+ 3장의 훅에 4장의 점수를 꽂았다 — 검사 내용이 “금지 패턴”에서 “점수 미달”로 진화했을 뿐, 구조는 같다.
+ 핵심 원칙은 fail-closed — 확인할 수 없으면 통과가 아니라 차단이 기본값이다.
+
+
-
+
-
-
-
- 04 · 워크스루
- Evaluator Driven 평가 게이트 워크스루 — 쿠폰 적용 API, 2회차 수렴
-
-
- 관찰: 전체 재생성이 아니라 미달 항목만 재작업. 종료는 선언이 아니라 게이트 해제.
-
-
+
+ 04 · 워크스루
+ 실전 워크스루 — 쿠폰 API 채점
+
+ 92점도 차단이다 — “거의 됐다”는 없다. 합격선 아래는 전부 같은 “미달”이다.
+ 통과한 항목은 건드리지 않는다 — 전체 재생성이 아니라 미달만 고치니 빠르고, 좋은 것을 망치지 않는다.
+
+
-
-
+
-
+
04 · 성숙도
- EDD(Evaluation-Driven Development, 평가 주도 개발) 성숙도 — 바이브 체크에서 완전한 루프까지
-
- 레벨 상태 · 목격 현상 다음 행동 LV0 바이브 체크 채팅창에서 몇 개 돌려보고 배포 — 반응적 루프 전부 실패 20~50건으로 골든셋 v1 LV1 골든셋+수동 채점 “3번·7번 케이스가 깨졌다”가 처음 가능. 채점이 병목 규칙화 가능한 것부터 코드 grader LV2 자동 채점 실험 속도 급상승. “정확하지만 불친절한 답”이 샘 루브릭 명문화 → Judge (인간 일치율 먼저) LV3 Judge+CI 게이트 배포 전 검출 정착. Judge 자기강화 리스크 등장 Judge 재교정 프로세스화, 런타임 확장 LV4 런타임 가드레일 드리프트가 지표로 잡힘. 단 “달았다≠막힌다” 가드레일 자체를 공격셋으로 평가 LV5 완전한 EDD 루프 실패→분류→최초 결정 지점 수정→골든셋 환류가 규정으로 회전 eval 스위트 포화 관리·갱신
- 하네스 사다리(3장 Lv0~5)를 오른 팀은 EDD 사다리의 부품을 이미 절반 갖고 있다 — 지금 팀이 어느 줄인지 찾고 그 줄 오른쪽 칸부터 시작한다.
+ Eval에도 성숙도 계단이 있다
+
+ 3장의 하네스 계단을 오른 팀은 이 계단의 부품을 이미 절반 갖고 있다 — 두 사다리는 같이 오른다.
+ 지금 팀이 어느 단인지 찾고 바로 다음 한 단만 오르면 된다 — LV0이라면 실패 사례 20건 모으는 것부터.
+
+
-
+
+
+
+
+
+
+
+
+
+
+
-
+
-
-
+
-
+
+ 05 · 원리
+ 프롬프트와 Eval은 앞뒷면
+
+ 성공 기준을 한 문장으로 먼저 쓰라 — “좋은 답변” 같은 말은 지시로도 채점 기준으로도 못 쓴다.
+ 프롬프트 한 줄 수정도 코드처럼 게이트를 통과시켜라 — CLAUDE.md 변경도 결국 프롬프트 변경이다.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
05 · 시작
- 시작 로드맵 — 완벽을 기다리지 마라
-
- 단계 내용 시작 로드맵 — 완벽을 기다리지 마라
+
+ 단계 무엇을 Step 0
일찍 시작 수백 개 불필요 — 실제 실패에서 뽑은 20~50개면 강력하게 출발. 초기 변경은 효과가 커서 작은 표본으로도 신호가 잡힌다. 미룰수록 만들기 어려워진다 Step 1
이미 하는 것에서 릴리스 전 수동 체크, 버그 트래커, CS 큐가 최고 소재 — 사용자 실패를 테스트 케이스로 Step 2
모호하지 않게 품질 기준 = 전문가 2명이 독립적으로 같은 합/불 판정. 명세의 모호함은 곧 지표의 노이즈. 참조 해법(모든 grader 통과 출력)으로 풀이 가능성과 grader를 동시 증명 Step 3
균형 일어나야 하는 케이스와 일어나면 안 되는 케이스 모두 — 치우친 eval은 치우친 최적화를 낳는다 ⓪ 일찍 시작 수백 개 필요 없다 — 실제 실패 20~50개면 충분히 출발. 미룰수록 만들기 어려워진다 ① 이미 하는 것에서 릴리스 전 수동 체크 · 버그 목록 · 고객 문의가 최고의 소재 — 실패를 테스트 케이스로 ② 모호하지 않게 좋은 기준 = 전문가 2명이 따로 봐도 같은 합/불 판정. 애매한 기준은 채점 노이즈가 된다 ③ 균형 있게 “일어나야 할 것”과 “일어나면 안 될 것” 둘 다 — 한쪽만 재면 한쪽으로만 좋아진다
- 신호 해석: 프론티어 모델이 pass@100(100번 시도 중 1회 이상 통과)에서 0% = 에이전트가 아니라 태스크가 깨진 신호.
+
+ 완벽한 채점 세트를 기다리지 마라 — 오늘의 실패 20건이 다음 달의 계획 100장보다 낫다.
+ 덤 신호 하나: 최고 모델이 100번 시도해도 0% 통과라면 — AI가 아니라 문제 자체가 깨진 것이다.
+
-
+
-
-
+
+ 05 · 실전 사례
+ 실전 팀의 채점 프레임, 세 질문
+
+ 순서가 중요하다 — ① 회귀부터 막고, ② 이행을 확인하고, ③ 품질은 마지막에 다듬는다.
+ 성패는 시작 시점이 아니라 태도 — 늦게 시작한 Bolt도 3개월이면 됐지만, 평가를 “부속물”로 다루면 영영 안 된다.
+
+
+
+
+
+
+
+
+
-
+
-
-
-
- 05 · 배포 판정
- CI 게이트와 버전 비교 — 숫자로 배포를 결정
-
-
- 통계 주의: 표본을 키우면 사소한 차이도 “유의” — p값만으로 결정 금지, 효과 크기·비용·지연을 함께.
-
-
+
+ 05 · 배포 판정
+ 배포로 가는 세 관문
+
+ 통계 함정 하나: 케이스를 많이 모으면 사소한 차이도 “유의미”해 보인다 — 차이의 크기와 비용·속도를 함께 보라.
+ 전부 한 번에 아니어도 된다 — 관문 ①(PR마다 재채점)만 걸어도 회귀의 대부분을 잡는다.
+
+
-
-
+
-
-
-
- 05 · 런타임 방어선
- 가드레일 — “달았다”와 “막힌다”는 다르다
-
-
- 결론: 가드레일 자체를 공격 데이터셋으로 정기 평가 (recall·차단률 분리 측정).
-
-
+
+ 05 · 런타임 방어선
+ 가드레일 — 달았다 ≠ 막힌다
+
+ 가드레일도 시험을 쳐야 한다 — 공격 문제집(레드팀 셋)으로 정기 평가하고, 탐지율과 차단율은 따로 재라.
+ 판정을 “통과/차단” 둘로만 두지 마라 — “계획을 고쳐서 계속”이라는 세 번째 선택지가 정상 업무를 살린다.
+
+
-
-
+
-
+
05 · 마지막 규율
- 트랜스크립트를 읽어라 — 점수를 액면 그대로 믿지 마라
- 누군가 eval 내부를 파고 트랜스크립트를 읽기 전까지, 점수를 믿지 마라. 실패는 공정해 보여야 한다 — 무엇을 왜 틀렸는지 명확해야.
-
-
- grader는 우회·해킹에 강해야 — 통과하려면 실제로 풀어야지, 허점을 악용해선 안 된다. 각 trial은 깨끗한 환경에서(공유 상태는 성능을 인위적으로 부풀린다).
+ 점수를 믿지 말고, 기록을 읽어라
+
+ 규율: 점수를 액면 그대로 믿지 마라 — 트랜스크립트(실제 대화·실행 기록)를 직접 읽기 전까지는.
+ 실패는 공정해 보여야 한다 — 무엇을 왜 틀렸는지 기록만 보고도 설명될 것.
+
+
-
-
-
@@ -3438,37 +3439,52 @@ 감으로 짠 코드의 대가 — 반응적
+
+
-
-
+
-
-
- 01 · 대가
-감으로 짠 코드의 대가 — 반응적 루프
-리스크의 본질은 “코드가 틀린다”가 아니라 — 틀렸는지 아닌지를 팀이 모른다는 데 있다. Eval·게이트 없는 팀에서 목격되는 3가지:
--
-
+
+
-
감으로 짠 코드의 대가 — 반응적
-
-
-
- 01 · 타이밍
- 왜 지금인가 — 세 가지 변화의 수렴
-
-
- → 그래서 필요한 것이 “모델을 감싸는 시스템” — 하네스다. (2장에서 계속)
-
-
+
+ 01 · 대가
+ 고쳐도 고쳐도 제자리인 이유
+
+ 검증 게이트가 없는 팀의 증상: 버그를 프로덕션에서야 발견하고, “느낌이 나빠졌다” 논쟁만 반복 — 진짜 리스크는 틀렸는지조차 모른다.
+ Eval과 게이트는 이 뺑뺑이를 끊는 장치다 — 뒤 챕터에서 직접 만든다.
+
+
-
-
-
-
+
-
+
-
- 01 · 타이밍
-왜 지금인가 — 세 가지 변화의 수렴
--
-
→ 그래서 필요한 것이 “모델을 감싸는 시스템” — 하네스다. (2장에서 계속)
-
+
01 · 대가
+고쳐도 고쳐도 제자리인 이유
+
+ 검증 게이트가 없는 팀의 증상: 버그를 프로덕션에서야 발견하고, “느낌이 나빠졌다” 논쟁만 반복 — 진짜 리스크는 틀렸는지조차 모른다.
+ Eval과 게이트는 이 뺑뺑이를 끊는 장치다 — 뒤 챕터에서 직접 만든다. +
+ Eval과 게이트는 이 뺑뺑이를 끊는 장치다 — 뒤 챕터에서 직접 만든다. +
+
+
+
+
+
+
+
+
+
-
+
+
-
+
-
+
+
+
+
-
+
-
+
-
+
-
+
-
-
-
-
+02 · 코드로 증명된 정의
-Harness = Tools + Knowledge + Observation + Action + Permissions
+
+
02 · 정의
+하네스 = 엔진을 뺀 자동차 전부
+
+ 모델은 엔진 — 아무리 좋아도 핸들·브레이크 없이는 도로에 못 나간다. 하네스는 모델을 뺀 나머지 전부다.
+ 이 자동차 비유가 강의 전체를 관통한다 — 모델(엔진)은 그대로 두고, 차(하네스)를 설계한다. +
+ 이 자동차 비유가 강의 전체를 관통한다 — 모델(엔진)은 그대로 두고, 차(하네스)를 설계한다. +
-
-
-
+
-
+
-
- 02 · 심장
-The Agent Loop — 제약·검증이 주입되는 자리
-while True: - response = await api.stream(messages, tools) - if response.stop_reason != "tool_use": - break # 모델이 작업 완료 - for call in response.tool_uses: - # 권한검사 → PreToolUse 훅 → 실행 → PostToolUse 훅 - result = await harness.execute_tool(call) - messages.append(tool_results)-
도구 실행 한 번에 권한 검사 → PreToolUse 훅 → 실행 → PostToolUse 훅 파이프라인이 끼어든다. 이 지점이 프로젝트 제약과 검증 훅이 주입되는 자리.
-
+
02 · 구성요소
+하네스를 이루는 다섯 가지
+
+ 거창한 프레임워크가 아니다 — 이미 Claude Code를 쓸 때마다 만나는 다섯 가지가 곧 하네스다.
+ 이 다섯 개의 손잡이를 의도적으로 조정하는 것이 하네스 엔지니어링이다. +
+ 이 다섯 개의 손잡이를 의도적으로 조정하는 것이 하네스 엔지니어링이다. +
-
-
-
-
-
- 제약이 생산성을 낮출 것 같지만, 탐색 공간을 줄여 에이전트를 집중시킨다.
-
+
+
-
- 02 · 3기둥
-하네스의 세 기둥 — 제약 · 피드백 루프 · 상태 관리
--
-
가장 효과적인 하네스: 자동 검증 → 독립 리뷰어 → 인간 체크포인트의 계층 조합.
-
+
02 · 심장
+에이전트의 심장, Agent Loop
+
+ Claude Code가 일하는 방식 = 이 루프의 반복 — 생각하고, 도구 쓰고, 결과 보고, 다시 생각한다.
+ 규칙을 CLAUDE.md에 쓰면 “기억”이지만, ③에 걸면 “강제”다 — 매 바퀴마다 자동 적용된다.
+ 규칙을 CLAUDE.md에 쓰면 “기억”이지만, ③에 걸면 “강제”다 — 매 바퀴마다 자동 적용된다.
+
+
+
+
+
+
+
+
+
+
-
-
-
-
+02 · 해부
-서브시스템 → 3기둥 매핑 (OpenHarness 10+) — 하나의 디렉토리 = 하나의 책임
-| 기둥 | 서브시스템 | 역할 |
|---|---|---|
| 제약 | permissions/ · hooks/ | 멀티레벨 권한 모드, 경로 규칙, 커맨드 차단, PreToolUse 차단 훅(exit 2 = 비정상 종료로 도구 호출 차단) |
| 피드백 | skills/ · coordinator/ · tools/ | 스킬 로딩, 서브에이전트 검증·조율, 결과 관찰 |
| 상태 | memory/ · tasks/ · prompts/ · config/ | MEMORY.md 크로스세션, 백그라운드 태스크, 컨텍스트 압축 |
| 코어 | engine/ · tools/ | Agent Loop, 43개 도구(Pydantic 입력 검증 — 파이썬 데이터 검증 라이브러리) |
권한 3모드: Default 쓰기·실행 전 확인 Auto 전부 허용(샌드박스) Plan Mode 모든 쓰기 차단
-주의: 3기둥 매핑은 강의 프레임에 따른 해석이며 OpenHarness 공식 분류가 아님. · 출처: openharness-analysis.html
+
+
02 · 제약 실전
+권한 모드 — 가장 쉬운 제약
+
+ 권한 모드는 하네스 제약의 첫 손잡이 — Shift+Tab으로 즉시 전환한다.
+ 원칙: 처음엔 Default, 익숙해지면 Accept Edits, Bypass는 컨테이너 같은 격리 환경에서만. +
+ 원칙: 처음엔 Default, 익숙해지면 Accept Edits, Bypass는 컨테이너 같은 격리 환경에서만. +
-
+
+02 · 실증 A/B
-하네스는 로컬 모델의 행동을 실제로 바꾸는가
-A/B 테스트(대조 실험): 동일 opencode 1.17.15 + qwen3.6:35b(ollama · 로컬 모델 실행 런타임)에, 하네스 유무만 다르게 두고 위반 유도 명령 7종(S0–S6)을 주입.
--
-
→ 다음 페이지: S0–S6 전체 결과 매트릭스 (CONTROL vs HARNESS). 출처: harnessreport.pdf (2026-07-08).
+정말 행동이 바뀔까? — 실험
+
+ 같은 모델이라도 하네스를 입히면 위험 명령이 게이트에서 막힌다 — 프롬프트가 아니라 구조가 행동을 바꾼다.
+ 로컬 오픈소스 모델로 재현한 실험(2026-07, harness-report) — 7가지 시나리오 전체 결과는 다음 페이지에. +
+ 로컬 오픈소스 모델로 재현한 실험(2026-07, harness-report) — 7가지 시나리오 전체 결과는 다음 페이지에. +
-
-
+
+
02 · 실증 결과
+7가지 위험 명령, 결과는?
+
+ 쉬운 위험(비밀키·개인정보)은 모델 스스로도 거부한다 — 하지만 DB 삭제·강제 푸시 같은 진짜 사고는 하네스 게이트만 막았다.
+ 못 막은 1건(디자인 규칙)도 교훈 — 훅이 경고만 하면 안 막힌다. 차단(exit 2)까지 가야 강제다. +
+ 못 막은 1건(디자인 규칙)도 교훈 — 훅이 경고만 하면 안 막힌다. 차단(exit 2)까지 가야 강제다. +
-
+
+02 · 실증 해석
-하네스가 값을 하는 3지점, 무의미한 2지점
--
-
한계 고지: 실시간 차단 훅은 Claude Code 전용. opencode에선 AGENTS.md(소프트)+pre-commit(하드) 2계층만.
+하네스, 어디에 걸어야 하나
+
+ 게이트는 비용이다 — 모델이 스스로 잘하는 곳엔 걸지 말고, 뚫리는 세 곳에 집중하라.
+ 도구마다 지원은 다르다 — 실시간 차단 훅은 Claude Code 전용, 다른 도구에선 커밋 게이트로 대신한다. +
+ 도구마다 지원은 다르다 — 실시간 차단 훅은 Claude Code 전용, 다른 도구에선 커밋 게이트로 대신한다. +
-
+
+
+
-
-
-
-
-
-
- 진입 장벽은 낮다 — Lv.1은 5분 투자로 반복 실수를 약 30% 줄인다.
-
+
-
-
-
- 03 · 로드맵
-성숙도 모델 — 5분부터 시작하라
-| 레벨 | 무엇 · 시간 | 효과 |
|---|---|---|
| Lv.0 | 프롬프트만 · 0분 | 기본 |
| Lv.1 | CLAUDE.md · 5분 | 반복 실수 30%↓ |
| Lv.2 | 역할 분리 · 30분 | 자기 평가 편향 제거 |
| Lv.3 | Hook 자동 검증 · 1시간 | 규칙 망각 해결 |
| Lv.4 | 파일 핸드오프 · 2시간 | 대규모 작업 가능 |
| Lv.5 | 실패 패턴 축적 · 지속 | 하네스 자체가 진화 |
본질은 레벨이 아니라 습관 — “이번만 고치기”가 아니라 시스템에 규칙을 추가하기.
-
+
+
+
03 · 용어
+먼저, 용어부터
+| 용어 (풀 네이밍) | 쉬운 설명 |
|---|---|
| 성숙도 모델 (Maturity Model) | 한 번에 완성이 아니라 Lv.0→5 계단으로 올라가는 도입 로드맵 |
| 커맨드 (Command) | 사람이 /이름 으로 직접 부르는 저장된 프롬프트 — 예: /commit |
| 스킬 (Skill) | 상황이 맞으면 AI가 스스로 꺼내 읽는 절차서 파일 (SKILL.md) |
| 서브에이전트 (Subagent) | 별도 기억 공간에서 일하는 보조 AI — 격리 실행·독립 검증에 쓴다 |
| PLAN.md | 구현 전에 체크박스로 쓰는 계획서 — 리뷰가 이 문장 그대로 결과와 대조한다 |
| 핸드오프 (Handoff) | 세션을 끝내기 전 진행 상황을 파일로 남겨 다음 세션이 이어받게 하는 인수인계 |
| 토큰 (Token) | AI가 글을 읽고 쓰는 최소 단위(대략 글자 몇 개) — 사용량과 요금이 토큰 수로 계산된다 |
+ 커맨드·스킬·서브에이전트 전부 이미 Claude Code에 들어 있는 부품이다 — 새로 만드는 게 아니라 켜는 것.
-
+
+
-
-
+
+
+
+
+
+
+ 03 · 로드맵
+성숙도 모델 — 5분부터 시작하라
+
+ 본질은 레벨이 아니라 습관 — “이번만 고치기”가 아니라 시스템에 규칙을 추가하기.
+ 한 계단씩이면 된다 — 다음 장부터 각 계단을 실제 설정으로 만들어 본다. +
+ + 한 계단씩이면 된다 — 다음 장부터 각 계단을 실제 설정으로 만들어 본다. +
+
-
+
-
+
-
+
03 · 부품 · CLAUDE.md 심화
-무엇을 넣고, 무엇을 빼는가 — CLAUDE.md는 항상 로드된다
-| 넣는다 (안정적 규칙) | 뺀다 → 어디로 |
|---|
| 넣는다 — CLAUDE.md에 | 뺀다 — 더 좋은 자리로 |
|---|---|
| 빌드·테스트·실행 명령어 (pnpm test) | 스타일 가이드 전문 → 린터/포매터 + 훅이 강제 |
| 코드 컨벤션 핵심 몇 줄 (“ESM 사용, CJS 금지”) | 조건부로만 필요한 긴 지식 → 스킬의 점진적 공개 |
| “완료의 정의(definition of done)” | 반드시 강제될 것 → settings.json·훅 (설정 1줄이 “NEVER” 문장보다 결정적) |
| 절대 건드리면 안 되는 경로 (마이그레이션·시크릿) | 자주 바뀌는 임시 컨텍스트 → 세션 프롬프트로 |
| — | 경로 종속 규칙 → .claude/rules/*.md + paths glob (지연 로드) |
| 빌드·테스트 명령어 (npm test) | 긴 스타일 가이드 → 린터·포매터가 자동 강제 |
| 컨벤션 핵심 몇 줄 | 가끔만 필요한 긴 지식 → 스킬 (필요할 때만 로드) |
| 완료의 정의 (“테스트 녹색이면 끝”) | 반드시 강제할 것 → 설정·훅 (설정 1줄이 “절대 금지” 문장보다 세다) |
| 건드리면 안 되는 경로 | 오늘만 필요한 맥락 → 그냥 대화로 |
| — | 특정 폴더 전용 규칙 → 규칙 파일 분리 (.claude/rules/) |
운영 원칙: 같은 실수 2회 = 규칙 후보. 조건부 지식과 강제 규칙은 CLAUDE.md가 아닌 다른 계층으로 뺀다.
+
+ 운영 원칙: 같은 실수 2번 = 규칙 후보.
+ 단, 강제할 수 있는 것은 문장으로 쓰지 말고 설정·훅으로 옮겨라 — 문장은 잊혀도 설정은 남는다. +
-+ 단, 강제할 수 있는 것은 문장으로 쓰지 말고 설정·훅으로 옮겨라 — 문장은 잊혀도 설정은 남는다. +
-
+
-
+
-
+
-
-
-
+
-
+
-
- 03 · 핵심 원리
-요청(request)과 보증(guarantee)은 다르다
--
-
“반드시 일어나야 하는 것은 훅에 속한다. 가드레일은 훅에 넣고, 그 외 전부는 정중한 제안이다.”
- 판별 질문 하나: “어기면 곤란한가?” → 예 = 훅/설정, 아니오 = CLAUDE.md/스킬
-
+
03 · 핵심 원리
+요청과 보증은 다르다
+
+ “반드시 일어나야 하는 것은 훅에 속한다 — 그 외 전부는 정중한 부탁이다.”
+ 판별 질문 하나: 어기면 곤란한가? 예 = 훅·설정(보증 층), 아니오 = CLAUDE.md·스킬(요청 층). +
+ 판별 질문 하나: 어기면 곤란한가? 예 = 훅·설정(보증 층), 아니오 = CLAUDE.md·스킬(요청 층). +
-
+
-
+
-
+
-
-
-
+
-
+
-
- 03 · 부품 · 역할 분리
-역할 분리 — Generator ≠ Evaluator
--
-
완료 판정 = 단언이 아니라 증거 (테스트 출력·명령 반환값·스크린샷).
-
+
03 · 부품 · 역할 분리
+만든 AI에게 채점을 맡기지 마라
+
+ 완료 판정은 단언이 아니라 증거 — 테스트 출력·명령 반환값·스크린샷이 말하게 하라.
+ 주의: 리뷰어에게 “문제를 찾으라”고만 하면 없는 문제도 만들어 온다 — 정확성·요구사항 위반만 필수로. +
+ 주의: 리뷰어에게 “문제를 찾으라”고만 하면 없는 문제도 만들어 온다 — 정확성·요구사항 위반만 필수로. +
+
-
+
-
+
-
+
-
+
03 · 실물 케이스 1
-실물 하네스 해부 — carve-harness (이 프로젝트가 실제 사용 중)
-| 계층 | 위치 · 트리거 | 성격 |
|---|
| 계층 | 위치 | 하는 일 |
|---|---|---|
| 강제 훅 (8개 활성) | .claude/hooks/ + settings.json | 툴 호출/프롬프트 자동 · 결정적 (차단은 exit 2) |
| Squad 에이전트 (9종) | .claude/agents/ · /squad | 단일 책임 위임 |
| 워크플로 스킬 | .claude/skills/ · /carve-* | 절차 자동화 (자연어 또는 커맨드) |
| 계약·규칙 문서 | 루트 *.md (flight-rules · 운영 규칙 문서) | 에이전트·훅이 참조 · 단일 진실 출처 |
| 강제 훅 (8개) | .claude/hooks/ | 위험 명령·비밀 파일을 자동 차단 — 어길 수 없음 (exit 2) |
| 전문 에이전트 (9종) | .claude/agents/ · /squad | 리뷰·QA·보안 등 역할별로 분리해 위임 |
| 워크플로 스킬 | .claude/skills/ | 커밋·핸드오프 같은 반복 절차를 말 한마디로 |
| 규칙 문서 | 루트 *.md | 훅과 에이전트가 참조하는 기준 문서 |
대표 훅: block-destructive(포크밤·rm -rf 차단) · protect-secrets(.env·키 차단) · pre-push-test(테스트 실패 시 push 차단) · anti-slop(시각 산출물 검사) · precompact-handoff(압축 전 상태 인계). 슬림화 결정: 11→8 훅.
+
+ 훅 예시: 파괴 명령 차단 · 비밀 파일 보호 · 테스트 실패 시 push 차단 — 오늘 배운 부품이 전부 실전 가동 중이다.
+ 그리고 지금 보고 있는 이 슬라이드 덱도 이 하네스 안에서 만들어졌다. +
-+ 그리고 지금 보고 있는 이 슬라이드 덱도 이 하네스 안에서 만들어졌다. +
-
+
-
+
-
+
-
+
-
+
-
+
03 · 실물 케이스 2
-프로젝트 필수 하네스 구성 — API 포탈 (Spring + React)
-| 묶음 | 무엇 | 핵심 자산 |
|---|
| 순서 | 무엇을 | 왜 |
|---|---|---|
| ① 에이전트 정의 | back/front/gateway 역할 분리 | AGENTS.md 계층 (폴더별) |
| ② 스킬 | 세션 인계·결정 기록 | handoff · changelog(decision-ledger) |
| ③ 훅 | 포맷·린트·머지금지·커밋룰 | hooks.json + commitlint (exit 2) |
| ④ 서브에이전트 | 타입·예외·시크릿·인증 검증 | security-reviewer · evaluator |
| ⑤ 룰/가드레일 | 검증 가능한 규칙 md | rules/ (common·java·react·ts) |
| ⑥⑦⑧ | 토큰 관리 · SDD 킷 · 게이트웨이 검증 | codesight+LSP · GSD · e2e |
| ① | 규칙 문서 (CLAUDE.md · rules/) | 팀 규칙을 파일로 — 모든 세션에 자동 적용 |
| ② | 훅 — 포맷·린트·커밋 검사 | “반드시”를 자동 강제 (exit 2 차단) |
| ③ | 스킬 — 세션 인계·결정 기록 | 반복 절차를 말 한마디로 |
| ④ | 검증 에이전트 — 보안·타입 검사 | 만든 쪽과 검사하는 쪽 분리 |
| ⑤ | 역할 분리 — 백/프론트 폴더별 정의 | 영역 밖 코드를 건드리지 않게 |
| ⑥ | 그 다음에야 — 컨텍스트 절약·명세 킷 등 | 기본기가 자리 잡은 뒤의 고급 부품 |
3기둥 위에 토큰 관리·SDD(명세 주도 개발)·게이트웨이 검증을 얹어 완성 — 한 번에 다 하지 말 것. (GSD = Get Shit Done, SDD 킷 · LSP = Language Server Protocol · e2e = 종단간 테스트)
+
+ 실제 사례: 사내 API 포탈(Spring + React)에 이 순서 그대로 적용했다.
+ 핵심은 순서 — 한 번에 다 하지 말 것. 성숙도 계단처럼 하나씩 얹는다. +
-+ 핵심은 순서 — 한 번에 다 하지 말 것. 성숙도 계단처럼 하나씩 얹는다. +
-
-
-
-
+03 · 토큰 매니지먼트
-토큰 관리 — 광고 수치와 실효 절감은 다르다
-| 도구 | 줄이는 대상 | 광고 절감 | 비고 |
|---|---|---|---|
| headroom | API 페이로드(grep·diff)를 프록시에서 압축 | 47~92% (중앙값 54%) | RTK(동반 압축 툴킷) 번들 포함 |
| caveman | Claude 자체 출력을 전보문처럼 축약(telegraphic) | 50~75% | /caveman lite|full|ultra |
| LSP | 코드 탐색을 심볼 좌표로 축소 (LSP = Language Server Protocol, 언어 서버 프로토콜) | 정의 43× · 참조 2.1× | 중대형·리팩토링용 |
| codesight | 세션 시작 구조 파악을 압축 맵 1개로 | 세션당 6.8× | LSP와 상호보완 |
실측 경고: 독립 실측(614M 토큰)에서 headroom+rtk+caveman 합산 실효 절감은 약 3.7% — 비용 대부분이 cache_create·output이라 이 도구들이 손대지 않는 스트림이기 때문. 광고 수치는 “특정 스트림 단독 최선값”이다.
+
+
03 · 토큰 관리
+토큰 절약 — 광고와 실측은 다르다
+
+ 광고 수치는 “특정 구간의 최선값” — 전체 청구서 기준으론 몇 %에 그치기도 한다. 도입 전 반드시 실측.
+ 도구보다 습관이 먼저 — 요약해서 가져오고, 조사는 서브에이전트에 맡기고, 컨텍스트가 차면 새 세션. +
+ 도구보다 습관이 먼저 — 요약해서 가져오고, 조사는 서브에이전트에 맡기고, 컨텍스트가 차면 새 세션. +
-
-
+
+03 · 하네스의 진화
-Harness Handbook — “어디를 고칠지”가 병목이다. 진화는 “수정을 생성”만이 아니라 “어디를 고칠지 아는” 표현에 달렸다. (arXiv:2607.13285)
+AI에게 코드 지도를 쥐여줘라
+
+ 진짜 병목은 “어디를 고칠지” — 위치를 찾는 능력이 코드를 짜는 능력보다 먼저다.
+ 실무 적용: 프로젝트 구조 문서(코드 맵)를 하네스에 넣어라 — 품질은 오르고 토큰은 준다. +
+ 실무 적용: 프로젝트 구조 문서(코드 맵)를 하네스에 넣어라 — 품질은 오르고 토큰은 준다. +
+
-
-
+
+
+
+
-
+
-
+
-
-
+
+
+
+
+
+
+
+
+
+
-
-
-
+
-
+
-
- 04 · 기초
-Eval의 3가지 본질 — 전통 테스트와 다른 점
--
-
셋 중 하나라도 빠지면 전통 QA의 연장선일 뿐, eval이 아니다.
-
+
04 · 두 축
+EDD의 두 축 — 만들고, 채점하고
+
+ 두 축은 분리하되(만든 쪽이 채점하지 않는다 — 32페이지), 나란히 기른다 — 채점 코드도 기능 코드와 같은 정성으로.
+ 축이 하나뿐인 팀이 반응적 루프에 빠진다 — 만드는 속도만 늘고, 확인하는 속도는 그대로라서. +
+ 축이 하나뿐인 팀이 반응적 루프에 빠진다 — 만드는 속도만 늘고, 확인하는 속도는 그대로라서. +
-
-
-
-
+04 · 채점기
-채점기 3종 — 대체재가 아니라 조합이다 (가능하면 결정적으로, 필요하면 LLM으로, 검증엔 사람)
-| 종류 | 방법 | 강점 | 약점 |
|---|---|---|---|
| 코드형 | 정규식 매칭, 이진 테스트, 정적 분석, 결과·도구 호출 검증 | 빠르고 저렴, 객관적, 재현 가능 | 유효한 변형에 뻣뻣, 뉘앙스 부족 |
| 모델형 LLM-as-Judge | 루브릭 점수, 자연어 assertion, 쌍대 비교, 다중 Judge 합의 | 유연, 뉘앙스 포착, 개방형 처리 | 비결정적, 비쌈, 사람과 보정 필요 |
| 사람형 | SME(Subject Matter Expert, 해당 분야 전문가) 리뷰, 스팟체크, A/B, 평가자 간 일치도 | 정답지 수준 품질 | 비싸고 느림, 스케일 한계 |
원칙: 경로가 아니라 결과를 채점 — 에이전트는 설계자가 예상 못한 유효한 접근을 찾는다. 창의성을 벌하지 마라. 다구성 태스크엔 부분 점수.
+
+
04 · 기초
+Eval은 테스트와 무엇이 다른가
+
+ Eval = AI 시대의 테스트 — 답이 매번 조금씩 달라지는 시스템은 통계로 채점할 수밖에 없다.
+ 셋 중 하나라도 빠지면 전통 QA의 연장선일 뿐 — 특히 “성공 정의” 없이 시작하지 마라. +
+ 셋 중 하나라도 빠지면 전통 QA의 연장선일 뿐 — 특히 “성공 정의” 없이 시작하지 마라. +
-
+
-
+
-
-
-
+
-
+
-
-
-
- 04 · 온프레미스
-3계층 게이트 — 결정론 → LLM-as-Judge → 사람
-| 게이트 | 수단 | 통과 조건 |
|---|---|---|
| 1 결정론 | 컴파일·테스트·Checkstyle(스타일 검사)·ArchUnit(아키텍처 규칙 테스트)·grep | 전부 통과 (하드) |
| 2 LLM-as-Judge | 루브릭 G-Eval(LLM 루브릭 채점) · 로컬 vLLM(오픈 LLM 추론 서버), guided_json(출력 스키마 강제) | 점수 ≥ 7.0 |
| 3 사람 | 수동 라벨 | 교정·엣지케이스만 |
임계값은 유형별 허용 실패율: convention 5% / correctness 3% / domain_safety 0% (Judge 출력은 guided_json 스키마 강제 + temperature 0).
-
+
04 · 3층 게이트
+게이트는 3층 — 기계, AI, 사람
+
+ 순서가 곧 비용 — 기계로 막을 수 있는 건 전부 기계로, AI와 사람은 그 다음 층에 아껴 쓴다.
+ 실패 허용도도 유형별로: 스타일 5% · 정답성 3% · 안전 규칙 0% — 안전은 단 한 건도 예외 없다. +
+ 실패 허용도도 유형별로: 스타일 5% · 정답성 3% · 안전 규칙 0% — 안전은 단 한 건도 예외 없다. +
-
+
-
+
-
+
04 · 결정론 우선
-규칙으로 표현 가능한 것은 전부 결정론적으로 — Run-AI 규약 → 자동 검사 매핑
-| 규약 | 검사 방법 |
|---|
| 팀 규칙 (사람의 문장) | 기계 검사 (자동 실행) |
|---|---|
| 컴파일 / 전체 테스트 | ./gradlew compileJava test |
| 코드 스타일·네이밍 | ./gradlew checkstyleMain |
| 컨트롤러의 엔티티 직접 반환 금지 | ArchUnit: @RestController 반환 타입에 @Entity 금지 |
| @ManyToOne/@OneToMany는 LAZY | ArchUnit + grep: FetchType.EAGER 금지 패턴 |
| AI 호출은 컨트롤러 스레드 동기 금지 | grep: 컨트롤러 패키지에서 동기 호출 부재 확인 |
| Flyway(DB 마이그레이션 도구) 기존 마이그레이션 미수정 | CI diff 검사: V*.sql 기존 파일 변경 시 실패 |
| 빌드가 깨지지 않는다 | 컴파일 + 전체 테스트 자동 실행 |
| 코드 스타일 통일 | 스타일 검사기(린터) 자동 실행 |
| 화면 계층에서 DB 객체 직접 반환 금지 | 구조 검사 도구가 반환 타입을 확인 |
| 무거운 호출은 응답 경로에서 금지 | 금지 패턴 검색(grep)으로 확인 |
| 과거 마이그레이션 파일 수정 금지 | CI가 기존 파일 변경을 감지하면 실패 |
2장 A/B의 S4(마이그레이션 불변)가 여기서 회수된다 — 모델이 모르는 팀 관례를 결정론 검사가 강제한다.
+
+ 포인트: 팀 관례를 문장이 아니라 기계 검사로 번역했다 — 사람이 안 봐도 걸린다.
+ 2장 실험에서 하네스만 막았던 “마이그레이션 수정”이 바로 이 검사다 — 실험이 실전 규칙으로 회수됐다. +
-+ 2장 실험에서 하네스만 막았던 “마이그레이션 수정”이 바로 이 검사다 — 실험이 실전 규칙으로 회수됐다. +
-
+
-
+
-
+
+
-
+
-
+
-
+
-
+
-
+
+
+
04 · 실물 채점표
-evaluation-criteria — 100점 정량 채점 (PASS ≥ 90, 게이트 항목 0점이면 총점 무관 FAIL)
-| # | 항목 | 배점 | 점수 규칙 |
|---|
| # | 항목 | 배점 | 점수 규칙 |
|---|---|---|---|
| G1 | 빌드/타입체크 | 25 | 빌드 exit 0 → pass=25 / fail=0 게이트 |
| G2 | 테스트 통과 | 25 | npm run test → pass=25 / fail=0 게이트 |
| G3 | 안전 위반 0건 | 15 | 검증 훅(파괴 명령·비밀 노출) 위반 0=15 / 1+=0 게이트 |
| 4 | 린트 | 10 | pass=10 / fail=0 |
| 5 | 회귀 없음 | 10 | 기존 스위트 전부 유지=10 / 깨짐=0 |
| G1 | 빌드/타입체크 | 25 | 빌드 성공=25 / 실패=0 게이트 |
| G2 | 테스트 통과 | 25 | 전체 테스트 성공=25 / 실패=0 게이트 |
| G3 | 안전 위반 0건 | 15 | 위험 명령·비밀 노출 0건=15 / 1건이라도=0 게이트 |
| 4 | 린트 | 10 | 통과=10 / 실패=0 |
| 5 | 회귀 없음 | 10 | 기존 테스트 전부 유지=10 / 하나라도 깨짐=0 |
| 6 | 커버리지 | 5 | 변경 전 대비 유지·상승=5 / 하락=0 |
| 7 | anti-slop | 10 | check-slop 0 ERROR=10 / 1+ ERROR=0 |
| 7 | 디자인 규칙 (anti-slop) | 10 | 검사 도구 오류 0건=10 / 1건 이상=0 |
“좋은 결과”를 주관에 두지 않는다 — 게이트 항목(G1·G2·G3)이 0점이면 나머지 만점이어도 총점 무관 FAIL.
+
+ “좋은 결과”를 주관에 맡기지 않는다 — 전부 명령어 실행 결과로 판정되는 항목뿐이다.
+ 게이트(G1~G3)는 거부권 — 하나라도 0점이면 나머지 만점이어도 FAIL. 총점은 그 다음 이야기다. +
-+ 게이트(G1~G3)는 거부권 — 하나라도 0점이면 나머지 만점이어도 FAIL. 총점은 그 다음 이야기다. +
-
-
+
+
04 · EVALUATOR-DRIVEN 게이트
-Evaluator Driven 평가 게이트 — “구현했다”는 주장을 믿지 않는다
-항목마다 실제 코드와 대조·테스트해 0~100점으로 채점하고, 전 항목이 95점 이상이 될 때까지 개발↔검증 루프를 자동으로 돌리는 하네스 서브시스템.
-
-
-
- 간극을 닫는 3장치
--
-
-
-
-
+ | 쓴다 | 안 쓴다 |
|---|---|
| 스펙이 명확하고 항목 단위 보증이 필요할 때 | 한 줄 수정·오타 등 자명한 변경 |
| 구현 주장이 많아 사람이 전수 확인 버거울 때 | 탐색·리서치처럼 정답 없는 작업 |
| 루프를 자동 수렴시키고 싶을 때 | 테스트 인프라 없는 프로토타입 (test축 0 → 95 불가) |
Evaluator 게이트 — 95점까지 돈다
+
+ 쓸 때: 스펙이 명확하고 확인할 항목이 많을 때 — 사람이 전수 검사하기 버거운 작업.
+ 안 쓸 때: 한 줄 수정 · 정답 없는 리서치 · 테스트가 아예 없는 프로토타입(95점 자체가 불가능).
+ 안 쓸 때: 한 줄 수정 · 정답 없는 리서치 · 테스트가 아예 없는 프로토타입(95점 자체가 불가능).
-
-
-
+
-
+
-
- 04 · EVALUATOR-DRIVEN 게이트 루프
-게이트가 열릴 때까지 되먹인다
-Spec 분해 → 개발/빌드(Generator) → 체크리스트 전수 열거 → 2렌즈 채점(read-only) → 게이트 전 항목 ≥95? — 아니오→deficiencies 피드백→개발 / 예→DONE.
--
-
+
04 · 루프 가드레일
+루프의 3중 안전장치
+
+ 자동 루프는 폭주 장치가 아니다 — 상한 · 교착 감지 · 역할 분리, 세 안전장치가 반드시 함께 간다.
+ 기록이 파일에 있으니 세션이 끊겨도 다음 바퀴가 이어진다 — 대화가 아니라 파일이 루프의 기억이다. +
+ 기록이 파일에 있으니 세션이 끊겨도 다음 바퀴가 이어진다 — 대화가 아니라 파일이 루프의 기억이다. +
-
-
-
+
-
+
-
-
-
- 04 · EVALUATOR-DRIVEN 게이트 루브릭
-5축 100점, 2렌즈 min — 테스트 없으면 95는 불가능
-| 축 | 배점 | 만점 조건 |
|---|---|---|
| exists | 25 | 실제 구현 존재 — 스텁·TODO 아님 |
| match | 25 | 코드가 claim과 의미적으로 일치 |
| test | 25 | verify 명령 실제 실행 → 통과 |
| contract | 15 | 타입·에러·입력검증·인가 경계 안전 |
| no-regress | 10 | 기존 통과 항목·기능 퇴행 없음 |
2렌즈: code-match(정적 대조) × test-pass(실제 실행) → min(두 렌즈). 한 렌즈만 후해도 통과 못 함.
-
+
04 · 루브릭
+채점표의 다섯 질문
+
+ 어려운 채점이 아니다 — 코드 리뷰어가 늘 하던 다섯 가지 질문에 점수를 붙였을 뿐이다.
+ 각 항목은 앞 장의 규칙대로 두 번 따로 채점해 낮은 점수만 인정 — 후한 채점자가 있어도 소용없다. +
+ 각 항목은 앞 장의 규칙대로 두 번 따로 채점해 낮은 점수만 인정 — 후한 채점자가 있어도 소용없다. +
-
-
-
-
+04 · EVALUATOR-DRIVEN 게이트 통합
-하네스 통합 — Stop 게이트가 거짓 완료를 물리적으로 막는다
-3장의 훅(요청→보증)에 4장의 점수가 꽂힌 형태 — 검사 내용이 정규식에서 점수로.
-| SCORE.json 상태 | Stop(응답 종료) 시 동작 |
|---|---|
| 파일 없음 | 통과 (일반 세션 무영향) |
| active: false | 통과 (루프 종료·게이트 해제) |
| active: true + 전 항목 ≥ threshold | 통과 |
| active: true + 미만 항목 존재 | 차단 (exit 2) — “다 됐다” 선언 불가 |
| score 누락 (malformed) | 차단 (fail-closed) |
구성 6표면: 계약(conformance.md 정본) · 커맨드(/evaluator-driven) · 스킬(spec-checklist) · 에이전트(conformance-scorer, read-only) · 워크플로(spec-conformance-loop.js) · 훅(conformance-gate.sh, active-only).
+
+
04 · 하네스 통합
+거짓 완료를 물리적으로 막는다
+
+ 3장의 훅에 4장의 점수를 꽂았다 — 검사 내용이 “금지 패턴”에서 “점수 미달”로 진화했을 뿐, 구조는 같다.
+ 핵심 원칙은 fail-closed — 확인할 수 없으면 통과가 아니라 차단이 기본값이다. +
+ 핵심 원칙은 fail-closed — 확인할 수 없으면 통과가 아니라 차단이 기본값이다. +
-
-
-
+
-
+
-
- 04 · 워크스루
-Evaluator Driven 평가 게이트 워크스루 — 쿠폰 적용 API, 2회차 수렴
--
-
관찰: 전체 재생성이 아니라 미달 항목만 재작업. 종료는 선언이 아니라 게이트 해제.
-
+
04 · 워크스루
+실전 워크스루 — 쿠폰 API 채점
+
+ 92점도 차단이다 — “거의 됐다”는 없다. 합격선 아래는 전부 같은 “미달”이다.
+ 통과한 항목은 건드리지 않는다 — 전체 재생성이 아니라 미달만 고치니 빠르고, 좋은 것을 망치지 않는다. +
+ 통과한 항목은 건드리지 않는다 — 전체 재생성이 아니라 미달만 고치니 빠르고, 좋은 것을 망치지 않는다. +
-
+
-
-
+04 · 성숙도
-EDD(Evaluation-Driven Development, 평가 주도 개발) 성숙도 — 바이브 체크에서 완전한 루프까지
-| 레벨 | 상태 · 목격 현상 | 다음 행동 |
|---|---|---|
| LV0 바이브 체크 | 채팅창에서 몇 개 돌려보고 배포 — 반응적 루프 전부 | 실패 20~50건으로 골든셋 v1 |
| LV1 골든셋+수동 채점 | “3번·7번 케이스가 깨졌다”가 처음 가능. 채점이 병목 | 규칙화 가능한 것부터 코드 grader |
| LV2 자동 채점 | 실험 속도 급상승. “정확하지만 불친절한 답”이 샘 | 루브릭 명문화 → Judge (인간 일치율 먼저) |
| LV3 Judge+CI 게이트 | 배포 전 검출 정착. Judge 자기강화 리스크 등장 | Judge 재교정 프로세스화, 런타임 확장 |
| LV4 런타임 가드레일 | 드리프트가 지표로 잡힘. 단 “달았다≠막힌다” | 가드레일 자체를 공격셋으로 평가 |
| LV5 완전한 EDD 루프 | 실패→분류→최초 결정 지점 수정→골든셋 환류가 규정으로 회전 | eval 스위트 포화 관리·갱신 |
하네스 사다리(3장 Lv0~5)를 오른 팀은 EDD 사다리의 부품을 이미 절반 갖고 있다 — 지금 팀이 어느 줄인지 찾고 그 줄 오른쪽 칸부터 시작한다.
+Eval에도 성숙도 계단이 있다
+
+ 3장의 하네스 계단을 오른 팀은 이 계단의 부품을 이미 절반 갖고 있다 — 두 사다리는 같이 오른다.
+ 지금 팀이 어느 단인지 찾고 바로 다음 한 단만 오르면 된다 — LV0이라면 실패 사례 20건 모으는 것부터. +
+ 지금 팀이 어느 단인지 찾고 바로 다음 한 단만 오르면 된다 — LV0이라면 실패 사례 20건 모으는 것부터. +
+
+
+
+
+
+
+
+
+
-
+
+
+
+
+
-
-
-
+
+
+
+
+
+
+ 05 · 원리
+프롬프트와 Eval은 앞뒷면
+
+ 성공 기준을 한 문장으로 먼저 쓰라 — “좋은 답변” 같은 말은 지시로도 채점 기준으로도 못 쓴다.
+ 프롬프트 한 줄 수정도 코드처럼 게이트를 통과시켜라 — CLAUDE.md 변경도 결국 프롬프트 변경이다. +
+ + 프롬프트 한 줄 수정도 코드처럼 게이트를 통과시켜라 — CLAUDE.md 변경도 결국 프롬프트 변경이다. +
+
+
+
+
+
-
+
-
+
+
-
+
-
+
-
05 · 시작
-시작 로드맵 — 완벽을 기다리지 마라
-| 단계 | 내용 |
|---|
| 단계 | 무엇을 |
|---|---|
| Step 0 일찍 시작 | 수백 개 불필요 — 실제 실패에서 뽑은 20~50개면 강력하게 출발. 초기 변경은 효과가 커서 작은 표본으로도 신호가 잡힌다. 미룰수록 만들기 어려워진다 |
| Step 1 이미 하는 것에서 | 릴리스 전 수동 체크, 버그 트래커, CS 큐가 최고 소재 — 사용자 실패를 테스트 케이스로 |
| Step 2 모호하지 않게 | 품질 기준 = 전문가 2명이 독립적으로 같은 합/불 판정. 명세의 모호함은 곧 지표의 노이즈. 참조 해법(모든 grader 통과 출력)으로 풀이 가능성과 grader를 동시 증명 |
| Step 3 균형 | 일어나야 하는 케이스와 일어나면 안 되는 케이스 모두 — 치우친 eval은 치우친 최적화를 낳는다 |
| ⓪ 일찍 시작 | 수백 개 필요 없다 — 실제 실패 20~50개면 충분히 출발. 미룰수록 만들기 어려워진다 |
| ① 이미 하는 것에서 | 릴리스 전 수동 체크 · 버그 목록 · 고객 문의가 최고의 소재 — 실패를 테스트 케이스로 |
| ② 모호하지 않게 | 좋은 기준 = 전문가 2명이 따로 봐도 같은 합/불 판정. 애매한 기준은 채점 노이즈가 된다 |
| ③ 균형 있게 | “일어나야 할 것”과 “일어나면 안 될 것” 둘 다 — 한쪽만 재면 한쪽으로만 좋아진다 |
신호 해석: 프론티어 모델이 pass@100(100번 시도 중 1회 이상 통과)에서 0% = 에이전트가 아니라 태스크가 깨진 신호.
+
+ 완벽한 채점 세트를 기다리지 마라 — 오늘의 실패 20건이 다음 달의 계획 100장보다 낫다.
+ 덤 신호 하나: 최고 모델이 100번 시도해도 0% 통과라면 — AI가 아니라 문제 자체가 깨진 것이다. +
-+ 덤 신호 하나: 최고 모델이 100번 시도해도 0% 통과라면 — AI가 아니라 문제 자체가 깨진 것이다. +
-
+
+
-
-
+
+
+
+
+
+
+ 05 · 실전 사례
+실전 팀의 채점 프레임, 세 질문
+
+ 순서가 중요하다 — ① 회귀부터 막고, ② 이행을 확인하고, ③ 품질은 마지막에 다듬는다.
+ 성패는 시작 시점이 아니라 태도 — 늦게 시작한 Bolt도 3개월이면 됐지만, 평가를 “부속물”로 다루면 영영 안 된다. +
+ + 성패는 시작 시점이 아니라 태도 — 늦게 시작한 Bolt도 3개월이면 됐지만, 평가를 “부속물”로 다루면 영영 안 된다. +
+
-
-
-
+
-
+
-
- 05 · 배포 판정
-CI 게이트와 버전 비교 — 숫자로 배포를 결정
--
-
통계 주의: 표본을 키우면 사소한 차이도 “유의” — p값만으로 결정 금지, 효과 크기·비용·지연을 함께.
-
+
05 · 배포 판정
+배포로 가는 세 관문
+
+ 통계 함정 하나: 케이스를 많이 모으면 사소한 차이도 “유의미”해 보인다 — 차이의 크기와 비용·속도를 함께 보라.
+ 전부 한 번에 아니어도 된다 — 관문 ①(PR마다 재채점)만 걸어도 회귀의 대부분을 잡는다. +
+ 전부 한 번에 아니어도 된다 — 관문 ①(PR마다 재채점)만 걸어도 회귀의 대부분을 잡는다. +
-
-
-
+
-
+
-
- 05 · 런타임 방어선
-가드레일 — “달았다”와 “막힌다”는 다르다
--
-
결론: 가드레일 자체를 공격 데이터셋으로 정기 평가 (recall·차단률 분리 측정).
-
+
05 · 런타임 방어선
+가드레일 — 달았다 ≠ 막힌다
+
+ 가드레일도 시험을 쳐야 한다 — 공격 문제집(레드팀 셋)으로 정기 평가하고, 탐지율과 차단율은 따로 재라.
+ 판정을 “통과/차단” 둘로만 두지 마라 — “계획을 고쳐서 계속”이라는 세 번째 선택지가 정상 업무를 살린다. +
+ 판정을 “통과/차단” 둘로만 두지 마라 — “계획을 고쳐서 계속”이라는 세 번째 선택지가 정상 업무를 살린다. +
-
+
+05 · 마지막 규율
-트랜스크립트를 읽어라 — 점수를 액면 그대로 믿지 마라
-누군가 eval 내부를 파고 트랜스크립트를 읽기 전까지, 점수를 믿지 마라. 실패는 공정해 보여야 한다 — 무엇을 왜 틀렸는지 명확해야.
--
-
grader는 우회·해킹에 강해야 — 통과하려면 실제로 풀어야지, 허점을 악용해선 안 된다. 각 trial은 깨끗한 환경에서(공유 상태는 성능을 인위적으로 부풀린다).
+점수를 믿지 말고, 기록을 읽어라
+
+ 규율: 점수를 액면 그대로 믿지 마라 — 트랜스크립트(실제 대화·실행 기록)를 직접 읽기 전까지는.
+ 실패는 공정해 보여야 한다 — 무엇을 왜 틀렸는지 기록만 보고도 설명될 것. +
+ 실패는 공정해 보여야 한다 — 무엇을 왜 틀렸는지 기록만 보고도 설명될 것. +