---
name: harness-update
description: 기존 harness_setup/의 검사·로컬 환경을 현재 코드와 진행 상태에 맞춰 갱신하고 실제 실행으로 확인한다. 검증 수단 누락·낡은 명령·환경 실패·흔들리는 테스트를 다룰 때 사용한다.
---

# 하네스 갱신

실제 요구를 계속 검증할 수 있도록 하네스를 필요한 만큼 고친다.

## 입력과 최소 산출물

- 기존 `harness_setup/HARNESS.md`·`quality_gates/`·관련 스크립트, 변경 코드·실행 결과를 읽는다.
- 관련 태스크의 수용 기준·`verification`·상태, `plan_setup/STATE.md`·`LOG.md`, 영향 있는 설계와 합의를 확인한다.
- `docs/PRD.md`의 `## 자율운영 합의`, 실행 중이면 `loop_setup/LOOP.md`와 잔여 예산을 이어받는다.
- 산출물은 영향 있는 하네스 정의·환경 설정의 부분 수정과 `plan_setup/LOG.md`의 변경·검증 근거다.
  하네스가 없으면 필요한 `harness-setup` 절차를 같은 요청 안에서 수행한다.

## 갱신 판단

시작 전에는 다음 작업을 판정할 수단·데이터·의존 서비스가 있는지 확인한다.
완료·차단 해소·설계 변경 뒤에는 활성 범위와 누락된 검증을 맞춘다.
이미 맞는 하네스를 의례적으로 다시 만들거나 모든 태스크마다 전체 검사를 반복하지 않는다.

실패가 원인이면 실행 결과와 이력을 먼저 읽고 코드 결함·검사/문서 불일치·환경·흔들림·판정 불가를 가른다.
같은 실패가 작업을 넘어 반복되면 테스트 데이터·준비 판정·공유 DB/포트·선택자 등 공통 원인을 조사한다.
반복 횟수만으로 특정 원인을 확정하지 않는다.

- 코드 결함이면 실행 요청 범위 안에서 코드를 고치고 회귀 검증까지 이어 간다.
- 낡은 검사·문서면 현재 합의와 요구를 근거로 맞춘다. 요구 충족 여부를 바꾸는 수정과 단순 표현 보정을 구분한다.
- 환경·흔들림이면 준비 조건·데이터 격리·대기·관찰 수단을 고치고 결과가 안정됐는지 확인한다.
- 수단이 없으면 합의 안에서 갖추거나 동등한 실제 관찰로 대체한다. 판정할 수 없으면 미검증으로 남긴다.

화면 제품은 디자인 정본의 유효한 승인 방향·버전·품질 기준과 대표 화면·주요 상태의 실제 렌더링 대조를 갱신한다.
기능 통과만으로 시각 적합성을 대신하거나 검증자가 기준선을 바꾸지 않는다. 승인 범위 안의 구현 복구와 사용자 결정이 필요한 새 방향을 구분한다.

## 필수 제약

제품 최종 완료는 필요한 네 게이트와 포함 범위 수용 기준의 실제 증거로 닫는다.
`lint`는 정적 오류, `unit`은 기능/계약, `e2e`는 실제 성공·실패 흐름, `task_validation`은 독립 수용 관찰을 담당한다.

- 모든 게이트의 판정 중 제품 소스·수용 기준·통과 단언을 자동 수정하지 않는다(`--fix`·포매터 쓰기·스냅샷 갱신 등).
  수정은 구현 단계에서 수행하고 영향받은 판정을 무효화해 재검증한다. 기준을 바꾸지 않는 허용된 테스트 데이터 준비는 가능하다.
- 기존 ID·파일 경로·절 참조·사용자 변경·완료 이력·검증 범위를 보존한다. 바뀐 곳만 고친다.
- 제품 Loop의 `harness_setup/quality_gates/` 네 정의와 HARNESS·태스크 `verification` 연결을 확인하고 누락은 복구한다.
  제품 Loop 판정 순서는 `lint → unit → e2e → task_validation`이며 앞 실패 복구 전 뒤의 완료 판정은 금한다.
  현재 코드·설정·의존성·데이터 조건과 영향이 같다는 근거로 결과를 재사용하거나 같은 코드 상태의 태스크를 묶을 수 있다.
  수용 기준의 태스크별 대응을 남기며 검증 전 completed 처리나 후행의 완료 선행 사용을 금한다.
  준비 미활성은 PASS가 아니며 준비 증거·후속 활성 담당/시점과 연결한다.
  문서·세팅만 요청과 작은 독립 수정에는 전체 파이프라인을 강제하지 않는다. 기존 Loop의 작업 범위에 속하는 제품 변경은 계약을 계승한다.
  LOOP.md의 존재만으로 새 독립 요청을 편입하지 않으며 현재 요청·유효한 합의·태스크 연결로 범위를 판단해 기록한다.
  사용자 명시 기본값 변경·자식 금지는 우선하며 바뀐 보장과 미검증을 남긴다.
