Harness Engineering

같은 실수 두 번이면 코드로 막는
Claude Code Harness System

보통의 AI 코딩 도구는 같은 실수를 되풀이합니다. 한 번의 작업이 끝나면 배운 것이 남지 않기 때문입니다. 이 글은 그 문제를 풀려고 만든 장치, Claude Code 하네스(harness, AI가 "다 됐다"고 대충 넘어가지 못하도록 증거를 요구하고 잘못을 자동으로 잡아 주는 감시 장치)를 뜯어본 기록입니다. 결론부터 적으면, 이 하네스는 무시할 수 없는 강제 검사 36개를 전부 통과했고 5개 항목 종합 진단은 100%였습니다. 다만 이 점검은 파일 속 문자열을 찾는 방식이라, 실제로 실행됐다는 것까지 증명하지는 못합니다. 이 하네스에서는 한 번 저지른 실수가 규칙으로 남습니다. 그 규칙은 스스로 더 단단해집니다. 개선이 진짜 효과가 있는지까지 자동으로 확인합니다.

Pipeline Skills

Hook Files

HARD Checks

Hook Events

Core Philosophy

왜 이런 장치가 필요한가

보통의 AI 코딩 도구

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

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

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

Karpathy가 말한 'Loopy Era(루프의 시대)'는 AI가 자기 자신을 계속 고쳐 나가는 반복 루프를 뜻합니다. 이 시스템은 그 루프를 이렇게 돌립니다. 먼저 자가개선 절차(self-improve)가, AI에게 주는 규칙 묶음(scaffold, 스캐폴드)을 손봅니다. 그러면 평가 도구(loopy-era-eval)가 "강제 규칙이 얼마나 촘촘한가", 곧 강제 규칙 비율(HARD ratio)을 다시 잽니다. 점수가 좋아졌으면 그대로 두고(keep), 나빠졌으면 버립니다(discard). 좋으면 남기고 나쁘면 버리는 자동 실험 방식(autoresearch, 오토리서치)을 규칙 개선에 그대로 적용한, 스스로 도는 개선 고리입니다.

Closed Loop

스스로 도는 개선 고리 (자가개선 폐루프)

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

5-Dimension Evaluation

하네스 종합 진단: 5개 항목 채점 (아래 표의 영문 라벨 D1~D5가 진단 항목 1~5)

#	평가 항목	점수	비율	상태
`D1`	작업 흐름이 처음부터 끝까지 이어지는가	6/6	100%
`D2`	여러 단계가 서로 연결돼 있는가	9/9	100%
`D3`	무시 못 하는 강제 규칙이 얼마나 촘촘한가	10/10	100%
`D4`	스스로 고치는 속도가 빠른가	6/6	100%
`D5`	한 지점으로 안정될 만큼 성숙했는가	5/5	100%
	종합	36/36	100%	S

Layer Evaluation

성숙도 6단계(L1~L6) 충족 분석 (카드마다 붙은 영문 라벨이 1~6단계)

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곳입니다. 시스템 안에서는 이런 검문을 게이트(gate, 통과하지 못하면 다음 단계로 못 넘어가는 관문)라고 부릅니다. 이 밖에도 규칙 위반 검사(scaffold-violation-check.sh), 코드 품질 검사(code-quality-check.sh), 브라우저 저장소(localStorage) 사용 금지(no-localstorage.sh), 비밀정보 파일(.env) 커밋 금지(no-env-commit.sh) 같은 무시할 수 없는 강제 게이트(HARD gate)가 10개가 넘습니다. 스크립트 문법이 맞는지 확인하는 검사(bash -n)도 통과합니다.

L5

자동 수정 충족

잘못을 사람 손 없이 시스템이 직접 고칩니다. 자가개선 절차(/self-improve)는 10개의 세부 단계(1.1~1.10)로 짜여 있습니다. 여기에는 AI에게 주는 규칙 묶음과 규칙 문서를 자동으로 손보기, 권고 규칙을 강제 규칙으로 자동 승격(SOFT→HARD), 한 프로젝트에서 배운 규칙을 다른 프로젝트로 확대(Cross-Project 승격), 그리고 개선이 진짜 받아들일 만한지 확인하는 최종 검증(L6 acceptance, 성숙도 6단계 폐루프 수용 검사)이 들어 있습니다.

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단계 · 구현을 전문 에이전트(agent, 역할을 나눠 맡은 AI 일꾼)에 위임OK

↓

9qa_cycle/qa-cycle · 도구 3개로 교차 검증 (700줄)OK

↓

10qa_fix_retryqa-cycle 자동 수정(검사에서 잡힌 오류를 고치는 단계) · 실패 시 최대 5번 재시도OK

↓

11inject_findings리뷰 지적사항(findings)을 대기목록에 넣기OK

↓

12si_worker_findings지적사항을 바탕으로 자동 수정(자가개선 일꾼이 11단계의 지적사항을 받아 고치는 단계)OK

↓

13verify_final/loopy-era-eval · 문법 실행 검사(bash -n) 포함 재평가OK

↓

