---
name: harness
description: Use when planning agentic implementation phases, creating phases/index.json and self-contained step files, or running the Harness step executor.
---

# Harness Workflow

Harness는 MSVC C++ 제품 개발을 위한 계획·실행 도구다. 제품 요구사항과 기술 결정을
Harness 자체 요구사항과 섞지 않는다.

## 탐색과 논의

1. `AGENTS.md`를 읽는다.
2. 변경 범위와 직접 관련된 제품 문서, 코드, 테스트와 `.harness/config.json`만 읽는다.
3. 미정인 제품 요구사항이나 공개 계약이 구현 결과를 바꾸면 사용자와 논의한다.

전체 `docs/`를 일괄 읽거나 그 본문을 step에 복사하지 않는다. 이전 대화 없이도 실행할
수 있도록 필요한 기존 파일을 명시적으로 참조한다.

## Step 설계

하나의 step에는 다음 요소만 필수로 둔다.

- 목표와 범위
- 관련 파일과 `context_files`
- 핵심 제약
- 실행 가능한 Acceptance Criteria

공개 API나 ABI 계약이 중요한 경우에만 시그니처를 적는다. 새 기능과 버그 수정은 한
step 안에서 실패 테스트 확인, 최소 구현, 성공 확인까지 끝낸다. 실제 설정과 기존
테스트 명령을 우선하며 확인되지 않은 예시 명령을 AC로 쓰지 않는다.

## Index 형식

`phases/index.json`:

```json
{
  "phases": [{"dir": "add-parser", "status": "pending"}]
}
```

`phases/{phase}/index.json`:

```json
{
  "project": "<제품명 또는 미정>",
  "phase": "add-parser",
  "steps": [
    {
      "step": 0,
      "name": "implement-parser",
      "status": "pending",
      "context_files": ["docs/ARCHITECTURE.md"],
      "validation": "full"
    }
  ]
}
```

- `name`은 kebab-case slug다.
- `context_files`는 선택 사항인 저장소 상대 파일 경로 배열이다. glob과 URL은 쓰지
  않는다. 생략하거나 빈 배열이면 추가 문서를 주입하지 않는다.
- `validation`은 `full` 또는 `docs-only`이며 생략 시 `full`이다. `docs-only`는 실제
  변경이 허용된 문서 경로에만 있을 때만 제품 검증 생략을 요청한다.
- 생성 시 status는 `pending`이다. timestamp는 executor가 기록한다.

상태 기록:

| 상태 | Codex 기록 | Executor 기록 |
|---|---|---|
| `completed` | 한 줄 `summary` | `completed_at` |
| `error` | `error_message` | `failed_at` |
| `blocked` | `blocked_reason` | `blocked_at` |

## Step 파일

````markdown
# Step N: <name>

## 목표와 범위
<한 가지 책임과 범위 밖 항목>

## 관련 파일
- `<path>`

## 핵심 제약
- <유지할 계약과 이유>

## Acceptance Criteria
```powershell
<실제 build/test 명령>
```
````

현재 step보다 앞선 작업이 만든 파일은 관련 파일에 적고 실행 중 직접 읽는다. 이미
존재하는 제품 문서만 `context_files`에 넣는다.

## Phase 기록

`docs/phase/{phase}/handoff.md`는 최신 상태, 결정, 미해결 문제, 마지막 검증과 다음
시작점을 약 60줄 이내로 유지한다. `stepN.md`에는 변경 파일, 결정, 검증 결과와 유효한
시행착오를 기록한다. 성공·실패·차단을 보고하기 전에 둘을 갱신한다. 형식은
`docs/phase/README.md`를 따른다.

## 실행

```powershell
python scripts/execute.py <phase>
python scripts/execute.py <phase> --dry-run
python scripts/execute.py <phase> --push
```

`--dry-run`은 첫 pending step의 주입 경로와 문자 수, 전체 프롬프트 문자 수만
출력하며 파일, Git, 상태와 Codex를 변경하지 않는다. `--push`와 함께 쓸 수 없다.

프롬프트는 `AGENTS → 공통 규칙 → context_files → 최신 handoff 또는 호환 summary →
직전 실패 → 현재 step` 순서다. handoff가 없을 때만 현재 step보다 앞선 완료 step 중
가장 최근 하나의 summary를 최대 1,000자로 전달한다.

Executor는 최초 호출을 포함해 Codex를 최대 3회 호출한다. 재시도 오류 본문은 총
4,000자 안에서 앞 1,500자, 중간 생략 marker와 끝부분 최대 2,500자를 보존한다. 원본 출력은
`phases/{phase}/stepN-output.json`에 온전히 쓰지만 다음 호출에서 덮어쓴다. 지속할
시행착오는 `docs/phase/{phase}/stepN.md`에 남긴다.

`completed`는 Codex 프로세스 exit code가 0일 때만 성공이다. `blocked`는 즉시 멈춘다.
`error`나 `blocked`를 재개하려면 원인을 해결하고 status를 `pending`으로 바꾼 뒤 해당
오류 필드와 timestamp를 제거한다.