Mk 하네스규칙은 문서가 아니라 훅으로
AI 코딩 에이전트를 주력으로 쓰면서 그 결과물을 자동으로 검증하려고 만든 개발 하네스입니다. 2026년 2월부터 모든 개인 프로젝트를 이 위에서 진행합니다.
- Phase 1 정적 검사35/35 PASS
- Phase 2 훅 기능87/87 PASS
- Phase 3 스키마 정합성29/29 PASS
- Phase 4 설치20/20 PASS
- Phase 5 교차 참조16/16 PASS
- Phase 6 운영 행동15/15 PASS
- Phase 7 런타임 통합9/9 PASS
총합 211/211 PASS
- 211하네스 자체 검증 항목 · 초기 108에서 늘림 · CI 상시 실행
- 859 → 0경고 859회에 행동 변화 0이던 훅을 기록 대조로 찾아 제거
- −56%매 세션 상시 로드되던 컨텍스트 절감
TL;DR
문제
AI가 만든 코드는 테스트를 통과해도 결함이 남고 문서로 적은 규칙은 바쁠 때 먼저 무시됐습니다.
한 일
규칙을 훅으로 집행하는 하네스를 설계하고 그 효과를 기록으로 감사했습니다.
결과
훅 19종 · 하네스 자체 검증 211항목. 경고 859회에 행동 변화 0이던 훅은 재고 나서 걷어냈습니다.
대표 사례
면접에서 가장 먼저 이야기하고 싶은 세 가지
가드레일
문서로 적은 규칙은 바쁠 때 가장 먼저 무시된다
규칙을 먼저 정하고 도구를 만들지 않았습니다. 실제로 겪은 사고를 기록하고 반복되지 않도록 훅을 붙이는 순서로 자랐습니다. 파괴적 명령과 main 직접 커밋도 같은 방식으로 막습니다.
훅 19종 중 차단 6종(도구 호출 5 · 세션 종료 1)이 위반 시 진행을 멈추고 2종은 경고를 주입
MK-01 전체 읽기 →효과 측정
늘린 규칙이 실제로 행동을 바꾸는지 쟀다
훅과 규칙은 늘릴수록 경고가 쌓입니다. 그 경고가 행동을 바꾸는지 확인할 수단이 없어 45일 · 79세션 기록에서 대상 8개의 발동 시점과 직후 행동을 전수 대조하는 감사를 발주했습니다.
훅 2종 제거 · 2종 축소 · 에이전트 8 → 6 · 제거 사유를 문서로 남겨 같은 가정으로 다시 넣지 않음 · 은퇴한 이름의 재유입은 테스트로 탐지
도구의 신뢰성
하네스에도 테스트를 붙였다
AI가 쓴 코드를 검증하는 도구가 틀리면 그 위의 검증이 전부 무너집니다. 그래서 도구 자체를 제품처럼 테스트하고 매 세션 드는 비용도 쟀습니다.
하네스 자체 검증
108 → 211
훅과 에이전트가 서로 영향을 줄 수 있어 개별 확인만으로는 안전하지 않았습니다. 7단계 검증을 CI에 걸었고 CI 첫 실행에서 macOS와 Linux 셸 차이로 생긴 이식성 결함 4종을 한꺼번에 찾았습니다.
상시 로드 컨텍스트
−56%
규칙과 에이전트 정의가 매 세션 전량 로드돼 작업 전부터 창을 차지했습니다. 중복 제거 · 규칙 문서 영어 전환 · 메모리 규약 중앙화 · 필요 시점 로드 4단계로 줄였고 완전 중복 6,897B를 합쳐 세션당 약 2,000토큰을 더 회수했습니다.
211항목 CI 상시 실행 · 이식성 결함 4종 일괄 검출 · 상시 로드 약 56% 절감
일하는 방식
도구도 제품처럼 운영합니다
모든 개인 프로젝트에서 이 하네스 위에서 일합니다. 규칙이 바뀌면 같은 세션 안에서 문서와 훅을 함께 고치고 새 훅은 실제로 한 번 발동시켜 확인한 뒤에만 "설치됨"으로 기록합니다. 2026-09-16부터는 집행 훅 8종에 계측을 붙여 종료 코드까지 남깁니다.
순서
사고 → 기록 → 훅
이론으로 규칙을 먼저 만들지 않습니다. 반복된 실패가 기록에 쌓이면 그때 집행으로 옮깁니다.
배포
원본 하나 · 배포본 대조
원본 레포에서 고치고 전역으로 배포합니다. 검증 스위트가 배포본과 원본이 같은지 매번 대조합니다.
은퇴
쓰지 않는 것은 뺀다
호출 실측으로 은퇴시킨 에이전트 이름이 다시 들어오면 테스트가 실패하게 했습니다.
그 밖의 결정
문제 → 결정 → 결과
- 컨텍스트규칙 문서를 영어로 바꾸고 응답만 한국어로 · 토큰은 줄이고 출력 언어는 유지
- 기억세션이 끝나도 맥락이 남도록 기록 규약을 하나로 · 기록 없는 종료는 훅이 차단
- 실패같은 실패가 3회 반복되면 멈추고 보고 · 조회형 명령의 정상 실패는 세지 않음
- 이식성macOS에서만 돌리면 드러나지 않는 셸 차이 4종을 CI에서 검출
한계
재지 않은 것과 재지 못하는 것
- 생산성"이 도구로 생산성이 얼마나 올랐다"는 말은 하지 않습니다. 막은 것은 셀 수 있지만 막지 않았다면 무슨 일이 났을지는 셀 수 없습니다.
- 사용자제 환경 한 곳에서만 쓴 도구입니다. 다른 사람의 작업 방식에서 같은 효과가 나는지는 재지 않았습니다.
- 경계훅은 실수를 막는 장치이지 보안 경계가 아닙니다. 이 한계가 다음 하네스 Shift에서 층을 나눈 이유가 됐습니다.
