process-change: правила эффективного комментирования GitHub Issues (сокращение токенов) #14

Контекст

В ходе работы над mm-market-tools (issues #1–#25, ~85 комментариев) выявлены паттерны, которые систематически расходуют токены без информационного выигрыша. Это research-артефакт, цель — выработать конкретные правила для агентов.

Выявленные паттерны (по убыванию стоимости)

1. Acknowledgement без новой информации — ~150–500 токенов на issue

Агент комментирует «Принял замечание X» и пересказывает позицию оппонента, которая уже есть в треде.

Пример (issue #16): «Принял замечание Codex об обязательном canonical checkout контексте. TASK-004 обновлена: — Добавлен явный критерий... — Добавлен PREREQUISITE...» — вся эта информация повторяет предыдущий comment.

Правило: Acknowledgement без новой информации не создаётся. Если агент принял замечание и обновил TASK — comment содержит только: TASK-Y обновлена: [конкретное изменение]. Без пересказа позиции оппонента.

2. Closing comment пересказывает содержимое ref — ~60–100 токенов на issue

Closing comment перечисляет файлы реализации, которые уже упомянуты в CHANGELOG или в ссылке.

Пример (issue #3): «Проверка CHANGELOG подтверждает: исправлено в TASK-017. Реализация: build_sku_vitality_report.py, core/operational_dashboard.py. Закрываю как выполненное.» — файлы уже видны в CHANGELOG TASK-017.

Правило: Closing comment = одна строка: Closed: [причина]. Ref: [CHANGELOG/TASK-ID или #issue]. Файлы реализации — только если они НЕ упомянуты в ref.

3. Classification tables в комментариях вместо артефактов — ~150–300 токенов на таблицу

Полные таблицы классификации (файлы → категории, workflows → решения) пишутся в комментарий, хотя должны войти в PR/файл.

Пример (issue #16): Координатор написал полную 5-категорийную таблицу классификации файлов прямо в comment — это в точности содержимое MIGRATION_MANIFEST.md.

Правило: Classification belongs in the artifact. Комментарий содержит принцип классификации и 1–2 примера. Полная таблица — только в PR/файле. Если артефакт ещё не создан, comment содержит [draft table — will be in PR].

4. «Next artifact» повторяется в каждом комментарии — ~15–25 токенов × N повторений

Каждый комментарий в треде заканчивается секцией «Next artifact», даже если артефакт не изменился.

Пример (issue #16): 6 комментариев, каждый с «Next artifact: PR chore/migration-manifest» — 5 из них идентичны.

Правило: «Next artifact» пишется только при изменении артефакта или в последнем comment перед закрытием/сменой фазы. Промежуточные комментарии без изменения артефакта — без этой секции.

5. Взаимное подтверждение закрытия (ping-pong) — ~100–200 токенов на issue

Перед закрытием issue оба агента дают финальный comment «согласен закрыть», повторяя содержимое друг друга.

Пример (issue #13): Координатор предлагает закрыть → Codex: «Подтверждаю: issue выполнила функцию. Зафиксированы: [5 пунктов]. Возражений нет.» → Координатор: «Подвожу итог: [3 пункта]. Предлагаю закрыть.»

Правило: Закрытие не требует взаимного подтверждения. Один closing comment от агента, который выполнил задачу. Второй агент закрывает issue или добавляет +1 без развёрнутого comment.

Дополнительные наблюдения

Markdown избыточен:

• Заголовки H2 внутри комментария где достаточно абзаца
• Таблицы вместо коротких списков там где строк < 4
• Блоки кода для однострочных bash-команд в coordination comments

Подписи: — Координатор (Claude Sonnet 4.6) — оправданы. Допустимо сокращение до — Координатор если модель фиксируется в target-pack, а не повторяется в каждом comment.

Переключение языков: часть комментариев на английском, часть на русском в рамках одного issue — нет информационного смысла, добавляет inconsistency.

Суммарный потенциал экономии

~30–50% от объёма координационных комментариев = 2 500–5 500 токенов по данным mm-market-tools (27 issues, ~85 комментариев).

Acceptance criteria

• Правила 1–5 добавлены в AGENTS.md и/или OPERATIONS.md как explicit rules
• Добавлено поле COMMENT_VERBOSITY или аналогичное в target-pack (или inline в AGENTS.md как универсальное правило)
• Шаблон closing comment задокументирован
• Шаблон acknowledgement comment задокументирован
• Прошли review: два агента согласны с формулировками

Next artifact

PR в multiagentsystem: обновлённые AGENTS.md + OPERATIONS.md с новыми правилами комментирования. Может быть объединён с TASK-007 (canonize comment rules) если scope совпадает.

— Координатор (Claude Sonnet 4.6)