中文版本 →

Примеры кода: code/ Практический проект: Проект 06. Полноценный harness (Capstone)

Лекция 11. Сделайте рантайм агента наблюдаемым

Какую проблему решает эта лекция?

Вы просите агента реализовать фичу. Он работает 20 минут, меняет кучу файлов и сообщает: «готово, но два теста падают». Спрашиваете почему — «не уверен, может быть, проблема с таймингом». Спрашиваете, какие критические пути он изменил — «дайте посмотреть в код…»

Дело не в том, что агенту не хватает способностей. Дело в том, что ваш harness не обеспечивает достаточной наблюдаемости. Без наблюдаемости агенты принимают решения в условиях неопределённости, оценки превращаются в субъективные суждения, а ретраи — в слепое блуждание. И OpenAI, и Anthropic определяют надёжность как проблему доказательств: harness должен раскрывать поведение во время выполнения и сигналы оценки в форме, которая может направлять следующее решение.

Ключевые понятия

• Рантайм-наблюдаемость: сигналы системного уровня — логи, трейсы, события процессов, проверки здоровья. Отвечает на вопрос «что сделала система».
• Процессная наблюдаемость: видимость артефактов решений harness — планов, рубрик оценки, критериев приёмки. Отвечает на вопрос «почему это изменение должно быть принято».
• Трейс задачи: полная запись пути решения от начала задачи до завершения, аналогично трассировке запросов в распределённых системах. Каждый шаг агента, с контекстом, фиксируется.
• Sprint contract: краткосрочное соглашение, согласованное до начала кодинга — определяет скоуп задачи, стандарты верификации и исключения. Основной инструмент процессной наблюдаемости.
• Рубрика оценщика: превращает оценку качества из субъективного суждения в основанную на доказательствах структурированную систему баллов. Заставляет разных оценщиков выдавать схожие результаты для одного и того же выхода.
• Многослойная наблюдаемость: наблюдаемость на системном и процессном уровнях, спроектированные одновременно и взаимно усиливающие друг друга. Рантайм-сигналы объясняют поведение; процессные артефакты объясняют намерение.

Многослойная наблюдаемость

Почему так происходит

Реальная цена отсутствия наблюдаемости

Когда у harness нет наблюдаемости, систематически появляются четыре типа проблем:

Невозможно отличить «корректно» от «выглядит корректно»: функция выглядит идеально на код-ревью — синтаксис правильный, логика здравая. Но во время выполнения ошибка обработки граничного случая выдаёт неверные результаты на конкретных входах. Только рантайм-трейсы могут показать, что фактический путь выполнения отклонился от ожиданий.

Оценка превращается в мистицизм: без рубрик оценки и критериев приёмки оценщики (человек или агент) опираются на неявные предположения. Один и тот же выход может получить дико разные оценки от разных проверяющих. Оценка качества становится невоспроизводимой.

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

Информационный обрыв при передаче сессии: когда незавершённая работа передаётся следующей сессии, отсутствие наблюдаемости означает, что новая сессия должна диагностировать состояние системы с нуля. Наблюдения Anthropic за долгоработающими агентами показывают, что эта избыточная диагностика может съедать 30–50% общего времени сессии.

Реальный сценарий с Claude Code

Представьте harness с трёхролевым воркфлоу «планировщик-генератор-оценщик», выполняющий задачу «добавить тёмную тему в приложение».

Без наблюдаемости: планировщик выдаёт расплывчатое описание. Генератор реализует тёмную тему на основе этой расплывчатости, но это не совпадает с неявными ожиданиями планировщика. Оценщик отвергает результат на основе своих собственных неявных стандартов, но не может точно сформулировать, что именно не так. Генератор слепо ретраит на основе размытых причин отказа. Цикл повторяется 3–4 раза, занимает около 45 минут и даёт едва приемлемый выход.

С полной наблюдаемостью: планировщик выдаёт sprint contract — список компонентов для модификации, стандарты верификации для каждого и исключения (никаких стилей для печати). Генератор реализует согласно контракту. Рантайм-наблюдаемость фиксирует процесс загрузки и применения стилей для каждого компонента. Оценщик использует балльную рубрику для оценки по измерениям с конкретными ссылками на доказательства. Одна итерация даёт высококачественный результат, около 15 минут.

Разница в эффективности в 3 раза. Единственное изменение — наблюдаемость.

Почему агенты не могут решить это сами

Вы можете подумать: «Почему агент сам не печатает свои логи?» Проблемы такие:

