ai-rules › handbook › Harness Engineering

Harness Engineering

`ai-rules`를 "규칙 문서 모음"에서 "정책을 실제로 집행하는 시스템"으로 확장하기 위한 공통 가이드

guide 2026-04-01 docs/guide/HARNESS_ENGINEERING.md

작성일: 2026-04-01
목적: ai-rules를 "규칙 문서 모음"에서 "정책을 실제로 집행하는 시스템"으로 확장하기 위한 공통 가이드

1. 왜 필요한가

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

핵심 구분:

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

한 줄 요약:

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

2. 현재 시스템의 강점

ai-rules는 이미 일부 하네스 성격을 갖고 있다.

  • core/, extensions/, profiles/, adapters/를 통해 정책을 중앙 관리
  • scripts/sync.mjs로 여러 도구에 동일 정책 배포
  • generated output을 프로젝트별로 일관되게 생성
  • governance adapter를 통해 .ai-governance/ 설정까지 자동 생성

즉, 현재 구조는 단순 문서 저장소가 아니라 policy distribution system에 가깝다.

3. 아직 부족한 하네스

현재는 "정책을 잘 퍼뜨리는 것"은 강하지만, "위험한 실행을 실제로 막는 것"은 약하다.

대표적인 공백:

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

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

4.1 sync 단계

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

추가 후보:

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

4.2 세션 시작

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

추가 후보:

  • SESSION.md 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. 결론

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