# Context: Harness — Full Guide
- URL: https://zimmy.dev/harness
- Tags: harness, coding-agent, workflow, full-guide

## User intent hint
Use this full workflow guide as source context and preserve section structure.

## Hyperlinks (1-depth)
- Compound Engineering: https://every.to/guides/compound-engineering
- SDD Tools — Exploring Gen AI: https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
- Harness Engineering: https://openai.com/index/harness-engineering/
- Effective Harnesses for Long-Running Agents: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
- How Every Codes with Agents: https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents
- Building a C Compiler with an Agent: https://www.anthropic.com/engineering/building-c-compiler
- The Loop: https://ghuntley.com/loop/
- https://github.com/team-attention/plugins-for-claude-natives/tree/main/plugins/clarify/skills: https://github.com/team-attention/plugins-for-claude-natives/tree/main/plugins/clarify/skills

## Article content
This is the full Harness guide across all six sections.

## 00. Setup
Environment, logging, and session management essentials

1. 병렬로 App이 뜰 수 있게 만든다.
   - 병렬 실행시 재시작되거나 Kill 하거나 다른 App에서 테스트하는 경우를 방지한다.
   - 포트 충돌 방지할 수 있게 만든다.
2. log를 파일로 남긴다. backend error를 복붙하는거 병목이다.
   - timestamp와 로그가 발생한 파일도 작성해둔다.
   - 1줄로 남긴다. grep으로 한 방에 찾을 수 있게.
3. CLAUDE.md (AGENTS.MD)는 Knowledge Dump가 아닌 Routing File 역할을 하도록 단순하게 유지한다.
   - architecture, schema 등 구체적인 내용은 docs/ 에 몰아 넣고 링크만 남긴다.
4. 세션 관리
   - 한 화면에 2개 이상 세션은 안둔다. 인지력 부하가 온다
   - 탭으로 나눈다
   - 탭에 이름을 넣고 필요할 때만 나중에 이어서 작업할 때만 세션에 이름을 부여한다.
   - Image: 탭 기반 세션 관리 예시 — 각 탭에 작업 이름을 부여한 터미널 화면 (asset: session-management.png)
5. Plugin을 쓰되 공부하고 사용한다. 자신의 입맛에 맞게 수정해서 쓴다.
6. 음성 입력을 적극 활용하여 타이핑 병목을 줄인다.
   - 무선 핀 마이크를 사용하여 접근성과 활동성을 높인다.
   - Willow Voice와 같은 음성 인식 도구를 활용한다.

## 01. Spec
Requirements clarity before writing any code

1. 스펙 문서는 읽는다.
   - 급하거나 피곤하면 읽지 않고 넘긴다. 하지만 결국 읽는게 빠르다.
2. UI Component가 추가되는 Spec은 Terminal 내에서라도 Mock UI를 그려달라고 한다.
   - UX Designer & Product Owner 두 관점을 (병렬로) 고려해서 스펙을 작성해달라고 한다.
3. 모호한(Vague) 내용을 구체화 하고, 미지의 영역(Unknown)을 수면 위로 올리고, 구현 수단(Medium)을 탐색한다.
   - https://github.com/team-attention/plugins-for-claude-natives/tree/main/plugins/clarify/skills

## 02. Plan
Structured implementation strategy with DAG ordering

1. 구현 순서를 DAG로 나타내라고 한다. 병렬 실행을 위해서.
2. Plan이 Spec과 일치하는지 검토한다. 달라지는 경우가 많다.
3. Architecture, Framework 결정, DB Schema 설계 수준의 high level 기술적 결정은 "읽고 이해한다"
4. Verification Plan도 같이 세우라고한다.
   - 백엔드만 테스트하면 되는지 프론트엔드, E2E도 필요한지
   - 성공 조건을 읽는다.

## 03. Execution
Model selection, continuous work, and quality hooks

1. Verification이 완료될때까지 계속 작업하라고 시킨다.
2. 작업 종료 알림을 받는다.
3. Worktree를 생성해서 작업한다.
4. Syntax error를 잡는 Hook은 꼭 걸어둔다.

## 04. Verification & Review
Systematic checking and continuous improvement loops

1. Verification 도구를 인지하고 지속적으로 개선한다.
   - 검증 단계에서 사람의 개입이 필수적인 지점과 시스템에 온전히 위임할 수 있는 지점을 명확히 분리한다.
   - 단순 확인처럼 사람이 필요 없는 작업은 시스템 권한(e.g., Accessibility 권한)을 부여해 시스템이 직접 검증하게 한다.
   - Accessibility 권한을 부여하면 화면의 UI 요소를 읽고 클릭·타이핑할 수 있다.
   - 예: PPTX 파일 생성 시 '파워포인트에서 파일이 오류 없이 열리는지'는 시스템이 검증하고
   - '슬라이드의 미적 완성도 판단'은 사람이 직접 시각적으로 확인하도록 역할을 분담한다.
2. Spec/ Plan 에 있는 내용 구현되었는지 검토하라고 시킨다.
3. 선입력 시킨다. (자동화?)
4. Review Agent를 만든다.
5. 버그는 test coverage로 남기고 compound한다.

## 05. Compound
Turn every session into lasting organizational knowledge

1. Spec 문서는 requirements/ 에 저장한다.
2. 버그 수정 문서는 docs/bug-fix/ 하위 경로에 저장하고, "이번에 에이전트가 멍청하게 행동한 부분이 어디인가?" + "이 문제는 나중에도 또 발생할 것 같은가?"를 기준으로 오답 노트와 해결책(Solution)을 함께 정리한다.
3. 자동화는 slash command부터 시작한다. Sub agent, Skill, Hook을 처음부터 만들지 않는다.

## References
1. [Compound Engineering](https://every.to/guides/compound-engineering) (every.to)
2. [SDD Tools — Exploring Gen AI](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) (martinfowler.com)
3. [Harness Engineering](https://openai.com/index/harness-engineering/) (openai.com)
4. [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (anthropic.com)
5. [How Every Codes with Agents](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents) (every.to)
6. [Building a C Compiler with an Agent](https://www.anthropic.com/engineering/building-c-compiler) (anthropic.com)
7. [The Loop](https://ghuntley.com/loop/) (ghuntley.com)