김경종
115 lines
5.5 KiB
Markdown
115 lines
5.5 KiB
Markdown
# 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에 필요한 문서와 파일만 지정합니다.
|