steelmorgan/agent-debug

Отладочные сообщения (Agent Debug)

Когда применять

| Триггер | Действие | |---------|----------| | Стандартная диагностика не даёт понять поведение | Вставить debug-точки | | Гипотеза о причине ошибки — нужно подтвердить/опровергнуть | Логировать ключевые значения | | Непонятно какая ветка кода выполняется | Расставить маркеры по веткам |

НЕ применять если ответ можно получить чтением кода, event-log или скриншотом.

---

Формат debug-блока

//[AGENTDEBUG-001]
ЗаписьЖурналаРегистрации("AgentDebug",
    УровеньЖурналаРегистрации.Информация, , ,
    "STEP=001 PROC=ОбработкаПроведения MSG=Проверка суммы"
    + " | СуммаДокумента=" + Строка(СуммаДокумента)
    + " | Статус=" + Строка(Статус));
///[AGENTDEBUG-001]

Правила маркеров

• Открывающий: //[AGENTDEBUG-NNN]
• Закрывающий: ///[AGENTDEBUG-NNN] (три слэша)
• NNN — порядковый номер точки (001, 002, ...)
• Между маркерами — ТОЛЬКО отладочный код. Никакого рабочего кода внутри блока
• Вложенность блоков запрещена

Параметры ЗаписьЖурналаРегистрации

| Параметр | Значение | Зачем | |----------|----------|-------| | ИмяСобытия | "AgentDebug" | Фильтрация: все debug-записи одним запросом | | Уровень | Информация | Надёжно сохраняется в ЖР (Примечание может не сохраняться) | | МетаданныеОбъекта | Неопределено или конкретный объект | Если очевиден — указать для дополнительной фильтрации | | Данные | Ссылка на объект или Неопределено | Для корреляции с конкретным документом/элементом | | Комментарий | STEP=NNN PROC=... MSG=... \| key=value | Структурированный формат, легко парсить |

Формат комментария

STEP=001 PROC=ОбработкаПроведения MSG=Краткое описание гипотезы | Ключ1=Значение1 | Ключ2=Значение2

• STEP — номер точки (совпадает с маркером)
• PROC — имя процедуры/функции
• MSG — что проверяем (гипотеза)
• После | — ключевые значения в формате key=value
• Не логировать: большие структуры, таблицы значений, двоичные данные, пароли

---

Процедура

1. Сформулировать гипотезу — что именно проверяем и зачем
2. Определить точки — где в коде вставить логирование (1-3 на гипотезу, макс 5)
3. Вставить debug-блоки с маркерами //[AGENTDEBUG-NNN] ... ///[AGENTDEBUG-NNN]
4. Запустить тест — unit-тест или Vanessa-сценарий
5. Прочитать ЖР — фильтр по ИмяСобытия = "AgentDebug", сортировка по времени
6. Сделать вывод — гипотеза подтверждена/опровергнута
7. Удалить ВСЕ debug-блоки (см. чек-лист очистки)

Если одной итерации недостаточно — скорректировать точки и повторить (шаги 2-6). Если нужно 10+ точек — гипотеза слишком широкая, разбить на несколько.

---

Где вставлять

Порядок поиска подходящего места:

1. Модуль формы — обработчики событий, ПриИзменении, ПередЗаписью
2. Модуль объекта — ОбработкаПроведения, ПередЗаписью, ПриЗаписи
3. Модуль менеджера — если логика в менеджере
4. Общие модули — если вызов уходит в общий модуль

Изучение кода предпочтительно делегировать сабагенту (Explorer / code-navigation).

---

Чек-лист очистки

MUST перед завершением задачи:

1. Поиск в коде: AGENTDEBUG — ни одного вхождения не должно остаться
2. Проверить что удалены только строки между маркерами, рабочий код не затронут
3. Проверить синтаксис модулей после удаления
4. Убедиться что комментарии-маркеры тоже удалены (открывающий и закрывающий)

Удаление построчно:

• Найти строку с //[AGENTDEBUG-NNN]
• Удалять все строки до парной ///[AGENTDEBUG-NNN] включительно
• Если парный маркер не найден — СТОП, сообщить об ошибке

---

Антипаттерны

| Антипаттерн | Последствие | |-------------|-------------| | Рабочий код внутри debug-блока | Удаление блока сломает бизнес-логику | | Debug-блоки оставлены в финальном коде | Засорение ЖР, утечка данных | | 10+ точек на одну гипотезу | Широкая гипотеза, непонятный результат | | Логирование таблиц значений / больших структур | Переполнение ЖР, замедление | | Свободный текст вместо key=value | Сложно парсить при анализе |

---

depends_on:

• framework/skills/tool-usage/diagnostics/event-log-analysis/SKILL.md

---