14final_review다른 AI로 마지막 교차 점검(수정을 마친 코드를 다른 AI가 마지막으로 다시 살피는 최종 리뷰 단계)OK

↓

15closeout텔레그램 알림 + 코드 업로드(git push)OK

Pipeline Steps

Skills

7 Skills Pipeline

7개 스킬(skill, 정해진 절차를 담은 명령 묶음)이 이어지는 흐름

loopy-era-eval

무시할 수 없는 강제 검사 36개

이 36개 검사는 모두 사람 판단 없이 기계적으로 참·거짓이 갈립니다(deterministic, 결정론적). 특정 문자열을 세거나(grep), 파일이 있는지 보거나, 스크립트 문법을 확인하거나(bash -n), 숫자를 비교하는 식입니다. AI의 주관적 판단은 끼어들지 않습니다. 아래 목록에서 영문으로 적힌 이름은 검사가 찾는 문자열·파일·스킬 이름을 그대로 옮긴 것입니다. 그룹 머리에 붙은 짧은 영문 라벨은 앞의 종합 진단 표 번호(진단 항목 1~5)와 성숙도 카드 번호(1~6단계)를 그대로 가리킵니다.

qa-cycle (5)

✓필수 테스트 ≥ 6개

✓TC_EVIDENCED gate

✓빌드 결과 자동 분류

✓콘솔 오류 0건

✓DB 직접 조회 확인

qa-scenario-gen (3)

✓실패 시 진행 차단

✓TC-CLICK- 클릭 테스트 케이스(test case) 이름 규칙 존재

✓브라우저 오류 모음 변수 __qaErrors 패턴 존재

self-improve (3)

✓pending = 0

✓recurrence = 0

✓권고→강제 승격 규칙

autoresearch (6)

✓git reset discard

✓metric_parse

✓중단 시 복구

✓timeout kill

✓results.tsv

✓NEVER STOP

D2 단계 연결(진단 항목 2) + L6 폐루프(성숙도 6단계), 검사 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개(진단 항목 5) + D3 강제 5개(진단 항목 3) + D4 구조 방어 3개(진단 항목 4)

✓평가 이력 ≥ 5줄

✓latest ≥ 90%

✓qa-gate exit 2

✓scaffold-violation

✓code-quality hook

✓no-env-commit

✓hook events ≥ 5

✓검사 건너뛰기 금지

✓외부 증거 요구

✓동작 후퇴 감지

36/36

HARD ratio

grep checks

runtime (bash -n)

SOFT patterns

Checklist Evolution

검사 항목이 늘어온 이력 (17 → 36개)

17개 → 처음 시작 (스킬 4개: 자동 QA 반복 qa-cycle + 테스트 시나리오 생성 qa-scenario-gen + 자가개선 self-improve + 자동 실험 autoresearch)
29개 → +단계 연결 D2(진단 항목 2) + 강제 규칙 깊이 D3(진단 항목 3)
32개 → +구조 방어 (건너뛰기 금지·외부 증거·동작 후퇴 감지)
34개 → +수렴 점검 D5(진단 항목 5) + 자기참조 제거
35개 → +성숙도 6단계 폐루프 L6 + 지적사항 주입 (거짓 수렴 해소)
36개 → +문법 실행 검사(bash -n) 추가 (문자열 검색의 한계 돌파)

'거짓 수렴' 사건: 검사 34개가 전부 100% 통과였습니다. 그런데 알고 보니 개선 고리(L6, 성숙도 6단계 폐루프)가 중간에 끊겨 있었습니다. 자가개선 절차(self-improve)가 규칙을 고친 뒤 평가 도구(loopy-era-eval)를 거꾸로 다시 불러 확인하는지를, 아무도 검사하지 않았기 때문입니다. "엉뚱한 것만 검사하면 100%도 거짓"이라는 교훈을 남겼습니다. 이 고리를 확인하는 검사 2개(진단 항목 2, 곧 D2의 7·8번)를 추가해 해결했습니다.

Honest Assessment

솔직한 한계: 증명되는 것과 안 되는 것

지금 확인 가능한 것

✓ 스킬 파일에 해당 지시가 적혀 있는지
✓ 훅 파일이 있고 문법이 맞는지
✓ 단계들이 서로 이어져 있는지 (A가 B를 부르는지)
✓ 평가 기록이 쌓이고 안정되는지
✓ 대기 중인 할 일이 다 처리됐는지

아직 확인 못 하는 것 (문자열 검색의 한계)

✗ 적힌 지시를 AI가 진짜 따르는지
✗ 훅이 정확한 순간에 실제로 돌았는지
✗ 브라우저 자동 테스트가 진짜 실행됐는지
✗ 규칙을 바꾼 뒤 실제 동작이 나빠졌는지
✗ QA 결과가 AI의 자기 보고에 그친 건 아닌지

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

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

데이터 출처: 홈 폴더 아래 Claude Code 설정 폴더의 .claude/skills/, .claude/hooks/, .claude/logs/ (스킬·훅·로그)

같은 실수 두 번이면 코드로 막는Claude Code Harness System

같은 실수 두 번이면 코드로 막는
Claude Code Harness System