modify harness framework

2026-09-08 10:30:07 +09:00
parent 1239d5b9f6
commit 1a0f3c9aaf
68 changed files with 6729 additions and 957 deletions
@@ -0,0 +1,145 @@
+---
+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는 Windows에서 C#·.NET 8 제품 개발을 지원하는 Python 계획·실행 도구다.
+제품 요구사항과 기술 결정을 Harness 자체 요구사항과 섞지 않는다. 제품 유형과 계층을
+가정하지 않으며 신규 테스트 기본값은 xUnit v2 + VSTest다.
+
+## 탐색과 논의
+
+1. `AGENTS.md`를 읽는다.
+2. 변경 범위와 직접 관련된 제품 문서, 코드, 테스트와 `.harness/config.json`만 읽는다.
+3. 미정인 제품 요구사항이나 공개 계약이 구현 결과를 바꾸면 사용자와 논의한다.
+
+전체 `docs/`를 일괄 읽거나 그 본문을 step에 복사하지 않는다. 이전 대화 없이도 실행할
+수 있도록 필요한 기존 파일을 명시적으로 참조한다.
+
+## Step 설계
+
+하나의 step에는 다음 요소만 필수로 둔다.
+
+- 목표와 범위
+- 관련 파일과 `context_files`
+- 핵심 제약
+- 실행 가능한 Acceptance Criteria
+
+공개 API 계약이 중요한 경우에만 시그니처와 nullability를 적는다. 새 기능과 버그 수정은 한
+step 안에서 실패 테스트 확인, 최소 구현, 성공 확인까지 끝낸다. 실제 설정과 기존
+테스트 명령을 우선하며 확인되지 않은 예시 명령을 AC로 쓰지 않는다.
+
+제품 검증은 저장소 루트에서 `global.json`에 따른 SDK 선택을 확인한다. version 2
+설정의 target에 포함된 각 프로젝트와 모든 `testProjects`에서 SDK로 평가한 참조를
+끝까지 따라가 실제 TFM이 .NET 8이고 프로젝트가 저장소 내부인지 확인한다.
+이후 target과 모든 `testProjects`를 restore/build한 뒤 각 테스트를
+실행한다. 경고는 오류로 처리하고 현재 TRX의 누락·실행 0건·skip-only를 성공으로
+기록하지 않는다. 제품에서 테스트 프로젝트로 향하는 참조를 만들지 않는다.
+세부 명령은 [환경 구축 가이드](../../../docs/ENVIRONMENT_SETUP.md)를 따른다.
+
+`Foo.cs`에는 기본적으로 `FooTests.cs` 또는 `FooTest.cs`가 필요하다. 파일 존재 검사는
+실제 실패 테스트와 성공 실행을 증명하지 않으므로 명령·결과를 step 기록에 남긴다.
+`Program.cs`도 자동 면제가 아니다. 필요한 면제는 정확한 `tdd.exclude` 경로와 이유를
+기록하며 제품 검증 대상에서 파일을 숨기는 용도로 사용하지 않는다.
+
+## 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이고 executor의 독립 제품 검증까지
+통과해야 성공이다. Stop이 실패 응답으로 턴을 멈춰도 CLI는 exit 0일 수 있으므로
+모델이 쓴 상태만 신뢰하지 않는다. 독립 검증 실패도 같은 3회 호출 예산에서 재시도한다.
+`docs-only`는 이 검사에서도 실제 문서 변경을 확인하며 `blocked`는 즉시 멈춘다.
+`error`나 `blocked`를 재개하려면 원인을 해결하고 status를 `pending`으로 바꾼 뒤 해당
+오류 필드와 timestamp를 제거한다.
@@ -0,0 +1,38 @@
+---
+name: review
+description: Use when reviewing repository changes against AGENTS.md, architecture decisions, tests, and build requirements.
+---
+
+# Repository Review
+
+`AGENTS.md`를 먼저 읽고 변경 범위와 직접 관련된 제품 문서, 코드와 테스트만 추가로
+읽는다. `context_files`가 있으면 해당 목록을 우선한다. 전체 `docs/`를 일괄 읽도록
+요구하지 않는다.
+
+사용자가 범위를 지정하지 않으면 현재 작업 트리의 변경을 리뷰한다. 실제 결함을
+심각도순으로 제시하고 각 finding에 파일과 줄 번호, 영향, 근거와 수정 방안을 적는다.
+
+다음을 해당 변경에 적용할 수 있는 범위에서 확인한다.
+
+- 공개 C# API의 접근성·호환성·nullability 계약, 프로젝트 참조 방향과 관련 ADR
+- 제품 프로젝트가 테스트 프로젝트를 참조하지 않는지 확인
+- 새 C# 동작을 먼저 재현한 실패 테스트의 명령·결과와 구현 후 회귀 검증
+- 실제 `global.json`, `.sln` / SDK 스타일 `.csproj`, version 2 `.harness/config.json`에
+  따른 .NET 8 SDK 선택, 각 제품·테스트 프로젝트의 실제 TFM 평가와 restore/build/test 결과;
+  상속된 props와 속성 참조를 포함한 `TargetFramework`/`TargetFrameworks`도 확인
+- `testProjects`가 전체 제품 테스트를 포함하고 각 프로젝트의 현재 TRX에 실행된
+  테스트가 있는지 확인; 테스트 0건·skip-only·누락·과거 결과는 성공 근거가 아니다
+- nullable 진단, 경고의 오류 처리와 범위 밖 변경
+- async 코드 변경 시 취소·예외 전파, `IDisposable` / `IAsyncDisposable` 사용 변경 시
+  자원 해제 확인; 모든 제품에 async나 DI를 요구하지 않는다
+- C# 대응 테스트 파일 존재를 red-green 증거로 혼동하지 않는지, `Program.cs` 등의
+  면제가 정확한 경로와 이유로 한정되고 제품 검증을 우회하지 않는지 확인
+- Harness 변경이면 관련 Python 테스트와 운영 문서의 필드·동작 일치
+
+명시적으로 `validation: docs-only`인 문서 step은 실제 변경이 허용된 문서 경로에만
+있을 때 제품 build를 생략할 수 있다. 그 외에는 기존 전체 검증을 사용한다. 실행하지
+못한 검사는 성공으로 추정하지 않고 `미검증`과 이유를 기록한다.
+
+finding 뒤에는 아키텍처, 기술 스택, 테스트, 필수 규칙, build 가능 여부를 각각
+`통과`, `실패`, `미검증`으로 요약한다. finding이 없으면 발견된 문제가 없다고 쓰고
+남은 검증 공백을 밝힌다.