Claude, Gemini, Codex — 여러 AI 세션이 한 지식 저장소 위에서 일하는 순간, 규칙은 복제되고 복제된 규칙은 서로 다른 답을 하기 시작합니다. Harness Engineering v2는 그 붕괴를 실제로 겪고, 실측으로 고치고, 격리 검증까지 거친 17문서 거버넌스 프레임워크입니다.
코드 빌드 없음 — 치환 항목은 PLACEHOLDERS.md 표 한 장 분량의 텍스트 치환이 전부입니다.
전수 감사에서 규칙 결함 110건(치명 2·주요 60·경미 48)을 확정하고, 5단계 재설계로 반영했습니다.
문서별 감사관 21 + 발견 전건을 "기각이 기본자세"로 재검증한 반박 검증관 111 + 시스템 실사 1.
세션 부팅 필수 독서량 최대 93KB → 9.6KB. 필수는 헌법 + 부팅 매니페스트 단 2개 문서입니다.
감사 발견 111건 중 반박 검증에서 기각된 것은 1건. 이 프레임워크의 결함 목록은 추측이 아니라 실측입니다.
재설계 결과를 깨끗한 별도 세션이 9개 항목으로 실측 판정 — 작성자와 검토자 둘 다 놓친 결함 2건을 추가로 잡아냈습니다.
감사 → 승인 → 5단계 재설계 → 격리 검증까지 하루. 모든 단계가 커밋된 복원 지점 위에서 진행돼 언제든 되돌릴 수 있었습니다.
모든 수치는 2026-07 실제 감사·재설계·격리 검증 기록의 실측치입니다. 추정치·벤치마크 아님.
WHY — 실제로 일어났던 일
이 프레임워크는 이론이 아니라 부검 보고서에서 태어났습니다. 아래 세 가지는 실제 운영 환경의 전수 감사에서 실측으로 확인된 붕괴 패턴입니다.
같은 규칙을 여러 문서에 복사하면, 한쪽만 갱신되는 순간부터 문서들이 서로 다른 답을 합니다. 검증 기준·파일명 규칙·우선순위가 문서마다 달라져 어느 쪽을 따라도 누군가에겐 위반이 됩니다.
실측: "보안 vs 사용자 지시" 우선순위에 3개 문서가 3가지 답 — 세션이 읽는 문서에 따라 정반대로 행동
"통합했다"는 기록만 남고 원본이 살아남으면, 폐기됐어야 할 문서가 몇 주씩 정본 행세를 합니다. 에이전트는 어느 것이 진짜인지 판단할 수 없고, 유지보수는 모든 사본을 고쳐야 하는 일이 됩니다.
실측: 통합 선언 후 8주간 통합본 2 + 폐기 대상 원본 5가 전부 "active"로 병존
작업한 세션이 스스로 검증하면 자기 작업을 관대하게 봅니다. 규칙을 만든 자가 규칙 준수를 검사하면, 정본 문서가 자기 규칙을 어기고 있어도 아무도 모릅니다.
실측: 격리 세션 검증이 작성자·검토자 둘 다 놓친 결함 2건 적발 (자기규칙 위반 포함)
CAPABILITIES — 숨어 있는 10가지 장치
각 장치는 위 붕괴 패턴 중 하나를 구조적으로 막습니다. 전부 실제 사고에서 역산해 설계됐습니다.
충돌 우선순위의 정본은 헌법 한 곳뿐. 다른 문서의 서열 서술은 전부 포인터로 강등되고, 문구가 갈리면 헌법이 이깁니다. "어느 문서를 먼저 읽었는가"가 행동을 바꾸지 못하게 합니다.
모든 세션의 필수 독서는 헌법 + 매니페스트 2개(합계 15KB 이내). 나머지 15개 문서는 "파일 작업을 할 때만", "인수인계할 때만" 조건부로 로드됩니다. 토큰과 시간을 태우는 부팅 의식이 사라집니다.
기획·구현·검증은 도구가 아니라 세션의 역할입니다. 구현 세션은 자기 작업을 검증해 "완료"를 선언할 수 없고, 검증은 아무것도 구현하지 않은 깨끗한 세션이 실측으로만 합니다.
"작업지시서(ORDER)는 사용자 승인이 아니다" — 무인 워커가 지시서를 승인으로 오인해 고위험 작업을 수행하는 사고를 원천 차단합니다. 킬스위치 파일, 고위험 작업의 무인 금지, 보류 후 에스컬레이션 절차까지 정본화되어 있습니다.
모든 문서가 frontmatter에 public / internal / pii 등급을 가집니다. 공개 사이트 발행은 public만 통과 — 기밀 메모가 블로그로 새는 경로가 메타데이터 수준에서 막힙니다.
5개 초과 파일의 일괄 작업·인덱스 재생성 전에는 git checkpoint 커밋이 관문입니다. 실패해도 명령 한 줄로 복원 — 실제 재설계 전 과정이 커밋된 복원 지점 위에서 안전하게 진행됐습니다.
릴레이·검색·수집 폴더·훅 등 실제 가동 중인 시스템의 명부. 새 세션이 "이 환경에 뭐가 있는지"를 추측하지 않고 조회합니다. 감사에서 가동 시스템 13종 중 9종이 규칙에 없었던 것이 이 문서가 생긴 이유입니다.
하네스 규칙의 의미가 바뀌면 반드시 이력 장부에 남깁니다. "누가 언제 왜"가 없는 규칙 변경은 몇 주 뒤 아무도 설명 못 하는 모순이 됩니다 — 실제로 7주 기록 공백이 유령 문서 사태의 공범이었습니다.
문서에 날짜·개수를 박제하지 않습니다. "인덱스가 6월 16일자다" 대신 "수정일을 비교해 뒤처졌으면 재색인하라"는 판정 절차문으로 씁니다. 쓰는 순간부터 낡는 문장이 구조적으로 사라집니다.
"의미 검색에 안 나옴 ≠ 존재하지 않음." 색인 크기 상한처럼 검색 도구가 조용히 놓치는 지점을 규칙이 명시해, 에이전트가 대형 문서를 '없는 것'으로 오판하는 사고를 막습니다.
사용자 고유 값은 전부 {{VAULT_ROOT}} 형식 플레이스홀더입니다. 개인정보 유출 검사 3중 게이트(정제 17 + 유출 사냥 17 + 결정론 스캔 60패턴)를 통과한 순수 원본만 배포됩니다.
혼자 쓰는 단독 세션과 릴레이·다중 세션 협업이 같은 문서로 굴러갑니다. 모든 절차 문서에 두 모드의 분기가 명시되어, 규모를 키울 때 규칙을 다시 쓸 필요가 없습니다.
PROOF — 이 문서 세트는 이렇게 만들어졌습니다
v2는 이 4단계 파이프라인을 거쳐 만들어졌습니다. 파이프라인은 체크리스트·방법론 문서로 저장소에 함께 배포되어, 여러분의 규칙도 같은 방식으로 검증할 수 있습니다.
문서별 독립 감사관이 모든 사실 주장(경로·날짜·규칙·역할)을 파일시스템과 git 실측으로 대조합니다. 인상 비평 금지, 근거 없는 발견 금지.
발견 전건을 "기각이 기본자세"인 별도 검증관이 재검증합니다. 원문 재인용 + 재실측에서 살아남은 것만 확정 — 기각률 0.9%가 목록의 신뢰도입니다.
수정 계획이 확정 발견 110건을 빠짐없이 커버하는지 역방향으로 대조합니다. 이 단계가 계획의 공백 11건과 불일치 2건(진입 순서가 정반대였던 오류 포함)을 실행 전에 잡았습니다.
구현에 관여하지 않은 깨끗한 세션이 체크리스트 9종을 실측 판정합니다. 파일 수정 권한 없음, 보고만 — 자기 채점의 관대함이 끼어들 자리가 없습니다.
GETTING STARTED — 설치 후 바꿔야 할 것들
전부 텍스트 편집입니다. 코드 빌드도, 의존성 설치도 없습니다. 1~4단계만 끝나면 가동되고, 5~6단계는 운영하면서 천천히 하면 됩니다.
17개 .md 파일을 자신의 Obsidian Vault(또는 어떤 마크다운 저장소든) 안의 00_Harness/ 폴더로 복사합니다.
에디터에서 {{ 를 전역 검색하면 바꿔야 할 곳이 전부 나옵니다. 핵심은 6개: {{VAULT_ROOT}}(저장소 경로) · {{CODE_ROOT}}(코드 폴더) · {{HTML_DOCS_DIR}}(산출물 수집 폴더) · {{WORK_LOG_DIR}}(작업 일지) · {{USER_NAME}}(자기 호칭) · {{CHECKPOINT_TIMES}}(일지 시각). 나머지는 PLACEHOLDERS.md 표에 전부 정리되어 있고, 안 쓰는 기능의 플레이스홀더는 그 줄을 지우면 됩니다.
project-mission-context.md — 내 조직·미션·핵심 프로젝트를 골격에 채웁니다 (작성 안내 주석이 들어 있음). agent-systems-registry.md — 내 환경에서 실제 돌아가는 시스템(검색 도구·수집 폴더·릴레이 등)을 명부에 등재합니다. 없으면 예시 행을 지우고 비워둬도 됩니다 — 나중에 생길 때마다 한 줄씩 추가하는 문서입니다.
CLAUDE.md / GEMINI.md / AGENTS.md 등 사용하는 도구의 진입 파일에 아래 3줄을 넣으면, 어떤 AI로 세션을 열어도 같은 하네스로 부팅됩니다.
agent-role-definitions.md에서 어떤 도구에게 어떤 역할을 줄지 조정합니다 (혼자 + AI 1개면 역할 절반은 삭제해도 됩니다). agent-decision-rules.md의 에스컬레이션 기준(예: "50개 이상 파일 수정 시 확인")을 자기 위험 감수 수준으로 조정합니다. {{CORE_PROJECT}} 기술 선택 정책(예시: Rust 우선)은 자기 스택으로 교체하거나 절을 삭제합니다.
harness-change-history.md에 "v2 템플릿 도입" 1건을 기록하면 설치 끝. 이후 규칙을 고칠 때마다 이 장부에 한 줄씩 남기는 습관이 이 시스템의 심장입니다. 분기별로 저장소에 동봉된 verification-checklist.md(체크 9종)를 깨끗한 새 세션에 시키면 규칙 부패를 조기에 잡습니다.
PACKAGE — 받게 되는 것
규칙 붕괴는 AI를 늘리는 모든 환경에서 같은 순서로 일어납니다 — 이 프레임워크는 그 순서를 이미 한 번 끝까지 겪고 나온 결과물입니다.