modify harness framework
This commit is contained in:
김경종
@@ -1,120 +1,118 @@
|
||||
# Harness 운영 가이드
|
||||
|
||||
요구사항 접수부터 Step 실행, TDD 정책, MSVC 빌드·테스트, 재시도와 커밋까지의
|
||||
전체 흐름은 [Harness Framework 동작 과정](HARNESS_WORKFLOW.md)을 참고한다.
|
||||
Harness는 MSVC C++ 제품 개발의 step 실행, 정책 검사와 build/test를 지원한다. 제품의
|
||||
목표와 기능은 `docs/PRD.md`에 별도로 둔다. 상세 실행 흐름은
|
||||
[HARNESS_WORKFLOW.md](HARNESS_WORKFLOW.md)를 참고한다.
|
||||
|
||||
## Requirements
|
||||
## 요구 환경과 설정
|
||||
|
||||
Windows, Python 3.10 이상, Codex CLI가 필요하다. CMake 프로젝트에는 Visual Studio의
|
||||
Desktop development with C++ 워크로드와 MSBuild, CMake/CTest를 설치한다.
|
||||
처음 사용하는 환경의 도구 설치, PATH·인증·훅 점검과 빌드 방식별 설정은
|
||||
[환경 구축 가이드](ENVIRONMENT_SETUP.md)를 따른다.
|
||||
|
||||
## 프로젝트 자동 감지
|
||||
|
||||
프로젝트 형식은 다음 순서로 결정한다: `.harness/config.json`의 명시적 type, 루트의
|
||||
CMake metadata, 하나의 `.sln`, 하나의 `.vcxproj` 순서다. C/C++가 아닌 저장소는
|
||||
건너뛰며, C/C++ 파일은 있지만 CMake/solution metadata가 없는 orphan-C++ 저장소는
|
||||
오류로 처리한다.
|
||||
|
||||
설정을 시작하려면 다음을 실행한다.
|
||||
- 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
|
||||
```
|
||||
|
||||
## Harness Python 검증
|
||||
먼저 `--dry-run`으로 첫 pending step이 읽을 파일과 프롬프트 문자 수를 확인한다. 이
|
||||
모드는 Codex 호출, branch 전환, timestamp, 파일 쓰기, commit과 push를 하지 않는다.
|
||||
`--push`와 함께 사용할 수 없다.
|
||||
|
||||
이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고
|
||||
다음 명령으로 실행한다.
|
||||
## 선택 문맥과 호환성
|
||||
|
||||
```powershell
|
||||
uv run --with pytest python -m pytest -v -rs
|
||||
```
|
||||
|
||||
## CMake preset 설정
|
||||
|
||||
`projectType`을 `cmake`로 지정하거나 자동 감지를 사용한다. `cmake.sourceDir`,
|
||||
`binaryDir`, `configurePreset`, `buildPreset`, `testPreset`은 preset을 사용할 때 함께
|
||||
지정해야 한다. 빌드 산출물은 저장소의 `.harness/build/`처럼 격리된 경로에 둔다.
|
||||
step index의 `context_files`에 필요한 기존 문서를 저장소 상대 경로로 적는다.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"projectType": "cmake",
|
||||
"cmake": {
|
||||
"sourceDir": ".",
|
||||
"binaryDir": "out/build/windows-debug",
|
||||
"configurePreset": "windows-debug",
|
||||
"buildPreset": "windows-debug",
|
||||
"testPreset": "windows-debug"
|
||||
}
|
||||
"step": 1,
|
||||
"name": "implement-parser",
|
||||
"status": "pending",
|
||||
"context_files": ["docs/ARCHITECTURE.md", "docs/parser-format.md"]
|
||||
}
|
||||
```
|
||||
|
||||
```powershell
|
||||
cmake --preset windows-debug
|
||||
cmake --build --preset windows-debug
|
||||
ctest --preset windows-debug --output-on-failure
|
||||
필드를 생략하거나 빈 배열로 두면 `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"}
|
||||
```
|
||||
|
||||
Preset을 쓰지 않는 경우에는 같은 격리된 build directory를 명시한다.
|
||||
`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
|
||||
```
|
||||
|
||||
## 직접 MSBuild 설정
|
||||
|
||||
`projectType`을 `msbuild`로 설정하면 `msbuild.solution`, `configuration`, `platform`을
|
||||
지정한다. 직접 MSBuild 프로젝트에서는 `msbuild.testCommand`가 필수이며, 테스트 실행
|
||||
파일과 인수를 JSON 배열로 적는다.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"projectType": "msbuild",
|
||||
"msbuild": {
|
||||
"solution": "MyProject.sln",
|
||||
"configuration": "Debug",
|
||||
"platform": "x64",
|
||||
"testCommand": ["build/tests/Debug/MyProjectTests.exe"]
|
||||
}
|
||||
}
|
||||
```
|
||||
Harness는 compiler metadata가 MSVC인지와 CTest가 한 개 이상의 테스트를 찾는지도
|
||||
확인한다. 직접 MSBuild는 solution, configuration, platform과 `msbuild.testCommand`가
|
||||
필요하다.
|
||||
|
||||
```powershell
|
||||
MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
|
||||
.\build\tests\Debug\MyProjectTests.exe
|
||||
MSBuild.exe <solution.sln> /m /nologo /p:Configuration=Debug /p:Platform=x64
|
||||
<configured-test-command>
|
||||
```
|
||||
|
||||
## TDD 확장
|
||||
## TDD와 복구
|
||||
|
||||
`tdd.testRoots`와 `tdd.testPatterns`로 테스트 위치와 이름을 확장한다. 패턴마다
|
||||
`{stem}`이 필요하다. `main`, 테스트, 외부 의존성, 생성 파일, build directory 같은
|
||||
기본 제외 항목은 Harness가 관리하며, `tdd.exclude`의 사용자 제외 항목은 이를
|
||||
대체하지 않고 추가한다.
|
||||
C/C++ 제품 파일을 편집하려면 설정된 test root나 인접 `tests/`, `test/`에 대응 테스트
|
||||
파일이 먼저 존재해야 한다. 테스트 자체, `main.cpp`, build·외부 의존성·generated
|
||||
경로와 `tdd.exclude`는 기존 정책대로 처리한다. 이 검사는 테스트의 존재를 확인하며
|
||||
테스트 품질이나 실제 red-green 실행을 대신하지 않는다.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"tdd": {
|
||||
"testRoots": ["tests", "integration-tests"],
|
||||
"testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"],
|
||||
"exclude": ["legacy/generated/**"]
|
||||
}
|
||||
}
|
||||
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
|
||||
```
|
||||
|
||||
## 실패 복구
|
||||
|
||||
- Visual Studio C++ workload가 없으면 Installer에서 Desktop development with C++를 설치한 뒤 다시 실행한다.
|
||||
- solution 또는 project가 여러 개라서 모호하면 `projectType`과 `msbuild.solution`을 명시한다.
|
||||
- MSVC가 아닌 컴파일러가 감지되면 MSVC Developer Command Prompt에서 실행하거나 toolchain을 MSVC로 전환한다.
|
||||
- CTest가 0개 테스트를 보고하면 `enable_testing()`과 테스트 등록을 확인한다.
|
||||
- 직접 MSBuild 구성에 test command가 없으면 `msbuild.testCommand` 배열을 추가한다.
|
||||
- timeout 또는 명령 실패 시 Stop 응답의 stage, 안전한 argv 배열, 작업 디렉터리,
|
||||
종료 코드와 출력 tail을 확인하고 해당 명령을 단독으로 다시 실행한다. Harness는
|
||||
별도의 로그 파일을 만들지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user