Files

T

$KOKO\Mimi$ KOKO\Mimi 18296a1944 docs: align Harness step execution guidance

2026-08-12 15:27:32 +09:00

7.6 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 프레임워크를 사용한다. 아래 워크플로에 따라 작업한다.

필수 읽기와 실행 소유권

계획, 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 등)를 읽고 프로젝트의 기획, 아키텍처, 설계 의도를 파악한다. 병렬 탐색이 실제로 유용하고 현재 세션에서 허용될 때만 Codex subagent를 선택적으로 사용한다.

B. 논의

구현을 위해 구체화하거나 기술적으로 결정해야 할 사항이 있으면 사용자에게 한 번에 하나씩 제시하고 논의한다.

C. Step 설계

사용자가 구현 계획 작성을 지시하면 여러 step으로 나뉜 초안을 작성해 피드백을 요청한다.

설계 원칙:

Scope 최소화 — 하나의 step에서 하나의 레이어 또는 모듈만 다룬다. 여러 모듈을 동시에 수정해야 하면 step을 쪼갠다.
자기완결성 — 각 step 파일은 독립된 Codex 실행에서 사용된다. 외부 대화 참조를 금지하고 필요한 정보를 모두 파일 안에 적는다.
사전 준비 강제 — 관련 문서와 이전 step에서 생성하거나 수정한 파일 경로를 명시한다.
시그니처 수준 지시 — 함수와 클래스의 인터페이스를 제시하고 내부 구현은 Codex 재량에 맡긴다. 멱등성, 보안, 데이터 무결성 같은 핵심 규칙은 명시한다.
AC는 실행 가능한 command — 추상적 조건 대신 실제 빌드와 테스트 command를 포함한다.
주의사항은 구체적으로 — "X를 하지 마라. 이유: Y" 형식으로 적는다.
네이밍 — step name은 핵심 작업을 표현하는 kebab-case slug로 정한다.

D. 파일 생성

사용자가 초안을 승인한 후에만 다음 파일을 생성한다.

Planning Agent는 초안을 만들고 승인받아 planning files만 materialize한다. planning Agent는 Step을 선택하거나 실행하지 않는다.

D-1. `phases/index.json`

여러 task를 관리하는 top-level 인덱스다. 이미 존재하면 phases 배열에 새 항목을 추가한다.

{
  "phases": [
    {
      "dir": "0-mvp",
      "status": "pending"
    }
  ]
}

dir: task 디렉터리명
status: pending | completed | error | blocked
timestamp는 executor가 상태를 바꿀 때 기록하므로 생성 시 넣지 않는다.

D-2. `phases/{task-name}/index.json`

{
  "project": "<프로젝트명>",
  "phase": "<task-name>",
  "steps": [
    { "step": 0, "name": "project-setup", "status": "pending" },
    { "step": 1, "name": "core-types", "status": "pending" },
    { "step": 2, "name": "api-layer", "status": "pending" }
  ]
}

필드 규칙:

project: AGENTS.md에 정의된 프로젝트명
phase: task 이름이며 디렉터리명과 일치
steps[].step: 0부터 시작하는 순번
steps[].name: kebab-case slug
steps[].status: 초기값 pending

상태와 기록 주체:

전이	기록 필드	기록 주체
`completed`	`summary`, `completed_at`	Codex가 summary, executor가 timestamp
`error`	`error_message`, `failed_at`	Codex가 message, executor가 timestamp
`blocked`	`blocked_reason`, `blocked_at`	Codex가 reason, executor가 timestamp

summary에는 다음 step에 유용한 생성 파일과 핵심 결정을 한 줄로 적는다. task created_at과 step started_at은 executor가 기록하므로 생성 시 넣지 않는다.

D-3. `phases/{task-name}/step{N}.md`

# Step {N}: {이름}

## 읽어야 할 파일

먼저 아래 파일을 읽고 프로젝트의 아키텍처와 설계 의도를 파악하라:

- `/AGENTS.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- 이전 step에서 생성하거나 수정한 파일 경로

이전 step의 코드를 꼼꼼히 읽고 설계 의도를 이해한 뒤 작업하라.

## 작업

구체적인 구현 지시를 파일 경로, 클래스와 함수 시그니처, 로직 설명과 함께 적는다.
구현체는 Codex에 맡기되 설계 의도에서 벗어나면 안 되는 핵심 규칙은 명시한다.

## Acceptance Criteria

프로젝트 형식에 맞는 명령을 사용한다. `.harness/config.json`이 있으면 해당 preset,
solution, configuration, platform, test command를 우선한다.

```powershell
# CMake
cmake --build .harness/build --config Debug
ctest --test-dir .harness/build -C Debug --output-on-failure

# 직접 MSBuild
MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
.\build\tests\Debug\MyProjectTests.exe
```

## 검증 절차

1. Acceptance Criteria command를 실행한다.
2. ARCHITECTURE 디렉터리 구조를 따르는지 확인한다.
3. ADR 기술 스택과 `AGENTS.md` CRITICAL 규칙을 확인한다.
4. 결과에 따라 task index의 Executor-selected current Step만 갱신한다.
   - 성공: `status`를 `completed`로 바꾸고 한 줄 `summary` 기록
   - 실행을 계속할 수 없는 오류: `status`를 `error`로 바꾸고 `error_message` 기록
   - 사용자 개입 필요: `status`를 `blocked`로 바꾸고 `blocked_reason` 기록 후 중단
   - retry, timestamp, commit, 다음 Step 선택과 advancement는 Executor가 기록한다.

## 금지사항

- 이 step의 범위 밖 기능을 추가하지 마라. 이유: step의 독립성을 깨뜨린다.
- 기존 테스트를 깨뜨리지 마라. 이유: 이전 동작을 회귀시킨다.

E. 실행

별도의 명시적 사용자 요청이 있고 approved planning files가 materialize된 경우에만 Executor를 시작한다. Implementation Agent는 Executor가 선택한 current stepN.md 하나만 RED -> observed failure -> minimal GREEN -> focused/full VERIFY 순서로 수행하고 다음 Step을 시작하지 않는다.

python scripts/execute.py {task-name}
python scripts/execute.py {task-name} --push

환경에서 Python 3 실행 명령이 python3이면 그 명령을 대신 사용한다.

executor가 처리하는 작업:

feat-{task-name} 브랜치 생성 또는 checkout
AGENTS.md와 docs/*.md guardrail 주입
완료 step의 summary를 다음 prompt에 누적
실패 시 최대 3회 재시도하며 이전 오류를 prompt에 전달
코드 변경과 metadata를 분리해 commit
started_at, completed_at, failed_at, blocked_at 기록

에러 복구:

error: 해당 status를 pending으로 바꾸고 error_message를 삭제한 뒤 재실행
blocked: 원인을 해결하고 status를 pending으로 바꾸고 blocked_reason을 삭제한 뒤 재실행

7.6 KiB Raw Blame History