modify harness framework
This commit is contained in:
김경종
@@ -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를 제거한다.
|
||||
Reference in New Issue
Block a user