🔧 Из чего сделан harness

5 подсистем — анатомия инженерной инфраструктуры агента

В модуле 1 мы разобрали 5 слоёв провалов — места, где агент ломается. Теперь разберём, чем наполнен хорошо устроенный harness, чтобы эти провалы не случались. Ключевое определение:

🍳 Кухонная метафора: 5 подсистем

Представьте профессиональную кухню. Повар (агент) блестящий, но без правильной инфраструктуры даже лучший шеф приготовит хаос.

⚡ Порядок атаки: Feedback first

Когда вы строите harness с нуля — не начинайте с самого очевидного. Начните с того, что даёт максимальный ROI при минимальных затратах:

🔗 Связь двух линз: слои провалов → подсистемы

В модуле 1 вы научились диагностировать, относя провал к одному из 5 слоёв. Теперь — чинить: каждый фикс попадает в одну из 5 подсистем.

📊 Интерактив 1: Эффект harness на реальном проекте

Кейс из практики: TypeScript + React, ~20 000 строк, модель GPT-4o. Модель не менялась. Добавлялись подсистемы harness — и росли результаты.

🧩 Интерактив 2: Слой провала → какая подсистема чинит?

Три сценария — определите, в какую подсистему harness нужно инвестировать.

🔬 Интерактив 3: Ablation-калькулятор

Isometric model control — экспериментальный метод: держите модель постоянной, отключайте (ablate) по одной подсистеме за раз, измеряйте просадку успеха. Так узнаёте, какая подсистема важнее именно для вашего проекта.

🗄️ Репозиторий как система записи

Модуль 3 · Harness Engineering — только то, что попало в репо, существует для агента

Единственный источник истины для агента

Агент работает в изолированном информационном пузыре: он видит системный промпт, текст задачи, файлы репозитория и вывод инструментов. Всё остальное — Slack-треды, Jira-тикеты, Confluence-страницы, устные договорённости — для него не существует.

Это означает: репо должно стать системой записи — авторитетным источником по решениям, ограничениям, текущему состоянию проекта и стандартам проверки. Не вторичным архивом, а единственным местом, куда агент (и любой новый член команды) смотрит за правдой.

Cold-Start Test — пять вопросов

Лучший способ проверить репозиторий — представить, что в него заходит свежая сессия агента, которая не помнит ни одного прошлого разговора. Может ли репо ответить на все пять вопросов?

🧮 Interactive 1 — Cold-Start Scorer

Оцени свой репозиторий по каждому вопросу (0 = нет информации, 1 = исчерпывающий ответ). Калькулятор покажет итоговый балл и примерный KVG (Knowledge Visibility Gap).

Три метрики здоровья репозитория

KVG — Knowledge Visibility Gap

Доля проектно-критичных решений и ограничений, которые живут вне репозитория: в головах, Slack, почте.

Discovery Cost — стоимость обнаружения

Сколько токенов контекст-бюджета агент тратит, чтобы найти нужное, даже если оно есть в репо. Информация может существовать, но быть закопанной в гигантский файл или рассыпанной по десяткам папок.

Knowledge Decay Rate — скорость устаревания

Доля документов, которые дрейфуют от кода со временем. Код эволюционирует — документация часто остаётся на месте.

Решение: размещать доки рядом с кодом, который они описывают (src/payments/ARCHITECTURE.md, а не docs/legacy/payments.md). Тогда PR, меняющий код, неизбежно проходит мимо документации — и reviewer замечает расхождение.

ACID для управления состоянием агента

Принципы ACID из баз данных применимы к git-репозиторию как к хранилищу состояния агентской работы.

git add -p          # только нужные изменения
git commit -m "feat: add retry logic"
git stash           # если нужно прервать

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: run-tests
        entry: pytest -q

git worktree add ../agent-b feature/b
# agent A: main
# agent B: ../agent-b (изолировано)

PROGRESS.md      ✓ переживает сессию
DECISIONS.md     ✓ переживает сессию
chat history     ✗ исчезает

Знание рядом с кодом

