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는 다음 정보를 포함해야 합니다.

# 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에 필요한 문서와 파일만 지정합니다.

5.5 KiB Raw Blame History