harness-design

# Multi-Agent Harness Design

Источники:
- Anthropic Engineering — "Harness design for long-running apps"
- OpenClaw-RL paper (arxiv 2603.10165) — personal agent verification
- DenisSergeevitch/repo-task-proof-loop — execution protocol with durable proof

См. также: `references/proof-loop-research.md` — детали paper + repo mapping

## Когда нужен harness, а когда хватит solo agent

| Сигнал | Solo agent | Harness |
|--------|-----------|---------|
| Scope | Одна фича, bug fix, refactor | Full-stack app, multi-feature product |
| Длительность | < 30 мин | 1-6+ часов |
| Качество | Baseline достаточно | Нужен polish, originality, craft |
| Стоимость | ~$5-15 | ~$100-200+ |
| Проверка | Manual review | Automated evaluation + Playwright |

**Правило:** Evaluator оправдан когда задача **за пределами reliable solo performance**. Не фиксированное yes/no — зависит от complexity tier.

---

## Архитектура: Three-Agent System

### 1. Planner (Планировщик)
- Расширяет 1-4 предложения пользователя в **детальную спецификацию**
- Амбициозный scope — находит возможности для AI-фич
- **НЕ** over-specify реализацию — только what, не how
- Вписывает AI features в продукт органично

### 2. Generator (Генератор)
- Реализует фичи итеративно
- Включает **self-evaluation** перед handoff (но она ненадёжна — см. ниже)
- Работает в рамках Sprint Contract

### 3. Evaluator (Оценщик)
- **Независимый** от генератора — отдельный контекст, отдельный промпт
- Валидирует через Playwright MCP — скриншоты, навигация, тесты
- Откалиброван через few-shot примеры
- Ловит то, что self-evaluation пропускает

---

## Sprint Contract Pattern

Перед каждой итерацией:

```
1. Planner определяет фичу и user story
2. Generator и Evaluator ДОГОВАРИВАЮТСЯ о:
   - Что значит "done" для этой фичи
   - Конкретные testable success criteria
   - Что НЕ входит в scope
3. Generator реализует
4. Evaluator валидирует по контракту
5. Если не пройдено → конкретный feedback → повтор с п.3
```

**Контракт = мост** между user stories и implementation. Без него evaluator судит по своим критериям, generator не знает что проверять.

---

## Generator-Evaluator: Почему раздельно

### Self-evaluation bias
Модели **уверенно хвалят свою работу** — даже когда качество посредственное. Это не баг модели, а свойство: генератор оптимизирован на producing, не на judging.

### Решение: Independent evaluator
- Другой system prompt с calibrated skepticism
- Few-shot примеры с **детальными score breakdowns**
- Тестирует через browser, не через чтение кода
- Конкретные failure criteria, а не общие "looks good"

### Калибровка оценщика (QA Tuning Loop)
```
1. Evaluator выдаёт оценку
2. Ты проверяешь: согласен ли с оценкой?
3. Расхождение → обновляешь QA промпт
4. Типичные проблемы:
   - Superficial testing, пропускает edge cases
   - Premature approval посредственной работы
   - Слишком строгие критерии → бесконечные итерации
5. Повторяешь пока evaluator judgment ≈ твой judgment
```

---

## Quality Criteria Framework (для фронтенда)

### 4 измерения, каждое 0-10:

**1. Design Quality** — Целостность
> Дизайн ощущается как единое целое, а не коллекция частей?
- Интеграция color, typography, layout, imagery
- Consistent visual language

**2. Originality** — Уникальность
> Штраф за:
- Template layouts, library defaults
- AI slop patterns: purple gradients over white cards
- "Telltale signs of AI generation"
- Cookie-cutter структуры

**3. Craft** — Техническое мастерство
- Typography hierarchy
- Spacing consistency
- Color harmony, contrast ratios
- Pixel-perfect alignment

**4. Functionality** — Работоспособность
> Пользователь завершает задачу без угадывания?
- Все интерактивные элементы работают
- Нет stub features
- Error states обработаны

### Влияние формулировок на генерацию
Фразы в criteria **прямо влияют** на вывод генератора:
- "museum quality" → visual convergence к одному стилю
- "best designs" → перфекционизм за счёт creativity
- **Тестируй формулировки** — они стируют модель ДО оценки

---

## Контекст-менеджмент

### Context Degradation
Модели теряют coherence по мере заполнения context window.

**Context reset > Compaction:**
- Compaction сохраняет continuity, но не даёт чистый лист
- Reset + structured handoff artifact = лучший баланс
- Handoff artifact = документ с state, decisions, progress

### Context Anxiety
Модели (особенно Sonnet) начинают **сворачивать работу раньше времени** — думают что контекст кончается.
- Решение: clean context resets
- Opus 4.6: проблема значительно уменьшена

### Structured Handoff
При context reset передавать:
```
- Что уже сделано (с конкретными файлами/строками)
- Какие решения приняты и почему
- Что осталось сделать
- Текущие проблемы и blockers
- Sprint contract для текущей итерации
```

---

## Assumption Testing

> "Every component in a harness encodes an assumption about what the model can't do on its own"

### Принцип: предположения устаревают
- Модели улучшаются → scaffolding requirements снижаются
- Sprint decomposition нужно было для Sonnet → Opus 4.6 может без него
- **Стратегия**: убирать компоненты по одному, измерять влияние

### Simplification Loop
```
1. Текущий harness работает? Да →
2. Убери один компонент (напр. sprint decomposition)
3. Качество упало? Да → верни. Нет →
4. Повтори с другим компонентом
5. Остановись на минимальном harness для текущей задачи
```

---

## Реальные failure modes (пойманные evaluator'ом)

- Rectangle fill tool ставит тайлы только на endpoints drag, вместо заполнения области
- Delete key handler требует два условия, когда нужно одно
- FastAPI route matching: "reorder" матчится как integer frame_id
- Audio recording: stub без mic capture
- Missing clip resize/split operations
- Effect visualizations как числовые слайдеры вместо графики
- Display-only features без интерактивности
- Missing instrument panels
- Unimplemented recording functionality

---

## Инструментарий

### Claude Agent SDK
- Handles agent orchestration + compaction автоматически
- Manages context growth a