Один мега-документ в корне — антипаттерн. Когда репо вырастает, агент тратит весь бюджет на поиск нужного абзаца. Правило:

• Каждый модуль / сервис / библиотека — своя ARCHITECTURE.md и CONSTRAINTS.md
• Корневой CLAUDE.md — только навигация и команды запуска/проверки
• Корневой PROGRESS.md — живое состояние: что в работе, что заблокировано, какие решения приняты сегодня

project/
├── CLAUDE.md              # навигация + команды
├── PROGRESS.md            # текущее состояние
├── src/
│   ├── payments/
│   │   ├── ARCHITECTURE.md   ← агент читает сразу при входе в модуль
│   │   ├── CONSTRAINTS.md    ← ограничения рядом с кодом
│   │   └── *.py
│   └── auth/
│       ├── ARCHITECTURE.md
│       └── *.py
└── tests/
    └── AGENTS.md          # критерии приёмки тестов

🧠 Проверь себя

М4 📄 Почему один гигантский файл инструкций проваливается

Instruction Bloat, Lost-in-the-Middle и принцип Progressive Disclosure

В М1–М3 мы убедились, что наличие правила в AGENTS.md критически важно. Теперь разберём оборотную сторону: если продолжать складывать всё в один файл, он начинает вредить. Файл размером ~300+ строк замедляет агента, снижает точность и размывает приоритеты.

🗻 Феномен Instruction Bloat

Instruction Bloat — когда файл инструкций разрастается настолько, что занимает значительную долю контекстного окна. Эмпирическое правило: файл инструкций > ~10–15% окна контекста начинает вытеснять рабочую информацию о задаче.

📍 Lost in the Middle (Liu et al., 2023)

Исследование показало, что LLM лучше используют информацию в начале и конце длинного контекста. Информация в середине — «тонет». Практический вывод: критичные правила нельзя зарывать в середину длинного файла.

📊 Signal-to-Noise Ratio инструкций

Instruction SNR — доля пунктов файла, релевантных текущей задаче. Если агент работает над добавлением нового канала уведомлений, а в AGENTS.md 37 пунктов, из которых к этой задаче относятся только 30 — SNR = 81%. Если же он запускает тесты, релевантны только 18–19 пунктов — SNR = 50%.

Низкий SNR — это шум: агент тратит внимание на нерелевантные правила и может применить их некстати («правило про webhook неожиданно применяется к рефакторингу»).

🔢 Интерактив 1 — SNR-калькулятор

Введите число релевантных пунктов и общее число пунктов в файле — получите SNR. В Lesson 4 «всегда-релевантных» через все 5 типов задач оказалось 9 из 37 — это скелет будущего routing-файла (SNR скелета = 100%).

📊 Интерактив 2 — SNR по типам задач

Один и тот же AGENTS.md даёт разный SNR в зависимости от типа задачи. Среднее по 5 типам ≈ 48% — почти половина инструкций в любой задаче является шумом.

Данные Lesson 4: T1 — добавление канала, T2 — отладка ошибок, T3 — написание тестов, T4 — рефакторинг, T5 — обновление зависимостей. Среднее SNR ≈ 48%.

🗺️ Routing File: таблица вместо прозы

Routing File — короткий файл (50–200 строк), который не содержит деталей, а указывает на тематические документы. По сути это таблица: условие → документ.

## Условия → документация

| Условие                          | Документ                     |
|----------------------------------|------------------------------|
| Добавляешь новый канал           | docs/channels.md             |
| Меняешь схему БД                 | docs/db-migrations.md        |
| Пишешь или меняешь тесты         | docs/testing-guide.md        |
| Деплой / CI                      | docs/deploy.md               |
| Изменения в зависимостях         | docs/deps-policy.md          |
| Любая задача (safety-правила)    | docs/safety-critical.md      |

🔭 Progressive Disclosure

Progressive Disclosure — принцип «обзор сейчас, детали по требованию». Routing-файл даёт быстрый ориентир, детальные доки загружаются только когда нужны. Агент не «читает весь учебник» перед каждой задачей — он ищет нужную главу.

