Наблюдаемость AI-агентов: как понять, что сделал агент, и что для этого логировать

Что такое наблюдаемость AI-агента

Наблюдаемость AI-агентов — это возможность по артефактам, а не по памяти и не по словам агента, ответить на три вопроса: что он сделал, почему именно так и чем подтверждено, что результат верен. Если после двадцати минут работы агент говорит «готово, но два теста падают, возможно, из-за тайминга», а на вопрос «какие пути затронуты» отвечает «дайте посмотреть код», — наблюдаемости нет. Агент не глупый: ему просто нечего предъявить.

Проблема системная. Один и тот же агент за неделю может десять раз честно сказать «готово», и каждый раз это будет значить что-то своё: где-то прогнаны все тесты, где-то только один, где-то ничего. Чем дольше живёт проект, тем дороже каждая следующая сессия, потому что она начинается с раскопок.

Два слоя: рантайм и процесс

Наблюдаемость путают с логами, но логи — только половина.

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

Почему агент не сделает это сам

Сказать агенту «логируй получше» не сработает по трём причинам.

• Он не знает, чего не знает. Агент не залогирует сигнал, о важности которого не догадывается.
• Формат плавает. В одной сессии он пишет подробно, в другой — одной строкой. Сравнивать сессии и считать агрегаты невозможно.
• Процесс логами не закрыть. Ответ на «почему так» живёт в документах, созданных до работы, а не в выводе команд.

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

Что логировать: минимальный набор

Хороший журнал — не стенограмма всего подряд, а набор фактов, по которым можно восстановить ход работы и посчитать статистику.

• Идентификаторы: id сессии, id задачи или фичи, модель агента.
• Действия с побочными эффектами: какие команды запущены, какие файлы изменены. Чтение файлов обычно можно не писать.
• Результаты проверок: какая команда проверки, код возврата, сколько тестов прошло и упало.
• Ретраи: сколько попыток ушло на шаг и чем они отличались.
• Расход: токены и время, если инструмент их отдаёт.
• Итог: задача принята, отклонена или брошена, и почему.

Чего не писать: секреты, токены доступа, персональные данные из вывода команд. Журнал может уйти в общий доступ или снова в контекст модели.

Журнал действий через хуки Claude Code

В Claude Code журнал удобно вести хуками — командами, которые запускает сам инструмент, а не модель, поэтому они срабатывают всегда. Хук получает на вход JSON с описанием события, в том числе id сессии, имя инструмента и его параметры. Пример настройки в .claude/settings.json, которая после каждого вызова Bash, Edit или Write дописывает строку в журнал:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — одна JSON-строка на действие
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

Формат JSONL (одна JSON-запись на строку) удобен тем, что его легко фильтровать jq и грузить в любую систему анализа. Кроме того, Claude Code сам хранит полную историю сессий локально в каталоге ~/.claude/projects/ — её можно открыть, если нужно посмотреть рассуждения и вывод целиком, но для статистики свой компактный журнал удобнее.

Трассировка: трейс на сессию, span на задачу

Когда агентов много или они работают по расписанию, текстовых журналов мало: нужны агрегаты. Здесь пригодятся обычные инструменты распределённой трассировки и стандарт OpenTelemetry.

• Трейс — одна сессия агента.
• Span — одна задача внутри сессии.
• Вложенные span — шаги верификации: сборка, тесты, e2e.

Минимум атрибутов на span: id фичи и сессии, модель, результат проверки, токены, число ретраев. Такие данные читаются в Jaeger, Grafana Tempo, Honeycomb и отвечают на вопросы, которые не видно в одной сессии: какой тип задач чаще требует ретраев, где агент тратит больше всего токенов, после какого изменения харнеса упала доля принятых задач. У Claude Code есть встроенная выгрузка метрик и событий через OpenTelemetry — она включается переменными окружения, подробности в документации инструмента.

Коммиты как журнал

Самый дешёвый и надёжный журнал у вас уже есть — git. Его нужно лишь сделать читаемым.

1. Один коммит — одна задача. Тогда git log совпадает со списком сделанного, а откат задачи — один git revert.
2. В сообщении — что и как проверено. Не «fix», а «что изменено, почему, какой командой проверено».
3. Коммит только после зелёной проверки. Тогда каждая точка истории — рабочее состояние, и git bisect находит виновника.

fix(payments): округление скидки до копеек

Скидка считалась во float, на сумме 999.99 терялась копейка.
Перевёл расчёт на int в копейках.
Проверено: make test (142 passed), make e2e checkout — ок.
Вне скоупа: округление в отчётах, записано в BACKLOG.md.

Отчёт агента: доказательства вместо впечатлений

Финальное сообщение агента — тоже артефакт наблюдаемости, если у него фиксированная форма. Пропишите шаблон в AGENTS.md или CLAUDE.md:

## Отчёт в конце задачи
- Что сделано: список изменений (файл — суть)
- Как проверено: точные команды и их результат
- Что НЕ проверено и почему
- Отклонения от договора о задаче
- Открытые вопросы к человеку

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

Договор до кода и рубрика после

Процессный слой начинается до работы. Короткий договор о задаче (sprint contract) фиксирует скоуп, критерии приёмки, раздел «вне скоупа» и открытые вопросы, которые решает человек. Раздел «вне скоупа» предотвращает половину споров о результате.

После работы результат оценивают по рубрике, а не по впечатлению. Иначе два опытных ревьюера дадут разные вердикты, и оценка станет лотереей.

Каждое измерение оценивается A/B/C/D, и оценка без ссылки недействительна. Простое правило решения: одна D или две C — отклонить со списком того, что исправить. Эту же рубрику может применять отдельный агент-проверяющий.

Как разобрать, что сделал агент за сессию

Если отчёта нет или ему нет доверия, пройдите по артефактам в таком порядке.

1. Состояние дерева: git status — что не закоммичено, нет ли мусорных файлов.
2. История: git log --stat с начала сессии — какие коммиты и файлы.
3. Масштаб изменений: git diff --stat main...HEAD, затем полный diff по важным файлам.
4. Журнал действий: какие команды запускались и что вернули проверки.
5. Повторная проверка: сами запустите сборку и тесты. Доверяйте выводу команды, а не пересказу.

# какие команды запускал агент в последней сессии
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# какие файлы правил чаще всего
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Типичные ошибки

• Логировать всё. Гигабайты стенограмм никто не читает. Пишите действия с побочными эффектами и результаты проверок.
• Свободный формат. Если формат журнала задаёт сам агент, агрегатов не будет. Формат задаёт харнес.
• Верить отчёту без вывода команд. «Тесты зелёные» без вывода — это мнение.
• Слепые ретраи. Без причины сбоя агент правит случайные места. Требуйте сначала диагноз со ссылкой на лог, потом правку.
• «Уберём потом». Отладочные файлы и незакоммиченные изменения сбивают с толку следующую сессию: она не отличит временное от намеренного.

Итог

Наблюдаемость AI-агентов строится из двух слоёв: рантайм (журнал действий через хуки, трейсы, коммиты с описанием проверок) и процесс (договор о задаче до кода, рубрика и отчёт со ссылками на доказательства). Тогда «готово» означает одно и то же в каждой сессии, а разбор работы агента занимает минуты. Эта тема разобрана на практике в курсе по harness engineering, на сквозном проекте платёжного бэкенда.