# Harness Engineering Guide

이 문서는 PDFtoMD 프로젝트에서 장기 agent 작업을 관리하는 Harness 운영 규칙입니다. 기준은 Anthropic의 "Harness design for long-running application development" 글에서 강조한 planner, generator, evaluator 분리, 파일 기반 handoff, sprint contract, 독립 평가 루프입니다.

## Purpose
- 긴 변환 엔진 개발을 작은 self-contained step으로 나눕니다.
- 새 agent가 이전 대화 맥락 없이도 `AGENTS.md`, `PLAN.md`, `PROGRESS.md`, `phases/` 파일만 읽고 일을 이어받게 합니다.
- 구현 agent와 평가 agent를 분리해 자기 평가 편향을 줄입니다.
- 각 step의 성공 조건을 코드 작성 전에 파일로 고정합니다.
- Harness 자체는 단순하게 유지하고, 복잡성은 필요한 검증 기준과 step 경계에만 둡니다.

## Roles

### Planner
- 제품 목표와 아키텍처 문서를 읽고 phase와 step을 작성합니다.
- 구현 세부를 과도하게 지정하지 않고 산출물, 책임 범위, 수락 기준, 금지 범위를 명확히 합니다.
- 산출물:
  - `PLAN.md` 업데이트
  - `phases/index.json`
  - `phases/{phase}/index.json`
  - `phases/{phase}/stepN.md`

### Generator
- 한 번에 하나의 `stepN.md`만 수행합니다.
- 작업 전 step의 "Sprint Contract"를 읽고, 애매하면 구현 전에 `PROGRESS.md`에 blocker로 남깁니다.
- TDD가 필요한 구현 step에서는 테스트를 먼저 작성합니다.
- 산출물:
  - step 범위 내 코드, 테스트, 문서 변경
  - `phases/{phase}/index.json` step status 업데이트
  - `PROGRESS.md` handoff 업데이트

### Evaluator
- generator가 만든 결과를 독립적으로 검토합니다.
- 합의된 기준 중 하나라도 hard threshold를 넘지 못하면 step을 통과시키지 않습니다.
- 통과 여부만 보지 않고, 재작업 가능한 구체적 실패 원인을 남깁니다.
- 산출물:
  - review finding 또는 pass 기록
  - 필요한 경우 `phases/{phase}/index.json`의 `error_message` 또는 `blocked_reason`
  - `PROGRESS.md` 검증 결과

## File Protocol
- `AGENTS.md`: 변하지 않는 저장소 규칙.
- `PLAN.md`: 전체 작업 계획의 단일 출처.
- `PROGRESS.md`: 현재 진행 상태와 handoff의 단일 출처.
- `docs/*.md`: 제품, 아키텍처, 결정, 도구 체인, Harness 운영 지식.
- `phases/index.json`: 실행 가능한 phase registry.
- `phases/{phase}/index.json`: 해당 phase step 상태의 단일 출처.
- `phases/{phase}/stepN.md`: 새 agent가 독립 실행할 수 있는 ticket.

## Step Contract Template
각 `stepN.md`는 다음 정보를 포함해야 합니다.

````markdown
# Step N: step-name

## Read First
- /AGENTS.md
- /PLAN.md
- /PROGRESS.md
- /docs/HARNESS.md
- /docs/ARCHITECTURE.md
- /docs/ADR.md
- /docs/CONVERSION_POLICY.md

## Task
이 step에서 만들어야 하는 산출물과 수정 가능한 파일을 구체적으로 적습니다.

## Sprint Contract
- Done means: 사용자가 관찰할 수 있거나 테스트로 확인 가능한 완료 조건.
- Hard thresholds: 하나라도 실패하면 step 실패로 보는 기준.
- Files owned: 이 step에서 수정할 수 있는 파일 또는 디렉터리.
- Dependencies: 이전 step 산출물 또는 필요한 문서.

## Acceptance Criteria
```powershell
python scripts\validate_workspace.py
```

## Verification
1. 테스트와 검증 명령을 실행합니다.
2. `PROGRESS.md`에 결과와 다음 handoff를 기록합니다.
3. `phases/{phase}/index.json`의 해당 step을 `completed`, `blocked`, `error` 중 하나로 갱신합니다.

## Do Not
- step 범위 밖 기능을 구현하지 않습니다.
- 새 parser나 외부 API를 도입하지 않습니다.
- 생성 Markdown 출력 contract를 임의로 넓히지 않습니다.
````

## Evaluation Criteria
PDFtoMD의 evaluator는 다음 hard threshold를 우선 적용합니다.

| Area | Hard Threshold |
| --- | --- |
| Architecture | Marker, Nougat, PyMuPDF 책임 경계를 깨지 않는다. |
| TDD | 구현 step은 실패하는 테스트가 먼저 추가되거나, 테스트가 필요 없는 이유가 step에 명시된다. |
| Determinism | 같은 입력과 옵션은 같은 slug, asset path, anchor, Markdown 구조를 만든다. |
| Markdown quality | heading, math delimiter, table, image link, caption, chunk frontmatter 검증이 가능하다. |
| Runtime | Windows path, Korean filename, CUDA/CPU runtime 정책을 훼손하지 않는다. |
| Scope | PyQt UI, hosted API, LLM correction, sidecar output을 1차 구현에 끌어오지 않는다. |
| Handoff | `PROGRESS.md`와 phase index가 다음 agent에게 충분한 상태를 제공한다. |

## When To Use The Full Loop
- Full planner/generator/evaluator loop를 사용합니다:
  - 새 phase를 시작할 때
  - parser adapter, chunk planner, renderer, quality validator처럼 실패 비용이 큰 작업
  - sample corpus나 runtime 정책처럼 여러 파일과 문서가 동시에 바뀌는 작업
- 단순한 문서 오타, 작은 command 설명, 명확한 단일 테스트 수정은 일반 Codex 작업으로 처리해도 됩니다. 그래도 `PROGRESS.md`는 갱신합니다.

## Simplification Rule
Harness 구성 요소는 실제로 품질을 높일 때만 유지합니다.
- 같은 검증을 두 곳에서 반복하면 하나로 줄입니다.
- hook은 보조 장치로 취급하고, step의 acceptance criteria와 evaluator 판단을 대체하지 않습니다.
- agent에게 너무 많은 컨텍스트를 주지 말고, step에 필요한 문서와 파일만 지정합니다.