📖 Кейс: SaaS-команда, 50 → 600 строк → рефакторинг

Команда начала с AGENTS.md на 50 строк. За год, добавляя правила по одному, файл вырос до 600 строк. Что произошло:

• Успешность задач: 45% (агент применял правила не к тем контекстам)
• Соблюдение safety-правил: 60% (критичные правила оказались в середине)
• Жалобы команды: «агент игнорирует наши требования к деплою»

После рефакторинга: routing-файл (80 строк) + 6 тематических документов:

• Успешность задач: 45% → 72%
• Соблюдение safety-правил: 60% → 95% (критичные правила вынесены в отдельный doc, который загружается всегда)

🧪 Интерактив 3 — Проверь понимание

Дальше — жизненный цикл сессии: инициализация и преемственность контекста между запусками агента.

Жизненный цикл сессии

Инициализация как отдельная фаза · Преемственность контекста между сессиями

В предыдущих модулях мы разбирали, как агент выбирает задачи и строит план. Теперь — про то, что происходит внутри одной сессии и на стыке сессий: инициализация и передача контекста.

A. Инициализация как отдельная фаза

Типичная ошибка: агент сразу пишет бизнес-код, не заложив фундамент. Инструменты не настроены, тесты не запускаются, пути не созданы — и первый же import рушит всё. Это смешивание Initialization и Implementation.

Bootstrap Contract — 4 обязательных условия

Инициализация считается завершённой, когда выполнены все четыре пункта:

1. ✅ Можно запустить — среда поднимается без ошибок
2. 🧪 Можно протестировать — хотя бы один тест проходит зелёным
3. 📊 Виден прогресс — есть измеримый артефакт (файл, лог, строка в БД)
4. 🔗 Можно подхватить — следующий агент (или следующая сессия) понимает, что сделано и что дальше

TTFV — Time To First Verification

Ключевая метрика эффективности инициализации. Чем быстрее агент добился первого зелёного теста, тем меньше риск, что он потратит контекст на неверный фундамент.

🧩 Интерактив: Bootstrap Contract

Проверь понимание четырёх условий Bootstrap Contract.

B. Контекст между сессиями

Каждая новая сессия начинается с чистого контекста. Без структурированного хэндоффа агент читает состояние с нуля и рискует принять решения, уже принятые ранее — и принять их иначе.

Context Anxiety

Находка Anthropic: Sonnet 4.5 вблизи лимита контекста проявляет преждевременную сходимость — выбирает более простые решения, пропускает верификацию, торопится закрыть задачу. Это не баг поведения, это рациональный ответ на ресурсное давление.

Continuity Artifacts

Честный вывод: когда PROGRESS.md действительно нужен?

🧩 Интерактив: Нужен ли тут PROGRESS.md?

Три сценария из реальных воркlogов. Для каждого — определи, нужен ли PROGRESS.md.

📊 Стоимость дробления: marathon vs несколько сессий

Данные из lesson 5: одна и та же 3-канальная задача решалась тремя способами. Метрика — суммарные токены.

Overreach и Under-finish: почему WIP=1

Агенты активируют слишком много задач за сессию и завершают слишком мало. Разберём механику и противоядие.

Overreach: слишком много задач в работе

Агент начинает сессию с амбициозного плана: «реализую сразу 5 фич». Каждая задача активируется — создаётся ветка, пишутся первые строки кода. Но к концу сессии ни одна не прошла верификацию. Это overreach: разбросанные частичные реализации вместо одной завершённой фичи.

Under-finish и VCR

Under-finish — доля активированных задач, которые провалили верификацию несмотря на сгенерированный код. Overreach напрямую порождает under-finish: чем больше задач в работе, тем выше вероятность, что каждая из них не будет доведена до исполняемого доказательства.

Proof of Completion: исполняемое доказательство

«На глаз» не считается. Задача завершена только тогда, когда существует исполняемое условие, которое можно запустить и которое проходит.

Little's Law: математика WIP

