Files

T

김경종 1a0f3c9aaf modify harness framework

2026-09-08 10:30:07 +09:00

6.0 KiB

Raw Blame History

name, description

name	description
harness	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다.

탐색과 논의

AGENTS.md를 읽는다.
변경 범위와 직접 관련된 제품 문서, 코드, 테스트와 .harness/config.json만 읽는다.
미정인 제품 요구사항이나 공개 계약이 구현 결과를 바꾸면 사용자와 논의한다.

전체 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를 성공으로 기록하지 않는다. 제품에서 테스트 프로젝트로 향하는 참조를 만들지 않는다. 세부 명령은 환경 구축 가이드를 따른다.

Foo.cs에는 기본적으로 FooTests.cs 또는 FooTest.cs가 필요하다. 파일 존재 검사는 실제 실패 테스트와 성공 실행을 증명하지 않으므로 명령·결과를 step 기록에 남긴다. Program.cs도 자동 면제가 아니다. 필요한 면제는 정확한 tdd.exclude 경로와 이유를 기록하며 제품 검증 대상에서 파일을 숨기는 용도로 사용하지 않는다.

Index 형식

phases/index.json:

{
  "phases": [{"dir": "add-parser", "status": "pending"}]
}

phases/{phase}/index.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 파일

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

실행

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를 제거한다.

6.0 KiB Raw Blame History