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
+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