docs: align Harness step execution guidance
This commit is contained in:
KOKO\Mimi
@@ -18,6 +18,21 @@
|
||||
- 모든 기능은 tolerance 기준을 명시하고, 기준을 만족할 때만 배포 후보가 된다.
|
||||
- Harness 운영은 `docs/HARNESS_WORKFLOW.md`의 계획, 독립 Step 실행, PreToolUse/Stop 검증 계층을 따른다.
|
||||
|
||||
## Harness Step 실행 계약
|
||||
|
||||
계획과 구현 Agent는 작업 전 `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다.
|
||||
Implementation Planning Agent는 multi-Step 초안을 사용자에게 승인받은 뒤 planning files만
|
||||
materialize하며 Step을 선택하거나 실행하지 않는다. Executor는 별도의 명시적 사용자 요청으로
|
||||
`scripts/execute.py`를 실행할 때 branch, pending Step 선택, retry, timestamps, commits, Step
|
||||
advancement와 phase status를 소유한다.
|
||||
|
||||
Implementation Agent는 approved plan, materialized phase files, Executor-selected current
|
||||
`stepN.md`만 사용해 `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`를 완료하고
|
||||
다음 Step을 시작하지 않는다. Agent가 쓸 수 있는 Harness metadata는 current Step의 `status`와
|
||||
`summary`, `error_message`, `blocked_reason` payload뿐이다. `.codex/hooks.json`이 PreToolUse
|
||||
interception과 Stop whole-project validation을 자동 실행하므로 hook entry point를 수동 실행해
|
||||
대체하지 않는다. 세부 schema와 recovery 절차는 `docs/HARNESS_WORKFLOW.md`를 따른다.
|
||||
|
||||
## 전체 Agent 구성
|
||||
|
||||
### Coordinator Agent
|
||||
@@ -159,19 +174,28 @@ Directory와 filename은 제공된 값을 그대로 사용한다. Reference Mode
|
||||
|
||||
필수 절차:
|
||||
- 구현 계획 요청에서 project-local `$harness` skill을 사용한다.
|
||||
- `docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽고 multi-Step 초안만 사용자에게
|
||||
제시한다.
|
||||
- 한 Step은 하나의 layer/module만 다루고 각 Step에 prerequisite file, TDD
|
||||
RED/GREEN/VERIFY, 정확한 MSVC/CMake/CTest command와 금지사항을 포함한다.
|
||||
- Step 초안을 먼저 사용자에게 제시한다. 승인 전에는 `phases/` 파일을 생성하지 않는다.
|
||||
- Harness executor 실행은 별도 사용자 요청이 있을 때만 수행한다.
|
||||
- 승인 후에는 planning files만 materialize하고 Step 선택/실행은 하지 않는다. Harness executor
|
||||
실행은 별도 사용자 요청이 있을 때만 수행한다.
|
||||
|
||||
### Implementation Agent
|
||||
C++ 코드를 구현하는 Agent이다.
|
||||
|
||||
책임:
|
||||
- `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`, materialized phase files와
|
||||
Executor-selected current `stepN.md`를 읽고 현재 Step만 수행한다.
|
||||
- 테스트를 먼저 작성하고 실패를 확인한다.
|
||||
- 정식화와 I/O schema에 맞춰 최소 구현을 작성한다.
|
||||
- C++17 이상, MSVC, CMake, CTest 환경에서 동작하도록 구현한다.
|
||||
- 불필요한 일반화나 speculative abstraction을 피한다.
|
||||
- current Step의 `status`와 `summary`, `error_message`, `blocked_reason`만 기록한다.
|
||||
branch, retry, timestamp, commit, advancement는 Executor에 맡긴다.
|
||||
- `.codex/hooks.json`으로 자동 등록된 PreToolUse와 Stop을 사용하며 hook script를 수동
|
||||
검증 대체물로 실행하지 않는다.
|
||||
|
||||
주요 산출물:
|
||||
- C++ source/header 변경
|
||||
|
||||
@@ -5,7 +5,21 @@
|
||||
Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정식화, 수치 리뷰, I/O
|
||||
정의와 lightweight reference-case inventory를 C++/MSVC 구현 전 TDD 작업계획으로
|
||||
변환한다. Project-local `$harness`를 사용해 multi-Step 초안을 먼저 제시하고 사용자가
|
||||
승인한 뒤에만 `phases/` planning files를 생성한다.
|
||||
승인한 뒤에만 `phases/` planning files를 생성한다. 계획과 구현 전에
|
||||
`docs/HARNESS.md`와 `docs/HARNESS_WORKFLOW.md`를 읽는다.
|
||||
|
||||
## Harness 실행 handoff
|
||||
|
||||
Planning Agent는 draft -> explicit user approval -> planning files만 수행하며 Step을
|
||||
선택하거나 실행하지 않는다. 별도의 명시적 사용자 요청이 있어야 Executor
|
||||
(`scripts/execute.py`)가 branch, pending Step, retry, timestamps, commits, advancement와 phase
|
||||
status를 소유한다.
|
||||
|
||||
Implementation Agent는 approved plan, materialized phase indexes, Executor-selected current
|
||||
`stepN.md` 하나만 사용한다. current Step에서 `RED -> observed failure -> minimal GREEN ->
|
||||
focused/full VERIFY`를 완료하고 다음 Step을 시작하지 않는다. Agent는 current Step의 `status`
|
||||
및 `summary`, `error_message`, `blocked_reason` payload만 쓴다. `.codex/hooks.json`의
|
||||
PreToolUse와 Stop은 자동으로 실행되며 hook entry point를 수동 실행해 대체하지 않는다.
|
||||
|
||||
기본 파일명은 `docs/implementation-plans/<feature-id>-implementation-plan.md` 형식을 사용한다. 각 문서는 Implementation Agent가 먼저 작성해야 할 실패 테스트, 최소 구현 순서, CMake/CTest 등록 계획, acceptance traceability를 제공해야 한다.
|
||||
|
||||
@@ -21,7 +35,9 @@ Implementation Planning Agent는 승인된 요구조건, 연구 브리프, 정
|
||||
- `.harness/config.json` 또는 자동 감지 기본값에서 해석되는 MSVC build/test 명령과 feature-specific command를 명시한다.
|
||||
- 한 Step을 하나의 layer/module로 제한하고 prerequisite files, RED/GREEN/VERIFY, exact
|
||||
acceptance commands와 구체적 금지사항을 포함한다.
|
||||
- 사용자 승인 전에는 `phases/` 파일을 만들지 않고, 별도 요청 없이는 `scripts/execute.py`를 실행하지 않는다.
|
||||
- 사용자 승인 전에는 `phases/` 파일을 만들지 않고, 승인 뒤에도 planning files만
|
||||
materialize한다. 별도 요청 없이는 `scripts/execute.py`를 실행하지 않으며 Step을
|
||||
선택하거나 실행하지 않는다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
@@ -146,6 +162,18 @@ MSVC build/test를 다시 확인하며, 구현 보고서의 RED 실패 증거를
|
||||
|
||||
User approval is required before materializing this draft under `phases/`.
|
||||
|
||||
## Executor Handoff
|
||||
|
||||
- Executor authorization: separate explicit user request for `scripts/execute.py`.
|
||||
- implementation input: approved plan, materialized phase indexes, and Executor-selected current
|
||||
`stepN.md`.
|
||||
- implementation recipe: `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`.
|
||||
- metadata ownership: Implementation Agent records only the current Step `status` plus `summary`,
|
||||
`error_message`, or `blocked_reason`; Executor records branch, pending-Step selection, retry,
|
||||
timestamps, commits, advancement, and phase status.
|
||||
- hooks: `.codex/hooks.json` automatically invokes PreToolUse and Stop; never manually run hook
|
||||
entry points as substitutes.
|
||||
|
||||
## Open Issues
|
||||
- <requirement, formulation, I/O, required comparison file/mapping, tolerance, or architecture issue>
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user