# Harness 운영 가이드

Harness는 MSVC C++ 제품 개발의 step 실행, 정책 검사와 build/test를 지원한다. 제품의
목표와 기능은 `docs/PRD.md`에 별도로 둔다. 상세 실행 흐름은
[HARNESS_WORKFLOW.md](HARNESS_WORKFLOW.md)를 참고한다.

## 요구 환경과 설정

처음 사용하는 환경의 도구 설치, PATH·인증·훅 점검과 빌드 방식별 설정은
[환경 구축 가이드](ENVIRONMENT_SETUP.md)를 따른다.

- Windows, Python 3.10 이상, Codex CLI
- Visual Studio Desktop development with C++ workload와 MSBuild
- CMake 프로젝트이면 CMake와 CTest

```powershell
Copy-Item .harness/config.example.json .harness/config.json
```

실제 preset, solution, configuration, platform과 test command를
`.harness/config.json`에 기록한다. 제품의 MSVC toolset, C++ 표준과 테스트 프레임워크는
현재 미정이며 예시값으로 확정하지 않는다.

## Phase 실행

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

먼저 `--dry-run`으로 첫 pending step이 읽을 파일과 프롬프트 문자 수를 확인한다. 이
모드는 Codex 호출, branch 전환, timestamp, 파일 쓰기, commit과 push를 하지 않는다.
`--push`와 함께 사용할 수 없다.

## 선택 문맥과 호환성

step index의 `context_files`에 필요한 기존 문서를 저장소 상대 경로로 적는다.

```json
{
  "step": 1,
  "name": "implement-parser",
  "status": "pending",
  "context_files": ["docs/ARCHITECTURE.md", "docs/parser-format.md"]
}
```

필드를 생략하거나 빈 배열로 두면 `AGENTS.md`, 자동 인계와 step 이외의 문서는
추가되지 않는다. 이전 Harness가 모든 `docs/*.md`를 넣던 동작에 의존하는 기존 phase는
필요한 문서를 `context_files`에 명시해야 한다. glob, URL, 절대 경로와 저장소 밖 경로는
지원하지 않는다.

현재 phase의 `docs/phase/{phase}/handoff.md`가 있으면 매 호출 다시 읽는다. 없을 때만
현재 step보다 앞선 완료 step 중 가장 최근 하나의 summary를 최대 1,000자로 전달한다.
상세 기록 형식은 [phase README](phase/README.md)를 따른다.

## 검증 모드

```json
{"step": 2, "name": "update-docs", "status": "pending", "validation": "docs-only"}
```

`validation` 생략 또는 `full`은 기존 전체 제품 검증을 수행한다. `docs-only`도 실제 Git
변경이 루트 `AGENTS.md`, `docs/**/*.md`, 현재 phase의 `index.json`과
`stepN-output.json`에만 있고 실제 문서 변경이 있을 때만 제품 검증을 생략한다. Git
조회 실패, 빈 변경, bookkeeping만 있는 변경, 다른 코드·설정·빌드 파일이 섞인 변경은
보수적으로 전체 검증으로 돌아간다. symlink나 junction으로 해석되는 변경 경로도
문서 전용으로 인정하지 않는다. 제품 build가 Markdown을 입력으로 사용하면 `full`을
선택한다.

## MSVC 검증

자동 감지는 명시 `projectType`, CMake metadata, 단일 `.sln`, 단일 `.vcxproj` 순서다.
C++ 파일은 있지만 build metadata가 없으면 오류다. 여러 solution/project가 있으면
설정으로 하나를 지정한다.

CMake preset을 쓸 때는 source, binary, configure/build/test preset을 함께 지정한다.
일반 CMake 검증의 형태는 다음과 같다.

```powershell
cmake -S . -B .harness/build -A x64
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --show-only=json-v1
ctest --test-dir .harness/build -C Debug --output-on-failure
```

Harness는 compiler metadata가 MSVC인지와 CTest가 한 개 이상의 테스트를 찾는지도
확인한다. 직접 MSBuild는 solution, configuration, platform과 `msbuild.testCommand`가
필요하다.

```powershell
MSBuild.exe <solution.sln> /m /nologo /p:Configuration=Debug /p:Platform=x64
<configured-test-command>
```

## TDD와 복구

C/C++ 제품 파일을 편집하려면 설정된 test root나 인접 `tests/`, `test/`에 대응 테스트
파일이 먼저 존재해야 한다. 테스트 자체, `main.cpp`, build·외부 의존성·generated
경로와 `tdd.exclude`는 기존 정책대로 처리한다. 이 검사는 테스트의 존재를 확인하며
테스트 품질이나 실제 red-green 실행을 대신하지 않는다.

Executor는 Codex를 최초 호출 포함 최대 3회 호출한다. 재시도 입력은 marker를 포함해
4,000자로 제한하며 앞 1,500자와 끝부분 최대 2,500자를 보존한다. 원본
`stepN-output.json`은 온전히
저장되지만 다음 시도에서 덮어쓴다. exit code 0과 `completed` 상태가 모두 있어야
성공한다.

`error` 또는 `blocked`를 재개할 때는 원인을 해결하고 step을 `pending`으로 바꾼 뒤
오류 이유와 해당 timestamp를 제거한다. 인증이나 CLI 환경 오류는 즉시 중단한다.

Harness 자체 Python 검증:

```powershell
uv run --with pytest python -m pytest -v -rs
uv run --with pytest python -m compileall -q scripts tests
```