harness-template

개발 요청 하나를 계획서 작성부터 PR 생성까지 정해진 순서로 끌고 가는 개발 하네스 템플릿입니다. 이 저장소를 클론해서 쓰면 /feature <요청> 한 번으로 아래 흐름이 돌아갑니다.

계획 → 교차검증 → 계약 확정 → 구현 → 게이트(테스트·린트) → 코드 리뷰 → PR 생성 → 보고

요청을 받자마자 코드를 쓰지 않는 것이 핵심입니다. 단계마다 실행기가 할 일을 지시하고, 산출물을 기계로 검사하고, 통과했을 때만 다음 단계로 넘어갑니다. 실패하면 정해진 횟수만큼 고쳐 보고, 그래도 안 되면 멈추고 사람에게 넘깁니다.

특징 세 가지입니다.

• 실행기는 파이썬 표준 라이브러리만 씁니다. 프로젝트의 패키지 설치가 깨져 있어도 검사는 그대로 돌아갑니다.
• 어떤 기술 스택에서도 씁니다. 스택별 지식은 어댑터 파일 한 곳에만 있고, 나머지 코드는 그것을 모릅니다.
• PR 생성까지가 범위입니다. 머지는 하지 않습니다.

용어

이 문서와 코드에서 반복해서 나오는 말들입니다.

말	뜻
런(run)	요청 하나를 PR 까지 끌고 가는 한 번의 작업입니다. 런마다 폴더가 하나 생기고 산출물이 거기 쌓입니다
페이즈(phase)	런을 나눈 8개 단계입니다. 각 단계의 요구와 산출물은 harness/phases/01~08.md 에 있습니다
계약(contract)	이번에 만들 함수와 API 를 미리 적어 둔 문서입니다. 구현 전에 확정하고, 이후 모든 검사의 기준이 됩니다
유닛 / 진입점	계약이 나열하는 함수 하나가 유닛이고, 바깥에서 호출하는 입구(API 경로 등)가 진입점입니다
어댑터(adapter)	스택별 실행 명령을 적어 둔 JSON 파일입니다. 스택을 바꿀 때는 이것만 갈아 끼웁니다
스테이지(stage)	검사 한 종류입니다. 이름 8개(컴파일·린트·의존성·부분 테스트·전체 테스트·E2E·빌드·문서)는 고정이고, 실제 명령은 어댑터가 정합니다
게이트(gate)	통과하지 못하면 다음 단계로 못 가게 막는 검사입니다
역할(role)과 소유 경계	구현 담당·테스트 담당 같은 작업자와, 각자 수정할 수 있는 파일 범위입니다. 남의 범위를 건드리면 검사에서 걸립니다
귀속(attribution)	실패한 검사가 누구의 몫인지 실행기가 가려내는 일입니다
봉투(envelope)	실행기가 표준 출력으로 내보내는 JSON 객체 하나입니다. "지금 할 일" 과 "다음에 칠 명령" 이 들어 있습니다
원장(ledger)	리뷰 지적을 append-only 로 쌓는 기록 파일입니다
승격(promote)	반복해서 나온 지적을 린트 규칙 같은 자동 검사로 올리는 일입니다
캘리브레이션(calibration)	각 스테이지의 실제 소요 시간을 한 번 재 두는 일입니다. 타임아웃 값이 여기서 나옵니다
에스컬레이션(escalation)	자동으로 풀 수 없을 때 진행을 멈추고 사람에게 넘기는 일입니다
PASS_WITH_GAPS	"통과했지만 실행하지 못한 검사가 있다" 는 결과 등급입니다

시작 전 주의사항