Закон Литтла — фундаментальный результат теории очередей. Для стабильной системы:

Если λ = 1 фич/день и L = 5 (пять задач одновременно), то W = 5 дней на задачу. Держи L = 1 → W = 1 день → вероятность накопления ошибок минимальна.

🧮 Интерактив 1 — Калькулятор времени цикла (Little's Law)

📊 Интерактив 2 — Цена дисциплины WIP=1

Данные из реального эксперимента (lesson 7, worklog): ~700 строк, 6 фич, Sonnet. WIP=1 дороже по инструментам — но ловит то, что гейт пропускает.

⚠ Честный эмпирический вывод

# Без ограничений — отгружено молча:
class DispatchNotFound(Exception): ...   # ← НЕВЕРНО

# WIP=1 — поймано при внимательном обходе:
class DispatchNotFound(NotifyError): ... # ← ВЕРНО

# Вызыватели с "except NotifyError" промахиваются мимо
# DispatchNotFound — линтер по regex не видит наследование.

# retry() пересоздаёт Dispatcher.from_config() со свежими
# дефолтами — config-оверрайды исходной отправки теряются.
# Тест проходил, потому что тестировал happy-path без оверрайдов.

WIP=1 на практике: правила активации

🧠 Проверь себя

📋 Списки фич как структуры данных + многоуровневая валидация

Модуль 7 · AI-агенты и harness engineering

В модулях 1–6 мы говорили о том, что проверять и как строить гейты. Здесь — о том, где хранить скоуп и почему агенты объявляют победу слишком рано. Оба вопроса связаны: плохая структура данных о фичах = слепой гейт = ложная победа.

A. Список фич — структура данных, не планёрка

Типичная ошибка: список фич живёт в чате, трелло или голове менеджера. В harness-подходе список фич — это артефакт в репо, на котором работает автоматика. Он имеет строгую схему, версионируется и является входом для верификационного пайплайна.

🔷 Triplet — обязательная запись

Каждая строка списка фич несёт ровно три поля. Нет хотя бы одного — запись неполна и не может войти в пайплайн:

{
  "description": "POST /api/send возвращает 200 и записывает сообщение в БД",
  "verify_cmd":  "pytest tests/test_send.py::test_send_200 -x -q",
  "state":       "passing"
}

🔄 Feature State Machine

Каждая фича проходит 4 состояния. Переход → passing совершается только по успешному результату verify_cmd. Состояние passing — необратимо: регресс означает новый баг, а не откат.

  not_started ──→ active ──→ passing  (необратимо)
                    ↕
                 blocked

📌 SSoT — Single Source of Truth

Вся информация о скоупе исходит из одного списка фич. Это цепочка: source → derived → executable. Каждое звено может дрейфовать — если PROGRESS.md расходится с кодом, harness теряет ориентир.

📊 State Pressure — метрика готовности

Число фич, не находящихся в passing — это State Pressure. Ноль = проект завершён. Это количественная, объективная метрика готовности — в отличие от субъективного «кажется, всё готово».

🧮 Калькулятор State Pressure

B. Почему агенты объявляют победу слишком рано

Агенты судят по принципу «код, что я написал, выглядит правильно», а не «система E2E удовлетворяет спеке». Это систематическая ошибка, подкреплённая математикой.

📐 Calibration bias

Guo et al. (ICML 2017) показали: современные нейросети систематически переуверены — заявленная уверенность выше фактической точности. Модель говорит «95% что готово» там, где реальная точность — 70%.

📊 Данные из worklog: weak vs strict проверка

Lesson 8 — 11 специально подброшенных багов. Два режима проверки:

📊 Данные из worklog: false-done и слепота гейта

Lesson 9 — 21 прогон, calibration bias = 24% (5/21 false-done). Ключевой ковариат: покрытие гейта:

🔒 Dual verification-validation gateway

Чтобы победа была честной, нужны два независимых гейта:

Оба обязательны. L1 без L2 = проверил детали, упустил систему. L2 без L1 = ловишь симптомы, не причины.

🏗️ 3-уровневая валидация

⚡ Completion priority constraint

Строгий порядок приоритетов:

🎯 Проверь себя

Модуль 8: E2E-тестирование, наблюдаемость рантайма и чистый выход из сессии

Синтез курса: калибруй harness по давлению, а не по моде

A. Только E2E-тестирование меняет результат

Юнит-тесты проверяют каждый компонент в изоляции. Но агент — это система, где компоненты взаимодействуют. Межкомпонентные сбои юнит-тестам не видны:

• Рассогласование интерфейсов — модуль A ожидает строку, B отдаёт dict: тесты обоих зелёные, система сломана.
• Распространение состояния — ошибка в шаге 2 тихо меняет результат шага 4; каждый шаг тестируется независимо и проходит.
• Зависимости окружения — тест мокает файловую систему, но в реальном окружении путь другой.

Кейс Anthropic: ретро-игровой редактор

Anthropic сравнил два подхода к одной задаче (идентичный промпт — разработать ретро-игровой редактор):

30× по стоимости — и это оправданная инвестиция: дешёвый прогон даёт сломанный артефакт, дорогой — рабочий. Evaluator-агент в harness выполнял именно E2E-проверку после каждой итерации.

📊 Сравнение стоимости: голый агент vs harness

B. Сделай рантайм агента наблюдаемым

Агент без наблюдаемости работает в режиме «чёрного ящика»: он сам сообщает о своём состоянии, а его самооценка систематически смещена в сторону завершённости. Как в М3 мы говорили об ACID: нельзя доверять агенту, что транзакция завершена, — нужен внешний наблюдатель.

Практически: добавь в свой check.py (из М2) не только юнит-тесты, но и минимальный E2E-smoke: запусти приложение, пройди критический путь, убедись, что output совпадает с ожидаемым. Это и есть наблюдаемость рантайма в минимальной форме.

C. Каждая сессия должна оставлять чистое состояние

Как в ACID-Durability (М3): транзакция либо применена полностью, либо откатана. Сессия агента — это транзакция над codebase. Нельзя оставлять half-done состояние, красный гейт или недокументированные решения.

Плохой выход из сессии — это техдолг, который платится при следующем старте: новая сессия тратит время на понимание того, что было сделано, что не сделано, и почему принято то или иное решение. Это потеря контекста, о которой мы говорили в М5.

✅ Чек-лист выхода из сессии

Отметь каждый пункт перед закрытием сессии:

D. Синтез курса — мета-вывод

🧪 Финальный квиз: синтез курса

Готово 🎉

8 модулей пройдены. Что теперь у тебя в инструментарии:

• Видеть, что узкое место — не модель, а harness; относить каждый провал к одному из 5 защитных слоёв.
• Различать 5 подсистем harness (Instructions / Tools / Environment / State / Feedback) и чинить Feedback первым.
• Делать репозиторий системой записи: Cold-Start Test, KVG, ACID-состояние.
• Разбивать раздутый AGENTS.md на routing-файл + topical-доки (SNR, lost-in-the-middle).
• Держать контекст между сессиями: init-фаза, continuity-артефакты, handoff.
• Вводить WIP=1 и executable proof of completion; считать VCR и Little's Law.
• Строить feature lists как структуры данных и многоуровневую валидацию (weak vs strict).
• Требовать E2E, делать рантайм наблюдаемым и оставлять чистое состояние сессии.
• Калибровать методологию по масштабу — отличать заявления, что воспроизводятся, от тех, что работают только под реальным harness-давлением.

Что читать дальше

• Walking Labs — «Learn Harness Engineering». Первоисточник курса: walkinglabs.github.io/learn-harness-engineering
• Liu et al. (2023) — «Lost in the Middle». Эмпирика про деградацию внимания LLM к середине длинного контекста.
• Guo et al. (ICML 2017) — «On Calibration of Modern Neural Networks». Почему нейросети систематически переоценивают свою уверенность.
• Anthropic — инженерные заметки про агентов и контекст. Context anxiety, многоагентные harness, init-фаза.

▶ Пройти курс заново