agent-debug

---
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
---