1. CLAUDE.md 의 규칙은 자동으로 프롬프트에 주입되지 않습니다. 파이프라인은 harness/config.json 과 harness/phases/03-implement.md 에서 이 파일을 가리킬 뿐이고, 규칙은 작업자가 실제로 읽어야 지켜집니다 (ROADMAP §4).
2. 순차 실행기 scripts/execute.py 는 들어 있지 않습니다. 권한 승인을 건너뛴 채 모델을 돌리는 방식이어서 제외했습니다 (DECISIONS ADR-H005 · ADR-H037).
3. 아직 검증되지 않은 부분이 있습니다. 동봉된 어댑터의 verified 값과 harness/calibration.json 이 미검증 상태이고, 검증 현황은 ROADMAP §6 의 표에 있습니다.

빠른 시작

flowchart LR
    C["git clone"] --> D["CLAUDE.md · docs/ 채우기"]
    D --> I["harness.py init<br/>doctor 통과"]
    I --> K["harness.py calibrate"]
    K --> R["/feature 요청"]

1. 클론한 뒤 문서부터 채웁니다

CLAUDE.md 의 빈칸과 docs/ 아래 7개 문서(PRD · TRD · API_SPEC · ARCHITECTURE · ADR · UI_GUIDE · PIPELINE-LOG)는 빈 골격으로 배포됩니다. 이 문서들이 하네스 설정의 입력이라서, 순서를 바꾸면 설정에서 채울 수 없는 칸이 생깁니다.

하네스가 알아야 하는 것	어느 문서에서 가져오나
어떤 어댑터를 쓸지 (빌드·테스트 명령이 무엇인지)	docs/TRD.md 의 기술 스택
무엇을 만드는지 (계약에 적을 유닛과 진입점)	docs/PRD.md 의 유저 스토리와 기능 요구사항
역할별 소유 경계	docs/ARCHITECTURE.md 의 디렉토리 구조와 레이어
검사가 무엇을 봐야 하는지	CLAUDE.md 의 CRITICAL 규칙
성능·보안의 기준선	docs/TRD.md 의 비기능 요구사항

2. 설정 파일을 만듭니다

하네스의 설정은 harness/config.json 하나입니다. 아래 명령이 harness/profiles/<어댑터>/config.json 을 복사하면서 {{name}} 자리에 프로젝트 이름을 넣어 저장합니다. 하는 일은 그게 전부이고, 이미 harness/config.json 이 있으면 --force 없이는 덮어쓰지 않습니다.

python scripts/harness.py init --adapter nextjs-ts --name my-project

프로필을 미리 두는 이유는 설정 항목 중 기술 스택이 정해지면 답도 정해지는 것이 많기 때문입니다. Next.js 프로젝트라면 소스가 src/ 아래 있고 테스트는 *.test.ts 이므로 소유 경계도 자동으로 정해집니다. 아래가 nextjs-ts 프로필에 이미 들어 있는 값입니다.

