Harness 운영 가이드

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

요구 환경과 설정

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

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

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

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

Phase 실행

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에 필요한 기존 문서를 저장소 상대 경로로 적는다.

{
  "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를 따른다.

검증 모드

{"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 검증의 형태는 다음과 같다.

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가 필요하다.

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 검증:

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

5.0 KiB Raw Blame History