Harness Engineering

Claude Code
Harness System

이 글은 AI 코딩 도구가 스스로 실수를 줄여 가는 장치를 뜯어본 기록입니다. 여기서 '하네스(harness)'란, AI가 "다 됐다"고 대충 넘어가지 못하도록 증거를 요구하고 잘못을 자동으로 잡아 주는 감시 장치를 말합니다. 이 하네스에서는 한 번 저지른 실수가 규칙으로 남고, 그 규칙이 스스로 더 단단해지며, 개선이 진짜 효과가 있는지까지 자동으로 확인합니다.

7
Pipeline Skills
41
Hook Files
36
HARD Checks
10
Hook Events
Core Philosophy
왜 이런 장치가 필요한가
보통의 AI 코딩 도구

규칙은 사람이 미리 다 적어 둬야 합니다. AI가 실수하면 그때그때 사람이 직접 고칩니다. 같은 실수를 몇 번을 반복해도 도구 자체는 그대로입니다. 한 번의 작업(세션)이 끝나면, 다음 작업은 배운 것 없이 다시 백지에서 시작합니다.

스스로 배우는 하네스 (이 시스템)

실수를 하면, 그 실수를 막는 규칙이 자동으로 만들어집니다. 처음엔 "이렇게 하지 말자"는 권고(무시할 수도 있는 SOFT 규칙)로 시작합니다. 같은 실수가 2번 다시 나오면, 아예 코드로 막아 통과 못 하게 하는 강제 규칙(무시 불가능한 HARD 규칙)으로 올립니다. 그리고 이 개선이 정말 나아졌는지 자동으로 확인해, 오히려 나빠졌으면 방금 바꾼 것을 원래대로 되돌립니다(rollback). 그렇게 시스템이 스스로 단단해집니다.

Karpathy가 말한 'Loopy Era(루프의 시대)' — AI가 자기 자신을 계속 고쳐 나가는 반복 루프를 뜻합니다. 먼저 자가개선 절차(self-improve)가, AI에게 주는 규칙 묶음(scaffold)을 손봅니다. 그러면 평가 도구(loopy-era-eval)가 "강제 규칙이 얼마나 촘촘한가(HARD 비율)"를 다시 잽니다. 점수가 좋아졌으면 그대로 두고(keep), 나빠졌으면 버립니다(discard). 좋으면 남기고 나쁘면 버리는 자동 실험 방식(autoresearch)을 규칙 개선에 그대로 적용한, 스스로 도는 개선 고리입니다.
Closed Loop
스스로 도는 개선 고리 (자가개선 폐루프)
fix: commit 실수 발생 trigger.sh 신호 감지 → 대기목록 /self-improve 규칙묶음 수정 /loopy-era-eval 강제규칙 비율 측정 keep? keep results.tsv 수렴까지 반복 discard git checkout 수정 되돌림 다시 시도 HARD Enforcement Layer qa-gate (exit 2) · scaffold-violation · code-quality · no-env · no-localstorage · 41 hooks L1 관측 L2 신호변환 L5 자동수정 L6 폐루프

실수를 고친 기록(fix 커밋) → 시스템이 신호 감지 → AI 규칙 묶음(scaffold) 수정 → 강제 규칙이 얼마나 촘촘해졌는지 점수 측정 → 좋으면 유지(keep)·나쁘면 폐기(discard). 이 과정이 반복되며 시스템이 한 지점으로 안정됩니다(수렴).

