Keystone Harness Engineering
Overview Archive
03 하네스 Markdown

Harness Engineering

규칙 문서 모음을 정책 집행 시스템으로 확장하는 하네스 설계 가이드 — Policy는 말해주고 Harness는 막는다

Source
src/content/docs/harness-engineering.md
Order
52

한눈에 보기

Harness Engineering은 “규칙을 잘 쓰는 것”과 “규칙이 실제로 지켜지게 만드는 것”을 분리하는 설계 문서입니다. KeystoneHub 하네스 체계의 출발점이 된 원전 가이드를 공개용으로 정리했습니다.

1. 왜 필요한가

규칙은 에이전트에게 원칙을 설명하지만, 그 자체로 행동을 강제하지는 못합니다. 따라서 위험한 작업을 줄이려면 문서형 정책과 별도로 실행 하네스가 필요합니다.

핵심 구분:

  • Policy: 무엇을 해야 하고 무엇을 금지하는지 설명
  • Harness: 그 정책이 실제로 지켜지도록 차단, 승인, 검증, 기록을 수행

한 줄 요약:

Policy는 말해주고, Harness는 막는다.

2. 규칙 배포 시스템의 강점

규칙 원천 저장소는 이미 일부 하네스 성격을 갖고 있었습니다.

  • core/extensions/profiles/adapters 구조로 정책을 중앙 관리
  • sync 스크립트로 여러 도구에 동일 정책 배포
  • generated output을 프로젝트별로 일관되게 생성
  • governance adapter를 통해 거버넌스 설정까지 자동 생성

즉, 단순 문서 저장소가 아니라 policy distribution system에 가깝습니다.

3. 아직 부족했던 하네스

“정책을 잘 퍼뜨리는 것”은 강하지만, “위험한 실행을 실제로 막는 것”은 약했습니다.

대표적인 공백:

  • sync 공급망 검증 없음
  • 금지 패턴 우회에 대한 의도 기반 판정 부족
  • 세션 handoff의 출처 신뢰 문제
  • 규칙 충돌 시 해석이 분산 문서에 의존
  • 사고 발생 시 결정 근거 추적 부족
  • 승인 요청이 형식적 클릭으로 끝날 수 있음

4. 하네스가 들어가야 할 지점

4.1 sync 단계

목적: 규칙 공급망 오염 방지

추가 후보:

  • 생성 전후 diff 출력
  • 새 block / 새 섹션 / 새 extension 출처 표시
  • allowlist 밖 헤더나 block id 경고
  • apply 전 사용자 확인

4.2 세션 시작

목적: handoff 정보의 무비판적 신뢰 방지

추가 후보:

  • handoff의 next 항목을 참고 정보로만 취급
  • push, deploy, DB 변경 같은 고위험 next는 현재 상태 재검증
  • handoff provenance 같은 출처 필드 도입

4.3 명령 실행 직전

목적: 패턴이 아니라 작업 효과로 위험 판정

추가 후보:

  • 가역성 체크
  • 영향 범위, 데이터 손실, 외부 상태 변경 여부 평가
  • 고위험이면 사람 승인 또는 사람 직접 실행 전환

4.4 승인 요청 시

목적: approval fatigue 방지

추가 후보:

  • 단순 “응” 대신 typed confirmation
  • 작업 내용을 포함한 재입력 문구 사용
  • Tier별 승인 강도 차등 적용

4.5 세션 종료

목적: audit trail 축적

추가 후보:

  • 왜 이 방식을 선택했는지
  • 어떤 대안을 고려했는지
  • 어떤 규칙을 적용했는지
  • 남은 리스크가 무엇인지

5. Policy와 Harness의 역할 분담

문서에 둘 것

  • 우선순위
  • 금지/허용 원칙
  • 승인 기준
  • 충돌 매트릭스

manifest나 구조화 데이터에 둘 것

  • action taxonomy
  • risk tier
  • approval mode
  • never override 목록

코드 하네스에 둘 것

  • diff gate
  • preflight risk check
  • typed confirmation
  • handoff 재검증
  • audit log 자동 기록

6. 설계 원칙

  • 핵심 규칙은 짧고 강하게 유지
  • 긴 설명과 사례는 handbook으로 분리
  • 패턴 금지는 빠른 감지용으로만 사용
  • 최종 판정은 가역성과 영향 범위 기준으로 수행
  • handoff는 신뢰의 근거가 아니라 참고용 힌트로 본다
  • 고위험 작업은 “설명”이 아니라 “절차”로 막는다

7. 점진 도입 순서

효과 대비 우선순위:

  1. 규칙 충돌 매트릭스
  2. 가역성 원칙
  3. 고위험 승인 마찰
  4. sync diff gate
  5. 선택적 결정 로그
  6. handoff provenance 보강

8. 결론

규칙 체계의 다음 단계는 규칙을 더 많이 쓰는 것이 아니라, 중요한 규칙을 하네스로 승격하는 것입니다. 문서는 정책을 설명하고, 하네스는 그 정책이 실제로 작동하도록 만들어야 합니다.

Source Notes

이 문서는 KeystoneHub 규칙 원천의 Harness Engineering 가이드(2026-04 작성)를 공개용으로 정리한 것입니다. 이 가이드에서 출발한 하네스 구현 현황은 Policy to Harness Lifecycle에서 확인할 수 있습니다. Provenance: keystone-native.