Чем она отличается от обычного трейса агента
Agent Observability отвечает, какие вызовы модели и инструментов произошли внутри одного запроса. Навигационная трасса берёт узкий срез того же потока и проецирует его на структуру репозитория:
задача → поиск → каталог → routing-файл → исходник → повторное чтение → изменение.
Проекция полезна, когда оптимизируют не саму модель, а среду вокруг неё: корневую инструкцию, описания skills, карту документации, границы каталогов и поисковые инструменты (Harness Optimization). На ней виден кружной путь, который в линейном журнале команд теряется среди остальной работы.
Граница важна: file touch не равен попаданию содержимого в контекст. grep мог вернуть одну строку, Read — целый файл, а индекс — только описание. Карта посещений показывает маршрут, но без размера результата инструмента не показывает реальную цену этого маршрута (Bounded Tool Output).
Какие события составляют трассу
Минимальное событие содержит:
- идентификатор задачи и сессии;
- операцию:
search,list,read,edit,write; - нормализованный путь и рабочий каталог;
- время или порядковый номер шага;
- объём результата инструмента, если он известен;
- принадлежность основному агенту или субагенту;
- версию модели, harness и ревизию репозитория для сравнимости.
Structured file path надёжнее пути, извлечённого из shell-команды. Если grep или find записаны одной строкой Bash, восстановление затронутых файлов остаётся эвристикой: паттерн поиска, редирект и настоящее чтение синтаксически похожи. Такие события надо помечать как inferred, а не смешивать с подтверждёнными.
Что измерять
| Метрика | Что обнаруживает | Оговорка |
|---|---|---|
| Время или шаги до первого релевантного файла | качество точки входа и routing descriptions | нужен заранее размеченный ожидаемый материал |
| Число уникальных прочитанных файлов | ширину обхода | меньше не всегда лучше: агент мог недособрать доказательства |
| Доля нерелевантных чтений | паразитный контекст | релевантность определяется относительно задачи, не имени каталога |
| Повторные чтения и возвраты между ветками | потерю фокуса, слабую карту или забывание | повтор может быть оправдан после изменения файла |
| Объём результатов чтения | приближение к контекстной стоимости | file touch без байтов/токенов этого не даёт |
| Task completion и качество результата | не куплена ли короткая траектория ценой ошибки | это ведущая метрика, маршрут — диагностическая |
Цикл в графе сам по себе не дефект: исходник → тест → исходник — нормальная проверка. Подозрителен цикл, который не меняет состояние задачи и не приносит новых данных. Поэтому «число повторов» без семантики шага превращает осмысленную итерацию в ложную тревогу (Behavioral Evals).
Как ставить A/B структуры репозитория
- Собрать 10–20 реальных формулировок задач и для каждой заранее указать ожидаемые skills, документы или исходники.
- Зафиксировать модель, права, инструменты, ревизию кода и бюджет; менять только routing layer.
- Прогнать обе конфигурации несколько раз: один запуск не отделяет эффект структуры от разброса модели.
- Сравнить сначала task completion и корректность, затем навигационные метрики как объяснение разницы.
- Держать часть prompts отложенной: описание, подогнанное под известные формулировки, перестаёт быть тестом (Harness Optimization).
Три класса ошибки соответствуют проверке Agent Harnesses: загрузилось не то, не загрузилось ничего, загрузилось слишком много. Визуальное дерево помогает найти конкретную ветку, но решение об изменении принимается по повторяющемуся провалу и отложенной проверке, а не по красивой или короткой картинке.
Routing-файлы и границы обхода
Agent Harnesses предлагает один конкретный файловый протокол progressive disclosure: краткий HARNESS.md, routing-файл в каждой крупной ветке и termination boundary перед внутренностями skill или большим хранилищем. .harnessleaf отмечает явный лист, .leaf-detectors — тип листа по наличию файла вроде SKILL.md; вложенный HARNESS.md начинает самостоятельное дерево маршрутизации.
Переносим здесь не имена файлов, а инвариант: у каждой крупной ветки есть дешёвый ответ «стоит ли идти сюда?» и явная точка, после которой общий обход прекращается. Конвенция работает только если клиент или metaskill действительно соблюдает эти границы; наличие файлов само по себе поведение агента не принуждает (Agent First Repository).
ahar-visualizer как экспериментальный пример
ahar-visualizer строит дерево VS Code workspace и пассивно опрашивает JSONL-транскрипты Claude Code. Он подсвечивает структурированные Read / Edit / Write, эвристически извлекает пути из Bash и учитывает отдельные транскрипты субагентов.
Инструмент годится для ручной диагностики, но не является системой измерения стоимости:
- glow затухает по числу строк транскрипта, а не по физическому времени;
- размер прочитанного контента и токены не учитываются;
- Bash-пути восстанавливаются эвристически;
- выбирается наиболее недавно изменённая сессия, что неоднозначно при параллельной работе;
- JSONL — внутренний неверсионированный формат Claude Code и может тихо измениться;
- поддержка привязана к Claude Code и не переносится на другой harness без нового адаптера событий.
Поэтому визуализатор — хороший exploratory UI поверх сырой трассы, но baseline, агрегация и регрессионный отчёт должны жить отдельно.
Связано с
- Agent First Repository — как карта и progressive disclosure уменьшают стоимость входа в репозиторий
- Harness Optimization — как превращать наблюдённый маршрут в проверяемое изменение обвязки
- Agent Observability — полный execution trace, из которого берётся навигационная проекция
- Behavioral Evals — почему оцениваются и процесс, и результат
- Context Layers — почему выборочная загрузка относится к cached-контексту
- Code Structural Search — структурный поиск как альтернатива широкому файловому обходу