---
name: harness-setup
description: 프로젝트의 수용 기준에 맞는 검증 하네스와 로컬 실행 환경을 harness_setup/에 준비한다. 하네스·테스트 파이프라인·로컬 환경을 처음 세팅할 때 사용하며 기존 하네스 갱신은 harness-update로 다룬다.
---

# 하네스 세팅

수용 기준을 실제로 검사할 수단을 갖추고, 다음 실행자가 같은 환경과 결과를 재현하게 한다.

## 입력과 범위

- 코드·기존 실행/테스트 설정, 관련 `docs/PRD.md`·`docs/TRD.md`·`docs/ARCHITECTURE/`, `plan_setup/`을 읽는다.
- PRD의 `## 자율운영 합의`와 기존 허용·금지·예산을 먼저 확인한다. 대화에서 확정한 내용도 문서에 보존한다.
- 문서가 부족하면 요청 범위의 목표·수용 기준·실행 전제만 보완한다. 전체 문서 파이프라인을 선행 조건으로 삼지 않는다. 다만 새 제품을 Loop까지 진행하는 요청이면 빠진 앞 단계를 해당 스킬로 진행해 단계마다 결과 보고·진행 확인을 받는다.
- `harness_setup/`이 이미 있으면 현재 상태를 읽고 필요한 갱신만 수행한다.

## 환경 조사와 결정

1. OS·셸·런타임·패키지 명령·외부 의존·현재 권한을 확인한다. 기존 실행·검증 명령을 우선 사용한다.
   요구가 다른 OS 동작을 포함하면 그 OS에서 실제 실행할 수단을 직접 확인해(Windows면 `wsl -l -v`의 배포판 등) 게이트와 독립 검증에 넣고, 수단이 없을 때만 미검증으로 남긴다.
2. 현재 제공된 도구·CLI 도움말에서 브라우저/HTTP/CLI/DB 관찰, 필요시 독립 검토 수단을 확인한다.
   제품 이름만으로 UI·서브에이전트·자동 호출의 가능 여부를 단정하지 않는다.
3. 조사로 알 수 없는 목적·제약·권한·비용/데이터 경계·예산·실패 대안만 Loop 전에 묶어 해소한다.
   기존 합의로 결정할 수 있는 도구 구성과 통상적 로컬 준비는 재승인 없이 수행한다.
4. 합의 밖 필수 결정이 남으면 준비 완료로 표시하지 않는다. Loop 중 호출됐다면 질문 없이 허용된 대안·독립 작업·최종 미완료 처리를 따른다.

## 최소 산출물

`harness_setup/HARNESS.md`에 다음 정보를 짧게 남긴다.

- 실행 전제, 로컬 준비/실행·상태 확인·로그·종료 방법과 실제 접속 주소.
- 검증 목록과 관련 수용 기준/요구 ID, 실행 시점, 검사 정의 위치.
- 브라우저 등 실제 관찰 수단, 필요한 테스트 데이터와 의존 서비스, 현재 미검증 범위·한계.

`harness_setup/quality_gates/`에는 요청 범위의 검사 정의를 둔다. 제품 Loop는 네 이름의 정의를 모두 두고 HARNESS·태스크에서 연결한다.
각 정의는 대상·근거 기준, 실제 명령 또는 관찰 방법, 통과 조건, 전제와 활성 범위를 담는다.
제품 Loop는 `lint → unit → e2e → task_validation` 판정 순서와 태스크 `verification` 연결을 유지한다.
앞 실패 복구 전에 뒤의 완료 판정을 열지 않는다. 현재 코드·설정·의존성·데이터 조건과 영향이 같다는
근거로 결과를 재사용하거나 같은 코드 상태의 태스크를 묶어 검사할 수 있다. 각 수용 기준의 태스크별
대응을 남기며 검증 전 `completed` 처리나 후행의 완료 선행 사용을 금한다.
준비 미활성은 PASS가 아니다. 준비 자체의 증거와 후속 활성 담당/시점을 연결하고 제품 완료와 구분한다.
문서·세팅만 요청과 작은 독립 수정에 전체 파이프라인을 강제하지 않는다. 기존 Loop의 작업 범위에 속하는 제품 변경은 계약을 계승한다.
LOOP.md의 존재만으로 새 독립 요청을 편입하지 않으며 현재 요청·유효한 합의·태스크 연결로 범위를 판단해 기록한다.
사용자 명시 기본값 변경·자식 금지가 우선하며 바뀐 보장과 미검증을 기록한다.
구판 PLAN의 `Layer 4로 넘기는 검증`이나 숫자 기준도 누락 없이 검사·묶음 측정·한계 중 어디에서 다룰지 연결한다.

`harness_setup/scripts/`에는 기존 명령으로 해결되지 않는 준비·실행 스크립트만 만든다.
필요하면 확인한 OS에 맞는 `local-dev.ps1` 또는 `local-dev.sh`를 사용한다.
기존 패키지 스크립트·서비스 관리 기능으로 충분하면 새 래퍼를 만들지 않는다.
복잡한 범용 구동기·감시·질문 플랫폼을 생성하지 않는다.

화면 제품은 디자인 정본의 승인 방향·버전·품질 기준과 대표 화면·주요 상태의 실제 렌더링을 대조할 수단과 지속 증거를 준비한다.
사람의 디자인 승인은 기능 게이트·독립 task_validation을 대체하지 않는다. 검증자는 승인 기준선을 바꾸지 않고 불일치를 반환한다.

