# Harness

> 하네스, 테스트 주도 팀, TDD 팀, 병렬 개발, 스펙 구현 - Spec/PRD-driven parallel development using Agent Teams. Generates tests first, then orchestrates teammates to make all tests pass. Use when implementing a feature or project from a spec with agent teams. Do NOT use for single-file changes or simple bug fixes.

- Skill: `aimskr/harness` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add aimskr/harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aimskr/harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: aimskr (https://skillmd.com/u/aimskr)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aimskr/harness

---


# Harness - Spec-Driven Parallel Development

You are a team lead running a test-driven harness.
Your ONE goal: make all tests pass.

> **PROGRESS 파일**: `.harness/PROGRESS-{feature}.md` — 다중 하네스 동시 실행을 지원한다.

## Phase Overview

```
Phase 0: Spec Intake → Analyze spec, extract feature name, create .harness/PROGRESS-{feature}.md
Phase 1: Test Suite  → Lead writes ALL tests (only phase lead writes code)
Phase 2: Team Setup  → Spawn agent team, assign tasks
Phase 3: Harness Loop → Test → Analyze → Decide → Track → Commit → Repeat
Phase 4: Convergence → 100% pass confirmed, lessons learned, cleanup
```

## Phase 0: Spec Intake

1. Ask user for spec location
2. Check `~/.claude/skills/harness/LESSONS_LEARNED.md` for prior lessons
3. Read spec, analyze project structure (stack, conventions, test runner)
4. **Extract feature name**: spec/PRD 제목 → kebab-case 변환 → 사용자 확인
   - 예: "사용자 인증 시스템 MVP" → `auth-system-mvp`
   - "하네스 이름: `auth-system-mvp` — 맞나요?"
   - 영문/숫자/하이픈만 허용
5. **`.harness/` 디렉토리 준비**
   - 없으면 `mkdir .harness`
   - `.gitignore`에 `.harness/` 엔트리 없으면 추가
6. **충돌 체크**: `.harness/PROGRESS-{feature}.md`가 이미 존재하면 사용자에게 경고
   - 덮어쓸지 / 이름 변경할지 확인
7. Define module boundaries and file ownership map
8. Create `.harness/PROGRESS-{feature}.md` (see `references/progress-template.md`)
9. Confirm module breakdown with user

## Phase 1: Test Suite Generation

Lead writes tests directly. For each module:
- Happy path, edge cases, error cases, integration points
- Tests verify general correctness, NOT specific outputs
- Run all tests → confirm ALL FAIL
- Commit: `test: initial test suite (0/N passing)`

For test reporting format and execution tiers, see `references/phase-details.md`.

## Phase 2: Team Setup

Inform user: **"Phase 2 시작: delegate mode (Shift+Tab)로 전환해주세요."**

Spawn team: researcher, impl-1~N (max 4), tester, reviewer.
Each implementer gets file ownership, target tests, **and the PROGRESS file path** (`.harness/PROGRESS-{feature}.md`).

For team creation prompts and spawn context, see `references/phase-details.md`.

## Phase 3: Harness Loop

**Core loop — repeat until all tests pass or max 10 iterations.**

```
Step 1: Test      → Message tester (quick/smoke/full tier)
Step 2: Analyze   → Compare with previous .harness/PROGRESS-{feature}.md
Step 3: Decide    → Regression? Stalled? Complete? Act accordingly
Step 4: Track     → Update .harness/PROGRESS-{feature}.md (EVERY iteration)
Step 5: Commit    → Implementers + lead commit
Step 6: Guard     → Pause at 10 iterations, ask user
```

### Decision Quick Reference

| Condition | Action |
|-----------|--------|
| Regression | STOP new work → fix immediately |
| Stalled 2+ rounds | Researcher investigates → new tasks |
| Wrong test | Confirm with user → adjust with approval |
| Module complete | Reviewer checks → reassign implementer |

### Parallelism by Pass Rate
- **0-80%**: Max parallelism by module
- **80-95%**: Cluster by dependency graph
- **95-100%**: Researcher first, then single implementer

For full loop details, mistake recording protocol, and sub-agent guidelines, see `references/phase-details.md`.

## Phase 4: Convergence

1. Full test suite → confirm 100%
2. Update `.harness/PROGRESS-{feature}.md` status to `COMPLETE`
3. Extract lessons → append to `LESSONS_LEARNED.md`
4. **Delete `.harness/PROGRESS-{feature}.md`** (lessons already extracted)
5. If `.harness/` is empty, remove the directory
6. Shutdown team, final report

## 문서화 (Phase 4 완료 후 자동 실행)

작업 완료 시 `auto-documenter`를 호출하여 프로젝트 문서를 업데이트한다.

## Lead Rules Summary

See `references/lead-rules.md` for complete 19 rules. Key rules:
- NEVER implement code yourself (except Phase 1)
- Regression = highest priority
- File ownership is sacred
- No hard-coding, no over-engineering
- Record every mistake with prevention rule

## Completion

Phase 4 완료: 전체 테스트 100% 통과 + `.harness/PROGRESS-{feature}.md` 삭제 + LESSONS_LEARNED.md 업데이트.

## Troubleshooting

**Tests pass but implementation is wrong**: Tests may be too loose. Tighten assertions to verify correctness, not just absence of errors.
**Agent team member is stuck**: Reassign the task or spawn a researcher to investigate. Never wait more than 2 iterations on a stalled task.
**Regression after a fix**: Immediately stop all other work. The implementer who caused the regression owns the fix. Update `.harness/PROGRESS-{feature}.md` with the regression event.
**PROGRESS file conflict**: If `.harness/PROGRESS-{feature}.md` already exists at Phase 0, another harness may be running with the same name. Ask user to rename or confirm overwrite.