김경종
119 lines
5.0 KiB
Markdown
119 lines
5.0 KiB
Markdown
# 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
|
|
```
|