## 필수 제약

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

- 모든 게이트의 판정 중 제품 소스·수용 기준·통과 단언을 자동 수정하지 않는다(`--fix`·포매터 쓰기·스냅샷 갱신 등).
  수정은 구현 단계에서 수행하고 영향받은 판정을 무효화해 재검증한다. 기준을 바꾸지 않는 허용된 테스트 데이터 준비는 가능하다.
- 화면 기준은 브라우저/실행 E2E로, 비화면 기준은 HTTP·CLI·DB 등 적합한 수단으로 확인한다.
  중요한 실패 경로와 실제 저장·다시 조회 결과도 기준에 맞게 검사한다.
- 코드 작성·종료 코드 0·테스트 0건·미실행을 기능 완료 증거로 대신하지 않는다.
  기존 `활성/부분 활성/미활성/대기`는 보존하고 적용 범위를 적는다. 미활성·대기는 통과가 아니다.
- 제품 Loop의 task_validation은 해당 변경을 구현하지 않은 비상속 별도 세션이 맡는다. 같은 모델은 가능하나
  구현 대화·추론·자체 통과 결론을 상속한 자식과 같은 세션 역할 변경은 독립 검증이 아니다.
  요구·수용 기준·필요 설계·대상 코드 식별·환경/접속·허용 데이터/권한·잔여 예산을 주고 코드/diff 열람은 허용한다.
  운영 제약은 필요한 절만 전달하고, 구현 추론·자체 판정이 담긴 STATE/LOG 전체를 검증 입력으로 넘기지 않는다.
  검증자는 제품·수용 기준·통과 단언을 고치지 않는다. 직접 수정한 변경은 다른 독립 검증자가 판정한다.
  실제 관찰에 따른 기준별 PASS/FAIL·환경 문제/판정 불가·재현 증거를 완전히 회수한다.
  세션 생성·테스트 재실행·코드 리뷰·구현자 보고만으로 제품 PASS를 대신하지 않는다.
- 초기 실행·도구 누락은 preflight에서 발견해 허용된 준비와 실제 실행으로 확인한다.
  공유 DB 초기화·마이그레이션·시드 명령과 실제 접속 대상을 확인하고 충돌 데이터만 격리한다.
  앱이 대상 코드/미커밋 변경·데이터를 서비스하는지 확인하고 검사 중 교체를 막는다.
  포트 열림·프로세스 존재만으로 readiness를 판정하지 않고 실제 요청과 필요한 준비 상태를 확인한다.
- 준비 명령은 반복 실행에 안전해야 한다. 데이터 초기화는 합의한 테스트 데이터 범위에 한정한다.
  프로세스 종료는 직접 띄운 프로세스의 신원을 확인하고 수행한다. 이름이나 재사용될 수 있는 PID만으로 종료하지 않는다.
- 비밀값은 예시·로그에 넣지 않는다. 병렬 실행을 쓰면 파일·DB·포트 충돌을 격리하거나 해당 검사를 직렬화한다.
- 실패를 숨기려고 검사·수용 기준을 낮추지 않는다. 합의 안의 코드·테스트·환경·문서 불일치는 원인에 맞게 고친다.
  영향 있는 앞 문서부터 필요한 부분만 맞추고 기존 ID·절 참조·사용자 변경·완료 상태를 보존한다.
- 루트 지침은 후속 실행에 필요한 하네스 포인터만 보완한다. 양쪽 루트 문서를 매번 전체 동기화하지 않는다.

## 완료 증거와 연결

작성·변경한 실행 방법과 선택한 검사를 실제로 돌려 명령·대상·관찰·판정·미실행 이유를 남긴다.
준비만 가능하고 제품 코드가 없다면 하네스 준비 결과와 기능 미검증을 구분한다.
전부 skip·서비스 미실행도 PASS가 아니다. 중요한 전환마다 HARNESS·태스크·STATE·LOG의 영향 부분을 증분 저장한다.
채택 로그·스크린샷·트레이스와 대상 코드/환경 식별을 지속 경로에 보존하며 임시 경로만 남기지 않는다.

보고에는 준비된 수단, 확인한 결과, 남은 한계와 재개 조건을 적는다.
사용자가 세팅·문서화만 요청하면 그 범위에서 끝내고 다음 스킬을 제안한다.
다음 단계는 `loop-setup`이다. 단계를 마치면 결과(요약·주요 결정·가정·남은 결정)를 보고하고 다음 스킬로 이어 진행할지 사용자에게 확인한다. 수정 요청은 반영해 다시 보고한다. Loop 실행 전까지 모든 단계에 적용하며, 사용자가 자기 말로 단계별 확인 생략을 지시했을 때만 확인 없이 이어 간다. '만들어줘'·'끝까지'나 사전 권한·예산 합의만으로는 생략하지 않고, 에이전트는 확인 생략이나 자동 진행을 먼저 권하거나 추천하거나 생략 방법을 안내하지 않으며, 그렇게 받은 선택도 근거가 아니다. 진행이 확인되면 실행을 사용자에게 떠넘기지 않는다. 합의가 충족되지 않았으면 이어 가지 않는다.

## 환경 참고

현재 호스트에서 실제 차이를 확인할 때만 읽는다.
- [Claude Code](references/claude-code.md)
- [Codex](references/codex.md)