docs: align Harness step execution guidance

This commit is contained in:
KOKO\Mimi
2026-08-12 15:27:32 +09:00
parent 65d5e0748a
commit 18296a1944
4 changed files with 107 additions and 17 deletions
+30 -2
View File
@@ -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>
```