- 제품 Loop의 task_validation은 해당 변경을 구현하지 않은 비상속 별도 세션이 맡는다.
  같은 모델은 가능하나 구현 대화·추론·자체 통과 결론 상속이나 같은 세션 역할 변경은 독립 검증이 아니다.
  요구·수용 기준·필요 설계·대상 코드 식별·환경/접속·허용 데이터/권한·잔여 예산을 제공하고 코드/diff 열람은 허용한다.
  운영 제약은 필요한 절만 전달하고, 구현 추론·자체 판정이 담긴 STATE/LOG 전체를 검증 입력으로 넘기지 않는다.
  검증자는 제품·수용 기준·통과 단언을 수정하지 않으며 직접 수정한 변경은 다른 독립 검증자가 판정한다.
  실제 관찰의 기준별 PASS/FAIL·환경 문제/판정 불가와 재현 증거를 완전히 회수한다.
  세션 생성·테스트 재실행·코드 리뷰·구현자 보고만으로 제품 PASS를 대신하지 않는다.
- 초기 실행·누락 도구는 preflight에서 발견해 허용된 준비와 실제 실행을 확인한다.
  다른 OS 요구는 그 OS의 실제 실행 수단을 직접 확인해(Windows면 `wsl -l -v`의 배포판 등) 있으면 게이트와 독립 검증에 포함한다.
  공유 DB 초기화·마이그레이션·시드 명령과 실제 접속 대상, 앱의 대상 코드/미커밋 변경·데이터 동일성을 확인한다.
  검증 중 앱/DB 교체를 막고 필요한 영역만 격리한다. 포트 열림만으로 readiness를 판단하지 않는다.
- `활성/부분 활성/미활성/대기`를 실제 범위와 맞춘다. 차단 해소는 남은 차단 근거까지 확인한다.
  실패·차단·미활성을 목록에서 숨겨 프로젝트 성공으로 합산하지 않는다.
- 검사 정의는 대상·실제 명령/관찰·통과 조건·전제를 유지한다. 숫자 기준이면 실제 측정 수단도 맞춘다.
- 실패를 통과시키기 위한 단언 삭제·검사 대상 축소·활성 연기/되돌림·임계 완화·재시도 추가는 하지 않는다.
  사용자의 명시 변경이나 기존 합의가 기준을 바꾸면 그 근거와 검증 영향부터 문서에 반영하고 적용한다. 같은 결정을 재승인받지 않는다.
- 합의 안의 통상적 코드·테스트·의존성·로컬 환경·관련 문서 조정은 자율 수행한다.
  기술·설계가 바뀌면 영향 있는 앞 문서부터 맞추며 필요한 스킬 지침을 읽어 이어 수행한다.
- Loop 전 사용자만 결정할 미해소 경계는 묶어 해소한다. Loop 이후에는 사용자 질문·수동 명령 요청 0회다.
  새 권한이 필요하면 우회하지 않고 허용된 대안이나 독립 작업을 진행한 뒤 최종 미완료로 종료한다.
- 실행 중에는 현재 필자와 안전한 경계에서 갱신한다. 병렬이면 공유 하네스·STATE·LOG 필자를 하나로 둔다.
  기존 필자가 관리하는 상태를 다른 워커가 덮어쓰지 않는다.
- 기존 실행 명령을 우선 사용한다. 준비 스크립트가 바뀌면 실행·상태·로그·종료 방법도 맞춘다.
  데이터 초기화·프로세스 정리는 합의한 자원만 다루고 비밀값을 노출하지 않는다.
- 루트 지침은 필요한 포인터만 수정한다. 감시·질문·슬롯 관리 플랫폼을 새로 만들지 않는다.

## 완료 증거와 실행 재개

변경한 명령·관찰 경로를 실제로 실행하고 영향 받은 검사와 필요한 회귀 검사를 확인한다.
로그에는 변경 이유·관련 ID·관찰 결과·실패 분류·남은 미검증과 증거 경로를 남긴다.
환경 부재·예산 소진·테스트 0건·전부 skip·서비스 미실행·종료 코드 0만으로 통과시키지 않는다.
하네스 변경에도 누적 시도·전략·전체 사용 예산을 초기화하지 않는다. 중요한 전환마다 대상 문서·STATE·LOG를 증분 저장하고
채택 로그·관찰·코드/환경 식별은 지속 경로에 보존한다.
복구 시도와 차단 원인·변경 보존 위치·재개 명령/조건을 STATE·LOG와 최종 보고에 남긴다.

세팅/점검만 요청하면 하네스 갱신 결과로 끝낸다.
진행 중 실행의 일부라면 하네스만 고치고 사용자에게 넘기지 말고 원래 작업의 구현·재검증·완료/최종 미완료까지 이어 간다.

## 환경 참고

호스트의 실행·권한 차이가 관련될 때만 읽는다.
- [Claude Code](references/claude-code.md)
- [Codex](references/codex.md)