5-Dimension Evaluation
하네스 종합 진단: 5개 항목 채점
#평가 항목점수비율상태
D1작업 흐름이 처음부터 끝까지 이어지는가6/6100%
D2여러 단계가 서로 연결돼 있는가9/9100%
D3무시 못 하는 강제 규칙이 얼마나 촘촘한가10/10100%
D4스스로 고치는 속도가 빠른가6/6100%
D5한 지점으로 안정될 만큼 성숙했는가5/5100%
종합36/36100%S
Layer Evaluation
성숙도 6단계(L1~L6) 충족 분석
L1
관측 가능성 충족
무엇이 언제 일어났는지 시스템이 스스로 기록하고 있다는 뜻입니다. 여기서 hook(훅)이란, 파일 저장·커밋·푸시 같은 특정 순간에 자동으로 끼어들어 실행되는 검사 스크립트입니다. 이 훅이 작동하는 시점이 10가지 있고(도구 실행 전후, 사용자 입력, 작업 종료 등 — PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, TaskCompleted, Notification, PreCompact, PostToolUseFailure, PostCompact), 훅 파일은 모두 41개입니다. 그중 feedback-detector, error-tracker, fix-commit-detector 같은 훅이 매 작업과 실패를 자동으로 남깁니다.
L2
신호 변환 충족
실수의 흔적을 다음에 처리할 "할 일"로 바꿔 두는 단계입니다. 작업이 끝나는 순간 실행되는 감시 스크립트(self-improve-trigger.sh)가, 실수를 고친 기록(fix 커밋)·버그 수정 재시도·같은 문제의 재발 등 5종류의 신호를 잡아냅니다. 그리고 이를 아래 경로의 대기 파일 하나로 만들어 둡니다 — ~/.claude/pending/self-improve-{project}.json — 이렇게 남긴 대기 파일을, 다음 작업을 시작해 사용자가 첫 입력을 넣는 순간(UserPromptSubmit) 확인 스크립트(self-improve-check.sh)가 발견해 개선 절차를 자동으로 돌립니다.
L3
프로젝트 경계 부분 충족
한 프로젝트의 개선 작업이 다른 프로젝트를 건드리지 않도록 경계를 나누는 부분입니다. 대기 파일에 프로젝트 이름(project_name)이 들어 있어서 프로젝트별 구분은 실제로 됩니다. 다만 "이 프로젝트 것만 처리하라"는 격리 규칙이 문서에는 뚜렷이 적혀 있지 않습니다. 개선 절차가 엉뚱한 프로젝트의 대기 파일을 집어 처리하지 않도록 막는 범위 제한은, 파이썬 스크립트가 지금 실행 중인 폴더를 알아내는 명령 os.getcwd() 을 기준으로 이뤄집니다. 즉 현재 열려 있는 프로젝트 폴더 안에서만 동작합니다.
L4
규칙 차단 충족
검사를 통과하지 못하면 아예 진행 자체를 막는 단계입니다. 예를 들어 코드를 서버에 올리기(push) 직전에 실행되는 검문 스크립트(qa-gate-before-push.sh)가, 실패를 뜻하는 종료 신호 exit 2를 내보내 push를 강제로 가로막습니다(이런 강제 차단 지점이 13곳). 이 밖에도 규칙 위반 검사·코드 품질 검사·브라우저 저장소 사용 금지·비밀정보 커밋 금지(scaffold-violation-check.sh, code-quality-check.sh, no-localstorage.sh, no-env-commit.sh) 같은, 무시할 수 없는 강제 검문(HARD gate)이 10개가 넘습니다. 스크립트 문법이 맞는지 확인하는 검사(bash -n)도 통과합니다.
L5
자동 수정 충족
잘못을 사람 손 없이 시스템이 직접 고칩니다. 자가개선 절차(/self-improve)는 10개의 세부 단계(1.1~1.10)로 짜여 있습니다. 여기에는 AI에게 주는 규칙 묶음과 규칙 문서를 자동으로 손보기, 권고 규칙을 강제 규칙으로 자동 승격(SOFT→HARD), 한 프로젝트에서 배운 규칙을 다른 프로젝트로 확대(Cross-Project 승격), 그리고 개선이 진짜 받아들일 만한지 확인하는 최종 검증(L6 폐루프 acceptance)이 들어 있습니다.
L6
폐루프 practical L6
개선의 고리가 실제로 한 바퀴 닫혀 돈다는 뜻입니다. 자가개선 절차의 1.8단계에서 규칙 묶음을 고친 뒤, 평가 도구(loopy-era-eval)로 강제 규칙 비율을 다시 잽니다. 점수가 떨어지면 방금 바꾼 것을 원래대로 되돌립니다(rollback). 이렇게 감지 → 수정 → 검증 → 확정(ack)의 고리가 끊기지 않고 이어집니다. 다만 별도 도구를 겉에서 이어 붙인 방식이라, 완전한 6단계가 아니라 사실상 6단계에 준하는 practical L6.
Pipeline
하네스 작업 흐름 (전체 15단계)
1init_project/init-project · 프로젝트를 분석해 규칙 생성 (320줄)OK
↓
2qa_scenario_gen/qa-scenario-gen · 테스트 시나리오 작성 (779줄)OK
↓
3self_improve_triggerself-improve-trigger.sh · 실수 신호 감지 (139줄)OK
↓
4self_improve_worker/self-improve Phase 1.1~1.10OK
↓
5verify_initial/loopy-era-eval (36 HARD checks)OK
↓
6cross_review다른 AI로 한 번 더 교차 점검 (이중 모델 리뷰)OK
↓
7team_plan/team 0단계 · 계획 수립 (init-project 연동)OK
↓
8team_execute/team 1~3단계 · 구현을 전문 에이전트에 위임OK
↓
9qa_cycle/qa-cycle · 도구 3개로 교차 검증 (700줄)OK
↓
10qa_fix_retryqa-cycle 자동 수정 · 실패 시 최대 5번 재시도OK
↓
11inject_findings리뷰 지적사항(findings)을 대기목록에 넣기OK
↓
12si_worker_findings지적사항을 바탕으로 자동 수정OK
↓
13verify_final/loopy-era-eval · 문법 실행 검사(bash -n) 포함 재평가OK
↓
14final_review다른 AI로 마지막 교차 점검OK
↓
15closeout텔레그램 알림 + 코드 업로드(git push)OK
15
Pipeline Steps
7
Skills
7 Skills Pipeline
7개 스킬이 이어지는 흐름
DESIGN & BUILD /init-project 프로젝트 파악 320줄 · 규칙문서+스킬 생성 CLAUDE.md /team 작업 지휘 114줄 · 0~5단계 + init 연동 구현물 /qa-scenario-gen 테스트 계약 생성 779줄 · 클릭·CRUD 시나리오 커버리지 qa-test-plan.md QA & VERIFY /qa-cycle 자동 QA + 수정 반복 700줄 · 도구 3개 교차검증 · 5회 실패 패턴 SELF-IMPROVE /self-improve 자가개선 10단계 429줄 · 규칙묶음 · 권고→강제 수정 적용 EVALUATE & REPORT /loopy-era-eval 강제규칙 비율 평가 421줄 · 36개 검사 · 유지/폐기 /harness-report 5개 항목 종합 진단 477줄 · D1~D5 · 등급 판정 유지→수렴 / 폐기→되돌림→재시도 Total: 3,240줄 7 skills · 41 hooks · 10 events 36 HARD checks · practical L6 데이터 흐름 init → team → scenario → qa-cycle 실패 → 자가개선 → 평가 → 리포트 평가 유지/폐기 → 수렴까지 반복 HARD Enforcement qa-gate-before-push.sh (exit 2) scaffold-violation-check.sh code-quality · no-env · no-ls
loopy-era-eval
무시할 수 없는 강제 검사 36개