항목	채워져 있는 값
역할과 소유 경계	구현 담당은 src/app/** src/components/** src/lib/** 등, 테스트 담당은 src/**/*.test.ts
계약 문서의 절 제목	## 유닛 ## 진입점 ## 오류 어휘 등. 여기 적힌 글자와 harness/templates/contract.md 가 정확히 같아야 합니다
브랜치 규칙	기준 브랜치는 main, 작업 브랜치는 feat- 로 시작, main 직접 push 금지
런당 예산	파일 10개 · 1500줄 · 모델 호출 24회
수정 금지 경로	harness/** docs/** scripts/** .claude/** 등

지금 프로필은 nextjs-ts 하나뿐입니다. 다른 스택이라면 이 명령 대신 harness/profiles/nextjs-ts/config.json 을 harness/config.json 으로 복사한 뒤 위 표의 항목을 고치면 됩니다. 어디가 틀렸는지는 다음 단계의 doctor 가 알려 줍니다.

3. doctor 를 통과시킵니다

설정과 실제 저장소가 어긋난 곳을 실행 전에 찾습니다.

python scripts/pipeline/cli.py doctor

파이썬 버전, 설정 파일 형식, 어댑터가 요구하는 파일의 존재, 실행할 명령의 존재, 역할별 소유 경계의 중복, 계약 문서의 절 제목과 설정의 일치, 원격과 기준 브랜치의 존재를 봅니다.

exit 2 가 나오면 거기서 멈추고 FAIL 항목부터 고칩니다. 경고는 통과시키되 전부 출력합니다. 건너뛴 검사는 통과가 아니어서 마지막 보고서까지 따라갑니다.

4. 캘리브레이션을 한 번 돌립니다

각 스테이지를 한 번씩 실행해 소요 시간을 harness/calibration.json 에 기록합니다. 타임아웃 값과 전체 테스트의 백그라운드 실행 여부가 여기서 나옵니다.

python scripts/harness.py calibrate

5. /feature <요청> 을 칩니다

여기서부터는 파이프라인이 끌고 갑니다.

8단계가 어떻게 돌아가나

한 페이즈는 호출 두 번으로 끝납니다. next 를 치면 실행기가 할 일을 지시하고, 모델이 산출물을 지정된 경로에 쓰고, record 를 치면 실행기가 그것을 검사한 뒤 통과 시 다음 페이즈로 넘깁니다. (04 는 record 대신 gate, 08 은 report 로 닫습니다.)

실행기의 출력은 언제나 JSON 객체 하나이고, 모델이 읽는 것은 "지금 할 일" 과 "다음에 칠 명령" 뿐입니다.

flowchart TD
    P01["01 계획<br/>요청 원문 동결 · 계획서 작성"]
    P02["02 교차검증<br/>계획서 전문을 다른 모델로 검증"]
    P03["03 구현<br/>계약 확정 · 구현·테스트 병렬 작성"]
    P04["04 게이트<br/>스테이지 실행 · 실패 귀속"]
    P05["05 코드리뷰<br/>계약 대조 · 리뷰어 병렬 호출"]
    P06["06 PR<br/>승인 기록 · push · PR 본문"]
    P07["07 PR 리뷰<br/>외부 리뷰 수집 · 규칙 승격"]
    P08["08 보고<br/>런 보고서 작성"]
    DONE(["exit 11 · 런 완료<br/>PR 까지. 머지는 하지 않음"])
    ASK(["exit 9<br/>사람의 판단 대기"])
    STOP(["exit 5 · 7 · 10<br/>에스컬레이션"])

    P01 --> P02 --> P03 --> P04 --> P05 --> P06 --> P07 --> P08 --> DONE
    P02 -. "critical 잔존 시 1회 반려" .-> P01
    P04 -. "실패 시 담당 역할이 수리 (최대 3회)" .-> P04
    P05 -. "지적 반영 후 재검토 (최대 2회)" .-> P05
    P07 -. "변경 요청이 열려 있으면" .-> P07
    P06 -. "승인이 없거나 원격이 없으면" .-> ASK
    P04 -. "수리 기회 소진 또는 동일 실패 반복" .-> STOP

단계	무엇을 하나	무엇이 나오나	언제 통과하고 언제 멈추나
01 계획	사용자의 원본 요청을 동결하고, 그 요청을 빠짐없이 덮는 계획서를 씁니다. 계획의 각 항목에는 요청 원문에서 그대로 따온 문장을 근거로 붙입니다	계획서와 회차별 리뷰 기록	근거가 요청 원문의 부분문자열인지, 요청의 모든 항목이 정확히 한 번씩 덮였는지를 봅니다. 반복해도 수렴하지 않으면 에스컬레이션합니다
02 교차검증	완성된 계획서 전문을 교차검증기에 넘깁니다. 01 의 리뷰는 매 회차의 계획만 봤고 완성본 전체를 본 적이 없기 때문입니다. 교차검증기는 외부 플랜 리뷰 도구(다른 모델)가 primary 이고, 없으면 plan-reviewer 에이전트로 폴백합니다	판정 JSON	critical 이 0건이어야 넘어갑니다. 남으면 01 로 1회 반려합니다. 둘 다 불가한 환경이면 스킵하되 등급을 PASS_WITH_GAPS 로 낮춥니다
03 구현	이번에 만들 유닛과 진입점 목록(계약)을 먼저 확정하고, 역할들이 병렬로 각자의 경로를 채웁니다. 만들 것을 미리 못 박기 때문에 구현과 테스트가 서로를 보고 형태를 맞추는 일이 없습니다	계약 문서와 역할별 작업 목록	소유 경계를 넘은 파일이나 주인 없는 파일이 없어야 하고, 컴파일·타입 검사를 통과해야 합니다
04 게이트	어댑터에 적힌 스테이지를 순서대로 실행하고, 실패를 귀속시켜 해당 역할에만 되돌립니다	스테이지 결과와 귀속 결과	수리 기회는 3회입니다. 기회가 남아도 같은 역할이 같은 실패를 두 번 내면 에스컬레이션합니다. 테스트 0개는 기록만 하고 막지 않지만, 기존 테스트 수가 크게 줄면 막습니다
05 코드리뷰	04 가 "동작하는가" 를 봤다면 05 는 "계약대로 만들었는가, 봐야 할 리뷰어가 실제로 봤는가" 를 봅니다. 비용이 들지 않는 precheck 부터 돌리고, 변경된 파일에 해당하는 리뷰어만 병렬로 부릅니다	계약 대조 결과, 리뷰 결과, 승격 후보	재검토는 2회까지입니다. 리뷰어가 전부 실패했거나 호출된 리뷰어가 0명이면 등급이 PASS_WITH_GAPS 로 내려갑니다
06 PR	승인을 받아 기록으로 남기고, 계약 문서를 삭제한 뒤 원격에 push 하고, PR 본문을 만듭니다. 실제 PR 생성은 메인 세션이 GitHub 도구로 합니다	PR 본문과 PR 생성 요청서	승인이 없으면 exit 9 로 정상 종료하고 사람을 기다립니다. 승인 후 코드가 바뀌면 다시 승인받습니다. 원격과 어긋나면 강제로 덮어쓰지 않고 멈춥니다
07 PR 리뷰	05 가 우리 코드를 우리가 본 것이라면 07 은 외부 리뷰를 받는 단계입니다. 외부 리뷰를 모으고, 원장에 쌓인 지적 중 기준을 넘은 것을 자동 검사 규칙으로 승격합니다	PR 리뷰 결과와 승격 결과	변경 요청이 열려 있으면 멈춥니다. 재검토는 2회까지입니다
08 보고	이번 런의 보고서를 씁니다. 숫자 표는 실행기가 기록에서 조립하고, 원인과 해결은 모델이 씁니다. 코드도 diff 도 보지 않습니다	docs/harness/pipeline/runs/ 아래 보고서	보고서가 부실해도 파이프라인을 실패시키지 않습니다. 다만 실행하지 못한 검사가 통과처럼 보이는 것은 막습니다

어떤 파일이 무엇을 하나

harness/ — 설정과 선언

경로	무엇
config.json	이 프로젝트의 설정 하나입니다. 어댑터, 역할과 소유 경계, 계약 문서의 절 제목, 리뷰어 호출 조건, 런당 예산(파일 수·줄 수·모델 호출 수), 브랜치 규칙이 들어갑니다
config.schema.json	위 파일의 스키마입니다. 검사기는 표준 라이브러리로 직접 만들었고, _ 로 시작하는 키는 주석으로 보고 건너뜁니다
adapters/*.json	스택별 명령 모음입니다. self-python(이 저장소 자신) · nextjs-ts · _template(새로 만들 때 복사하는 빈 틀)
adapters/adapter.schema.json	어댑터의 스키마입니다. 실행 허용 명령 목록이 여기 있습니다 — 실행기 코드에 두지 않습니다
profiles/<어댑터>/config.json	미리 채워 둔 설정 프로필입니다. harness.py init 이 복사하면서 프로젝트 이름만 바꿔 넣습니다
phases/01~08.md	각 페이즈의 정의입니다. 문서 맨 위 JSON 에 요구(requires)·산출(produces)·재시도 상한(loop)이 적혀 있습니다
templates/contract.md	계약 문서의 빈 틀입니다. 절 제목은 config.json 과 글자까지 같아야 하고, 다르면 doctor 가 미리 막습니다
calibration.json	calibrate 의 실측값과 거기서 나온 정책입니다. "미측정" 과 "0초" 를 같은 칸에 쓰지 않습니다

어댑터는 스택 지식을 한 곳에 격리합니다. 스테이지 이름 8개 (compile · lint · check · scoped · full · e2e · build · docs)는 코어가 고정하고, 각 이름에 붙는 실제 명령은 어댑터가 정합니다. 페이즈 정의는 이름만 부르기 때문에 스택을 바꿔도 코어 코드는 한 줄도 바뀌지 않습니다. 명령이 null 인 스테이지는 없는 것이지 통과한 것이 아니고, 결과에도 그렇게 남습니다.

scripts/ — 실행기

경로	무엇
harness.py	설정을 다루는 명령들입니다 — init · doctor · calibrate
pipeline/cli.py	8단계 파이프라인의 입구입니다. 명령을 해석하고, 페이즈 정의를 읽고, 진입 조건을 따지고, 결과를 JSON 으로 내보냅니다
pipeline/state.py	런 폴더와 진행 상태, 이벤트 기록, 작업 트리 해시를 다룹니다. 상태 이름과 등급 이름이 이 파일 하나에서 나옵니다
pipeline/adapters.py	어댑터를 읽고 스테이지를 실행합니다. 판정하거나 상태를 쓰지는 않습니다
pipeline/attribution.py	실패의 귀속을 가려냅니다. 파일도 프로세스도 건드리지 않는 순수 함수라, 실패 상황을 저장해 두었다가 그대로 재현할 수 있습니다
pipeline/contract.py	계약 문서를 파싱하고 실행할 테스트를 골라냅니다. 절 제목이 이 파일에 하드코딩되어 있지 않습니다
pipeline/gate.py	04 의 본체입니다. 스테이지를 순서대로 실행하고 등급을 매깁니다. 전체 테스트는 수리 루프가 끝난 뒤 한 번만 돌립니다
pipeline/trace_contract.py	계약에 적은 것이 코드에 실제로 있는지 5가지로 대조합니다(구현 누락, 오류 상수 누락, 진입점 누락, 테스트 없는 항목, 계약에 없는 새 함수)
pipeline/review.py	변경된 파일을 보고 호출할 리뷰어를 정합니다. 자기가 쓴 코드를 자기가 리뷰할 수 없다는 규칙을 여기서 강제합니다
pipeline/precheck.py	05 에서 가장 먼저 도는 무비용 검사입니다. 예산, 브랜치, 기준 브랜치와의 차이, 환경을 봅니다. 모델도 테스트도 부르지 않습니다
pipeline/mask.py	외부로 나가는 텍스트(PR 본문·코멘트)의 비밀값을 마스킹합니다. 내부 기록에는 원문을 남깁니다
pipeline/pr.py	06 의 본체입니다. 승인과 push, PR 요청서까지 만듭니다. GitHub 을 직접 호출하지 않습니다 — 실행기는 git 명령까지만 실행합니다
pipeline/review07.py	07 에서 내장 리뷰의 호출 여부와 강도를 정해진 규칙으로 정합니다
pipeline/ledger.py	지적 기록을 읽고 씁니다. 읽고 쓰기만 하고 판단하지 않습니다
pipeline/promote.py	쌓인 지적을 자동 검사 규칙으로 올립니다. 실제 적용은 07 에서 런당 한 번뿐입니다
pipeline/report.py	08 입니다. 표는 실행기가 조립하고 설명은 모델이 씁니다
pipeline/verdict.py	산출물이 조건을 맞췄는지 판정합니다. 요청이 동결됐는지, 요청 항목을 빠짐없이 덮었는지, 계획이 범위를 벗어나지 않았는지, 리뷰가 수렴했는지를 봅니다
runtime.py	시각, 대화 기록 읽기, 출력 인코딩처럼 여러 곳이 함께 쓰는 도구입니다
session_log.py	세션 종료 훅이 부르는 기록기입니다. 해석 없이 사실만 남깁니다. 실패해도 세션을 막지 않고, 실패했다는 사실을 기록에 남깁니다

.claude/ — 명령과 에이전트

경로	무엇
commands/feature.md	/feature 명령입니다. doctor 로 열고, 사용자의 요청을 한 글자도 바꾸지 않고 동결한 다음, 종료 코드에 따라 다음 행동을 정합니다
commands/log.md	/log 명령입니다. 세션 기록의 사실을 docs/PIPELINE-LOG.md 에 한 줄로 옮깁니다. 기록에 없는 것은 적지 않습니다
agents/impl-writer.md · agents/test-writer.md	03 이 병렬로 부르는 구현 담당과 테스트 담당입니다. 각자 자기 경로만 건드립니다
agents/plan-reviewer.md	01·02 가 부르는 검토자입니다. 계획을 직접 고치지 않고 지적만 냅니다 — 02 에서는 외부 플랜 리뷰 도구가 없을 때의 폴백입니다
skills/{data-layer,security,architecture,test-quality,docs}-reviewer/SKILL.md	05 의 리뷰어 5종입니다(데이터·보안·구조·테스트 품질·문서). 변경된 파일이 각자의 담당 범위에 걸리면 켜집니다. 문서 리뷰어만 소스 변경이 0인 런에서 켜집니다
settings.json	훅 2개입니다 — 세션 종료 시 기록, 위험한 셸 명령 차단

docs/

경로	무엇
docs/ 바로 아래 7개	프로젝트가 채우는 자리입니다. 빈 골격으로 배포됩니다
docs/harness/ROADMAP.md	이 템플릿의 구성물, 시작 순서, 검증된 것과 아직인 것
docs/harness/DECISIONS.md	왜 그렇게 만들었는지에 대한 결정 기록입니다 (ADR-H001~ADR-H040)
docs/harness/PILOT-LOG.md	런마다 실제로 잰 값입니다. 추정치는 적지 않고, 재보지 않은 것은 "미측정" 으로 남깁니다
docs/harness/pipeline/team-spec.md	8단계의 원본 명세입니다. 동작을 바꾸려면 여기부터 고칩니다
docs/harness/pipeline/ledger/taxonomy.json	지적을 분류하는 어휘의 단일 출처입니다
docs/harness/pipeline/ledger/findings.jsonl	지적 기록입니다. append-only 라서 여러 브랜치가 충돌 없이 합쳐집니다
docs/harness/pipeline/ledger/rules_changelog.md	규칙 승격 이력입니다. promote 가 쓰고 사람이 직접 적지 않습니다

명령어

python scripts/harness.py — 설정을 다룹니다

명령	하는 일
init --adapter <이름> --name <프로젝트>	harness/profiles/<이름>/config.json 을 복사해 harness/config.json 을 만듭니다. 이미 있으면 --force 없이는 덮어쓰지 않습니다
doctor	설정과 저장소가 어긋난 곳을 찾아 사람이 읽는 보고서로 냅니다
calibrate [--stage <이름>] [--replace]	스테이지를 한 번씩 돌려 소요 시간을 기록합니다. 하나라도 실패하면 파일을 쓰지 않습니다 — 코드가 깨진 상태의 실측값은 기준이 될 수 없습니다

python scripts/pipeline/cli.py — 파이프라인을 돌립니다

--help 가 없습니다. 도움말이 화면으로 나가면 "출력은 JSON 객체 하나" 라는 약속이 깨집니다.

명령	하는 일
doctor	설정 검사에 더해 파이프라인 쪽 7가지를 봅니다(런 폴더가 git 에서 제외됐는지, 에이전트 정의가 있는지, 페이즈 정의가 온전한지, 계약 틀이 파싱되는지, 리뷰어 설정이 맞는지, 원격과 기준 브랜치가 있는지, 외부 리뷰 봇 설정이 맞는지)
init --feature <이름> --request-file <경로>	런을 만들고, 요청 파일을 한 글자도 바꾸지 않은 채로 동결합니다
next [--run-id <아이디>]	진입 조건을 확인하고 다음 할 일을 알려 줍니다. 세션이 끊겼을 때 이어서 하는 방법도 이 명령입니다
record --phase <번호> [--file …] [--reviewer …] [--round n] [--failed]	산출물을 검사하고, 통과하면 다음 페이즈로 넘깁니다
gate [--phase 04] [--stage <이름>] [--replay <폴더>]	스테이지를 실행하고 결과를 읽어 실패를 귀속시킵니다
advance --phase <번호>	다음 페이즈로 명시적으로 넘깁니다. 게이트 뒤에 코드가 바뀌었으면 막습니다
retry --phase <번호> --counter <이름> --reason <사유>	실패한 페이즈를 다시 진행 상태로 되돌립니다. 재시도는 반드시 이 명령을 거칩니다
escalate [--reason <사유>]	진행을 멈추고 사람에게 넘깁니다. 선택지 세 개(그대로 진행 / 범위 축소 / 중단)를 함께 제시합니다
resume --ack	멈춰 둔 상태를 푸는 전용 명령입니다
status	지금 상태를 보여 줍니다. 언제나 exit 0 입니다
abandon --reason <사유>	런을 명시적으로 닫습니다. 사유가 없으면 기록에서 "중단" 과 "고장" 이 구분되지 않습니다
lint-phases [--dir <경로>]	페이즈 정의 파일의 정합을 봅니다. CI 없이도 돌아가는 유일한 검증 장치입니다
precheck [--scope pr] [--phase 05]	예산, 브랜치, 기준 브랜치와의 차이, 환경을 미리 봅니다
contract-trace [--contract <경로>]	계약에 적은 것이 코드에 실제로 있는지 대조합니다
approve --phase 06 [--auto] [--revoke]	승인을 기록으로 남깁니다. 그 시점의 작업 트리 해시와 등급을 함께 적습니다
mask --file <입력> --out <출력>	외부로 나갈 텍스트의 비밀값을 마스킹합니다
pr	06 의 여섯 과정을 싼 것부터 돌리고 처음 실패한 곳에서 멈춥니다
promote --scan / --stage / --apply / --flush	기록을 다시 세고, 후보를 담고, 실제로 규칙을 쓰고, 남은 것을 정리합니다
review07 [--external <경로>]	07 에서 리뷰의 호출 여부와 강도를 정합니다
report [--out <경로>]	08 보고서를 조립합니다

종료 코드

명령이 끝날 때 남기는 숫자입니다. /feature 는 이 숫자로 다음 행동을 정합니다.

코드	뜻	코드	뜻
0	성공	6	게이트 이후 코드가 바뀌어 넘길 수 없음
1	내부 오류	7	재시도했는데 진전이 없음
2	사용법이 틀렸거나 doctor 실패	8	제출한 산출물이 조건 위반
3	앞 페이즈 조건이 아직 안 갖춰짐	9	사람의 판단 대기
4	게이트 실패 (수리 기회 남음)	10	에스컬레이션 (상태를 잠급니다)
5	수리 기회 소진	11	런 완료

하네스 자신의 테스트 돌리기

python -m pytest scripts/

더 읽을 곳

• docs/harness/pipeline/team-spec.md — 8단계의 원본 명세. 페이즈별 상세, 종료 코드표, 실패 분류, 귀속 규칙, 승격 기준이 전부 여기 있습니다
• docs/harness/ROADMAP.md — 템플릿의 구성물(§1), 시작 순서(§4), 검증된 것과 아직인 것(§6)
• docs/harness/DECISIONS.md — 왜 그렇게 만들었는지 (ADR-H001~ADR-H040)
• CLAUDE.md — 작업 원칙과 프로젝트 규칙. 작업자가 직접 읽어야 지켜집니다