baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align Harness step execution guidance

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/harness/SKILL.md
+28 -2
View File
@@ -7,6 +7,23 @@ description: Use when planning agentic implementation phases, creating phases/in
이 프로젝트는 Harness 프레임워크를 사용한다. 아래 워크플로에 따라 작업한다.
## 필수 읽기와 실행 소유권
계획, phase 파일 생성, 또는 Executor 실행 전 `AGENTS.md`,
`docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`를 읽는다. Step을 구현할 때는
`.codex/hooks.json`, phase index, Executor가 선택한 현재 `stepN.md`도 읽는다.
| 책임 | 소유자 |
|---|---|
| branch, pending Step 선택, retry, timestamps, commits, advancement | Executor (`scripts/execute.py`) |
| Executor-selected current Step의 작업과 해당 Step의 `status` 및 `summary` / `error_message` / `blocked_reason` payload | Implementation Agent |
| PreToolUse interception과 Stop whole-project validation | `.codex/hooks.json`으로 등록된 hooks |
Hook은 자동으로 작동한다. `scripts/hooks/pre_tool_use.py` 또는
`scripts/hooks/stop_validation.py`를 수동 실행해 등록된 hook의 대체물로 사용하지 않는다.
계획 승인은 Executor 실행 권한이 아니다. `scripts/execute.py`는 별도의 명시적 사용자
요청에서만 실행한다.
## A. 탐색
`AGENTS.md`와 `docs/` 하위 문서(PRD, ARCHITECTURE, ADR 등)를 읽고 프로젝트의 기획,
@@ -42,6 +59,9 @@ description: Use when planning agentic implementation phases, creating phases/in
사용자가 초안을 승인한 후에만 다음 파일을 생성한다.
Planning Agent는 초안을 만들고 승인받아 planning files만 materialize한다. planning
Agent는 Step을 선택하거나 실행하지 않는다.
### D-1. `phases/index.json`
여러 task를 관리하는 top-level 인덱스다. 이미 존재하면 `phases` 배열에 새 항목을
@@ -136,10 +156,11 @@ MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
1. Acceptance Criteria command를 실행한다.
2. ARCHITECTURE 디렉터리 구조를 따르는지 확인한다.
3. ADR 기술 스택과 `AGENTS.md` CRITICAL 규칙을 확인한다.
4. 결과에 따라 task index의 해당 step을 갱신한다.
4. 결과에 따라 task index의 Executor-selected current Step만 갱신한다.
- 성공: `status`를 `completed`로 바꾸고 한 줄 `summary` 기록
- 수정 3회 후 실패: `status`를 `error`로 바꾸고 `error_message` 기록
- 실행을 계속할 수 없는 오류: `status`를 `error`로 바꾸고 `error_message` 기록
- 사용자 개입 필요: `status`를 `blocked`로 바꾸고 `blocked_reason` 기록 후 중단
- retry, timestamp, commit, 다음 Step 선택과 advancement는 Executor가 기록한다.
## 금지사항
@@ -149,6 +170,11 @@ MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
## E. 실행
별도의 명시적 사용자 요청이 있고 approved planning files가 materialize된 경우에만
Executor를 시작한다. Implementation Agent는 Executor가 선택한 current `stepN.md` 하나만
`RED -> observed failure -> minimal GREEN -> focused/full VERIFY` 순서로 수행하고 다음
Step을 시작하지 않는다.
```bash
python scripts/execute.py {task-name}
python scripts/execute.py {task-name} --push
.codex/skills/fesa-cpp-msvc-tdd/SKILL.md
+24 -12
View File
@@ -14,26 +14,38 @@ Read these first:
- `AGENTS.md`
- `docs/SOLVER_AGENT_DESIGN.md`
- `docs/implementation-plans/README.md`
- `docs/HARNESS.md`
- `docs/HARNESS_WORKFLOW.md`
- `docs/build-test-reports/README.md`
- `docs/corrections/README.md`
- `docs/implementation-plans/<feature-id>-implementation-plan.md`
- Related requirements, formulation, numerical review, I/O definition, and reference model documents
For Harness implementation, also read `.agents/skills/harness/SKILL.md`,
`.codex/hooks.json`, the materialized phase indexes, and the Executor-selected current
`stepN.md`.
## Workflow
1. For planning, use the project-local `harness` skill to convert upstream documents into a
user-approved multi-Step draft. Create `phases/` files only after approval and never run the
executor without a separate explicit request.
2. For implementation, follow `RED -> GREEN -> VERIFY`.
3. RED: write the planned unit, integration, parser/I/O, or reference-comparison test first.
4. RED: run the targeted test and verify the expected failure before production code.
5. GREEN: implement the minimum C++17/MSVC-compatible code needed for the task.
6. VERIFY: run the targeted command, then the full MSVC build/test commands resolved from `.harness/config.json` or the Harness defaults.
7. For C++ production changes, require a related C++ test file in the same patch or already present.
8. Treat PreToolUse as a test-file-existence guardrail, not proof that RED was observed. Record the RED and GREEN commands and results in the implementation report.
9. Let Stop perform the final whole-project MSVC build/test before the Step ends.
10. For failure triage, classify as `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`.
11. Fix implementation-owned failures only and keep changes traceable to the implementation plan.
user-approved multi-Step draft. Materialize only planning files after approval; planning never
selects or runs a Step. Run `scripts/execute.py` only after a separate explicit user request.
2. For implementation, require the approved plan, materialized phase files, and the
Executor-selected current `stepN.md`. Do not start another pending Step.
3. Execute the current Step as `RED -> observed failure -> minimal GREEN -> focused/full VERIFY`.
Update only its Codex-owned `status` plus `summary`, `error_message`, or `blocked_reason`.
The Executor owns branch, pending-Step selection, retry, timestamps, commits, and advancement.
4. Hooks are automatic through `.codex/hooks.json`: PreToolUse intercepts before edits and Stop
performs whole-project validation. Do not manually run their entry points as substitutes.
5. RED: write the planned unit, integration, parser/I/O, or reference-comparison test first.
6. RED: run the targeted test and verify the expected failure before production code.
7. GREEN: implement the minimum C++17/MSVC-compatible code needed for the task.
8. VERIFY: run the targeted command, then the full MSVC build/test commands resolved from `.harness/config.json` or the Harness defaults.
9. For C++ production changes, require a related C++ test file in the same patch or already present.
10. Treat PreToolUse as a test-file-existence guardrail, not proof that RED was observed. Record the RED and GREEN commands and results in the implementation report.
11. Let Stop perform the final whole-project MSVC build/test before the Step ends.
12. For failure triage, classify as `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`.
13. Fix implementation-owned failures only and keep changes traceable to the implementation plan.
## Output Contract
docs/SOLVER_AGENT_DESIGN.md
+25 -1
View File
@@ -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 변경
docs/implementation-plans/README.md
+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>
```