1. Агент не знает того, чего не знает — он не станет проактивно записывать сигналы, о необходимости которых он не подозревает.
2. Форматы логов несогласованы — разные сессии используют разные форматы логов, что делает систематический анализ невозможным.
3. Процессную наблюдаемость нельзя решить логами — sprint contracts и рубрики оценки являются структурированными артефактами, которым нужна поддержка на уровне harness.

Как делать правильно

1. Встройте сбор рантайм-сигналов в harness

Не полагайтесь на то, что агент сам напечатает логи. Harness должен автоматически собирать эти сигналы:

• Жизненный цикл приложения: состояния фаз startup, ready, running, shutdown
• Выполнение пути фичи: записи выполнения критических путей, включая точки входа, контрольные точки и выходы
• Поток данных: записи о потоке данных между компонентами
• Использование ресурсов: аномальные паттерны использования ресурсов (например, постоянно растущая память)
• Ошибки и исключения: полный контекст ошибки, а не просто сообщение об ошибке

2. Внедрите Sprint Contracts

Перед стартом каждой задачи генератор и оценщик (которые могут быть разными вызовами одного и того же агента) согласуют контракт:

# Sprint Contract: Dark Mode Support

## Scope
- Modify the theme toggle component
- Update global CSS variables
- Add dark mode tests

## Verification Standards
- Visual regression tests pass for each component
- Main flow end-to-end tests pass
- No flash of unstyled content (FOUC)

## Exclusions
- Not handling print styles
- Not handling third-party component dark mode

3. Установите рубрику оценщика

Превратите «хорошо или нет» в количественную систему баллов:

# Scoring Rubric

| Dimension | A | B | C | D |
|-----------|---|---|---|---|
| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |
| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |
| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |

4. Стандартизируйте через OpenTelemetry

Создавайте трейс для каждой сессии harness, span для каждой задачи и саб-span для каждого шага верификации. Используйте стандартные атрибуты для аннотации ключевой информации. Так данные наблюдаемости интегрируются со стандартными цепочками инструментов (Jaeger, Zipkin).

Реальный кейс

Harness, использующий воркфлоу «планировщик-генератор-оценщик», выполняющий задачу «добавить поддержку тёмной темы»:

Версия без наблюдаемости: 3–4 раунда слепых ретраев, 45 минут, едва приемлемый результат. Оценщик говорит «что-то не то», но не может сказать что именно. Генератор тратит много времени в неверных направлениях.

Полностью наблюдаемая версия:

• Sprint contract уточняет скоуп, стандарты и исключения
• Рантайм-трейсы фиксируют процесс загрузки стилей каждого компонента
• Балльная рубрика обеспечивает структурированную оценку по измерениям
• Одна итерация даёт высококачественные результаты, 15 минут

Прирост эффективности в 3 раза, более стабильное качество, воспроизводимые оценки.

Ключевые выводы

• Наблюдаемость — это архитектурное свойство harness — не фича, добавляемая постфактум, а ключевая способность, которую нужно учитывать при проектировании.
• Оба слоя наблюдаемости обязательны — рантайм-сигналы объясняют «что произошло», процессные артефакты объясняют «почему это сделано именно так».
• Sprint contracts заранее выравнивают понимание — предотвращают ситуации, когда «генератор построил то, что оценщик сразу отвергает по предсказуемым причинам».
• Балльные рубрики делают оценку воспроизводимой — разные оценщики выдают схожие баллы для одного и того же выхода.
• Отсутствие наблюдаемости тратит 30–50% времени сессии на избыточную диагностику.

Дополнительное чтение

• Observability Engineering — Charity Majors — теория и практика современного инжиниринга наблюдаемости
• Dapper — Google (Sigelman et al.) — прорывная практика крупномасштабной распределённой трассировки
• Harness Design — Anthropic — введение sprint contracts и рубрик оценщика
• Site Reliability Engineering — Google — систематическое применение наблюдаемости в продакшен-системах

Упражнения

1. Анализ пробелов в наблюдаемости: проведите аудит вашего текущего harness на предмет наблюдаемости системного и процессного уровней. Найдите состояния системы, которые невозможно различить по существующим сигналам, и предложите дополнения.

2. Практика Sprint Contract: напишите sprint contract для реальной задачи. Заставьте агента выполнить её согласно контракту и сравните эффективность и качество с контрактом и без него.

3. Построение трейса задачи: запишите каждый шаг операций агента в течение полной задачи кодинга. Аннотируйте семантическими конвенциями OpenTelemetry. Проанализируйте узкие места информации в трейсе — на каких шагах не хватает достаточных сигналов для решений.