이 36개 검사는 모두 사람 판단 없이 기계적으로 참·거짓이 갈립니다(deterministic). 특정 문자열을 세거나(grep), 파일이 있는지 보거나, 스크립트 문법을 확인하거나(bash -n), 숫자를 비교하는 식입니다. AI의 주관적 판단은 끼어들지 않습니다.

qa-cycle (5)
✓필수 테스트 ≥ 6개
✓TC_EVIDENCED gate
✓빌드 결과 자동 분류
✓콘솔 오류 0건
✓DB 직접 조회 확인
qa-scenario-gen (3)
✓실패 시 진행 차단
✓TC-CLICK- 패턴 존재
✓__qaErrors 패턴 존재
self-improve (3)
✓pending = 0
✓recurrence = 0
✓권고→강제 승격 규칙
autoresearch (6)
✓git reset discard
✓metric_parse
✓중단 시 복구
✓timeout kill
✓results.tsv
✓NEVER STOP
D2 단계 연결 + L6 폐루프 (9)
✓init→team
✓team→qa-scenario
✓scenario→qa-cycle
✓team→qa-cycle
✓cycle→improve
✓improve→scaffold
✓improve→eval (L6)
✓adv→pending
✓문법 실행 검사(bash -n)
D5 수렴 (2) + D3 강제 (5) + D4 구조 방어 (3)
✓평가 이력 ≥ 5줄
✓latest ≥ 90%
✓qa-gate exit 2
✓scaffold-violation
✓code-quality hook
✓no-env-commit
✓hook events ≥ 5
✓검사 건너뛰기 금지
✓외부 증거 요구
✓동작 후퇴 감지
36/36
HARD ratio
35
grep checks
1
runtime (bash -n)
0
SOFT patterns
Checklist Evolution
검사 항목이 늘어온 이력 (17 → 36개)
17개 → 처음 시작 (qa-cycle + qa-scenario-gen + self-improve + autoresearch)
29개 → +단계 연결(D2) + 강제 규칙 깊이(D3)
32개 → +구조 방어 (건너뛰기 금지·외부 증거·동작 후퇴 감지)
34개 → +수렴 점검(D5) + 자기참조 제거
35개 → +L6 폐루프 + 지적사항 주입 (거짓 수렴 해소)
36개 → +문법 실행 검사(bash -n) 추가 (문자열 검색의 한계 돌파)
'거짓 수렴' 사건: 검사 34개가 전부 100% 통과였는데, 알고 보니 개선 고리(L6 폐루프)가 중간에 끊겨 있었습니다. 자가개선(self-improve)이 평가(loopy-era-eval)를 거꾸로 다시 불러 확인하는지를 아무도 검사하지 않았기 때문입니다. "엉뚱한 것만 검사하면 100%도 거짓"이라는 교훈을 남겼습니다. 이 고리를 확인하는 검사 2개(D2의 7·8번)를 추가해 해결했습니다.
Honest Assessment
솔직한 한계: 증명되는 것과 안 되는 것
지금 확인 가능한 것
  • ✓ 스킬 파일에 해당 지시가 적혀 있는지
  • ✓ 훅 파일이 있고 문법이 맞는지
  • ✓ 단계들이 서로 이어져 있는지 (A가 B를 부르는지)
  • ✓ 평가 기록이 쌓이고 안정되는지
  • ✓ 대기 중인 할 일이 다 처리됐는지
아직 확인 못 하는 것 (문자열 검색의 한계)
  • ✗ 적힌 지시를 AI가 진짜 따르는지
  • ✗ 훅이 정확한 순간에 실제로 돌았는지
  • ✗ 브라우저 자동 테스트가 진짜 실행됐는지
  • ✗ 규칙을 바꾼 뒤 실제 동작이 나빠졌는지
  • ✗ QA 결과가 AI의 자기 보고에 그친 건 아닌지

핵심은 이렇습니다. 이 점검 방식은 파일에서 문자열을 찾는(grep) 방식이라, "문서에 그렇게 적혀 있다"까지만 증명할 뿐, "그게 실제로 실행된다"는 것까지는 증명하지 못합니다. 실제로 36개 검사 중 35개가 문자열 찾기(grep)이고, 진짜로 돌려 보는 검사(bash -n)는 단 1개뿐입니다. 그래서 다음 과제는 이 '실제로 돌려 보는' 검사의 비율을 높이는 것입니다.

측정일 2026-04-05 | 자가개선 평가(loopy-era-eval) 36/36 = 100% | 5개 항목 종합 리포트(harness-report) 100%

데이터 출처: ~/.claude/skills/, ~/.claude/hooks/, ~/.claude/logs/