---
name: agent-debug
description: Паттерн отладочных сообщений для 1С BSL. Используй, когда стандартная диагностика (event-log, скриншоты) не даёт понять фактическое поведение системы — нужно вставить временные точки логирования в код, запустить тест и проанализировать записи ЖР.
---
# Отладочные сообщения (Agent Debug)
## Когда применять
| Триггер | Действие |
|---------|----------|
| Стандартная диагностика не даёт понять поведение | Вставить debug-точки |
| Гипотеза о причине ошибки — нужно подтвердить/опровергнуть | Логировать ключевые значения |
| Непонятно какая ветка кода выполняется | Расставить маркеры по веткам |
**НЕ применять** если ответ можно получить чтением кода, event-log или скриншотом.
---
## Формат debug-блока
```bsl
//[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
---