| name | apple-harness |
| description | Swift/SwiftUI 기능이나 Apple 앱을 처음부터 끝까지 구현해야 할 때 사용하는 장기 오케스트레이션 스킬입니다. PLAN→DESIGN→BUILD→EVALUATE 루프가 필요할 때만 사용합니다. |
Apple Harness
원본 apple-harness의 의도를 Codex 오케스트레이션으로 옮긴 스킬입니다.
When to use
- 새 기능을 처음부터 끝까지 구현해야 할 때
- 대규모 UI 리팩터링이나 복합 프레임워크 통합이 필요할 때
- 단일 파일 수정이 아니라 단계별 검증 루프가 필요할 때
Do not use when
- 단일 파일 수정이나 짧은 버그 픽스처럼 작은 작업 →
apple-craft
- 구현 없이 리뷰·감사만 필요한 작업 →
apple-review
- PLAN→DESIGN→BUILD→EVALUATE 아티팩트를 유지할 필요가 없는 작업
Quick start
harness-spec.md와 features.json으로 목표와 기능 상태를 먼저 적는다.- 현재 라운드에서 다룰 기능 하나를 고른다.
- DESIGN → BUILD → EVALUATE를 한 사이클로 실행한다.
- 최대 3라운드 안에 수렴하지 않으면
pivot / rescope / escalate를 검토한다.
Shared artifacts
작업 산출물은 기본적으로 .codex/harness/ 아래에 둔다.
harness-spec.md — 제품/기능 스펙features.json — 기능 목록과 상태design-spec.md — 디자인 토큰·화면 구조evaluation-round-N.md — 검증 피드백
Use references
references/harness-design-principles.mdreferences/apple-hig-map.mdreferences/walkthrough-liquid-glass-settings.md
Orchestration flow
- PLAN — 요구사항을 구조화하고
harness-spec.md, features.json을 만든다.
- DESIGN — Pencil이 가능하면 화면 구조와 디자인 토큰을
design-spec.md에 남긴다.
- BUILD — 우선순위가 가장 높은 기능부터 작은 단위로 구현한다.
- EVALUATE — 빌드, 프리뷰, 런타임, 접근성, 설계 일치 여부를 점검한다.
- 실패한 항목이 있으면 최대 3라운드까지 반복한다.
Agent mapping
- Codex app/CLI에서는
.codex/agents/harness-*.toml custom agents를 우선 사용한다.
- 현재 환경에 custom agent 호출이 없으면 built-in subagent 또는 로컬 작업으로 역할을 분리한다.
- 평가 단계는 가능하면 read-only 역할로 유지하고, 구현 단계와 쓰기 범위를 분리한다.
Guardrails
features.json의 기능 항목은 삭제하지 말고 상태만 변경한다.- 한 번에 한 기능 또는 명확히 분리된 write scope만 다룬다.
- 빌드 성공 전 파괴적 후속 작업을 밀어붙이지 않는다.
Review Harness
- mode: required
- 공통 기준:
../../../docs/review-harness.md
- planner:
harness-spec.md, features.json, 필요 시 design-spec.md를 먼저 정의한다
- generator: builder가 기능 구현과 디자인 반영을 수행한다
- evaluator: evaluator/reviewer가 빌드, 프리뷰, 런타임, 접근성, 설계 일치 여부를 검토한다
- 평가축: feature completeness, functionality, visual design, code quality, acceptance criteria 충족
- artifacts/evidence:
.codex/harness/*, build log, preview, evaluation round 문서
- pass condition: 핵심 acceptance criteria가 충족되고, 실패 항목은 최대 3라운드 안에 수렴하거나 명시적으로 남아야 한다
- 자동 다음 행동:
pass면 다음 기능 또는 종료, refine이면 builder 재수행, pivot이면 설계 전환, rescope면 spec 갱신, 3라운드 초과 시 escalate한다
Output expectation
- 라운드별 결과
- 완료/실패 기능 목록
- 남은 리스크와 다음 액션
