Expand AGENTS.md with current repo and reporting rules

.agent/skills/communication-reporting/SKILL.md

@@ -0,0 +1,248 @@
+# Skill: Communication Reporting
+
+## Когда использовать
+
+Используй этот skill в каждом ответе пользователю после анализа, правки кода, ревью, аудита, планирования рефакторинга или подготовки PR. Особенно если задача затрагивает несколько файлов, backend/frontend boundary, security, Windows services или UI.
+
+## Цель
+
+Писать так, чтобы человек с опытом разработки быстро понял суть без чтения технической простыни. Не упрощать до детского сада, но объяснять по-человечески: что поменялось, где, зачем, как проверить, где риск.
+
+Пользователь не обязан продираться через внутренний монолог агента и каталог аббревиатур. У него есть жизнь, возможно даже вне репозитория, страшно представить.
+
+## Базовый формат ответа
+
+Для нетривиальных изменений используй такую структуру:
+
+```text
+Коротко
+- 2-4 пункта: главный результат, важный риск, что проверить.
+
+Что изменилось по файлам
+| Файл | Что изменилось | Зачем |
+|---|---|---|
+| src/... | Кратко | Человеческая причина |
+
+Важные места
+- 3-6 конкретных мест: файл + функция/секция + смысл.
+
+Как проверить
+- Команды или ручные шаги.
+
+Что не проверено
+- Честно и коротко.
+
+Риски
+- Только реальные риски, не философия.
+```
+
+Если изменение маленькое, можно сократить до:
+
+```text
+Коротко: ...
+
+Файлы:
+- `path`: что и зачем.
+
+Проверка: ...
+```
+
+## Правила ясности
+
+- Сначала вывод, потом детали.
+- Не писать длиннее, чем нужно для решения задачи.
+- Не перечислять каждую строку diff. Указывать только смысловые изменения.
+- Всегда называть конкретные файлы.
+- Для сложных мест указывать функцию, модуль или секцию, если это помогает найти код.
+- Если используешь термин, рядом дать короткое человеческое объяснение.
+- Не использовать аббревиатуры без расшифровки при первом упоминании, кроме очевидных: UI, JSON, URL, API.
+- Не писать «улучшена архитектура» без объяснения, что именно стало проще или безопаснее.
+- Не писать «всё готово», если часть проверок не запускалась.
+- Не скрывать ошибки окружения. Если `cargo` или Windows недоступны, так и сказать.
+
+## Как объяснять технические изменения
+
+Плохо:
+
+```text
+Refactored orchestration layer and extracted imperative use-case side effects into composable boundaries.
+```
+
+Хорошо:
+
+```text
+Вынес запуск service-команд из большого `commands.rs` в отдельный модуль. Теперь Tauri command только принимает запрос и возвращает ошибку, а вся Windows-логика лежит отдельно. Так проще тестировать и меньше шанс сломать соседние команды.
+```
+
+Плохо:
+
+```text
+Added CSP hardening.
+```
+
+Хорошо:
+
+```text
+Включил CSP в `src-tauri/tauri.conf.json`. Это ограничивает, какие скрипты/ресурсы может загрузить webview, и снижает ущерб, если в UI когда-нибудь появится XSS.
+```
+
+## Уровни детализации
+
+По умолчанию — средний уровень:
+
+- достаточно конкретно, чтобы разработчик понял diff;
+- без пересказа каждой строки;
+- без внутренних рассуждений агента;
+- без длинной теории.
+
+Если пользователь просит глубже, добавь раздел:
+
+```text
+Детальнее
+- ...
+```
+
+Если пользователь просит совсем кратко, оставь только:
+
+```text
+Коротко
+Файлы
+Проверка
+```
+
+## Таблица файлов
+
+Для 2+ файлов почти всегда используй таблицу:
+
+| Файл | Тип изменения | Смысл |
+|---|---|---|
+| `src/api/tauriCommands.ts` | API boundary | Добавлен typed wrapper для новой Tauri command |
+| `src-tauri/src/commands.rs` | Backend | Добавлена команда, которая вызывает уже существующую service-логику |
+
+Правила:
+
+- Не вставлять огромные таблицы на 30 строк. Группировать мелкие файлы.
+- В колонке `Смысл` писать человеческую причину, не только «обновлено».
+- Если файл опасный, отметить это: `security-sensitive`, `Windows/elevation`, `storage`, `routing`.
+
+## Как писать про риски
+
+Риск должен быть конкретным:
+
+Плохо:
+
+```text
+Есть некоторые риски.
+```
+
+Хорошо:
+
+```text
+Риск: я не запускал real Windows service flow, поэтому install/start/stop надо проверить на Windows 10/11 с UAC.
+```
+
+Плохо:
+
+```text
+Может быть несовместимость.
+```
+
+Хорошо:
+
+```text
+Риск: если у пользователя уже стоит чужая служба с похожим именем ProxiFyre, fuzzy detection может показать ее кандидатом. Управлять ей нельзя без проверки `PathName`.
+```
+
+## Как писать про проверки
+
+Разделяй выполненное и невыполненное:
+
+```text
+Проверено
+- `npm run build` — прошел.
+- Markdown-файлы открываются, битых путей не нашел.
+
+Не проверено
+- `cargo test` — не запускал, в среде нет Rust toolchain.
+- Windows service flow — не проверял, нужна Windows-машина с UAC.
+```
+
+Не объединять это в мутное «тесты частично пройдены». Машины и люди заслуживают хотя бы грамм конкретики.
+
+## Запрещенный стиль
+
+Не писать:
+
+- огромные абзацы без заголовков;
+- «магия», «оптимизировано», «улучшено» без конкретики;
+- внутренний дневник действий агента;
+- цепочки мыслей;
+- список всех строк diff;
+- рекламный тон;
+- уверенные заявления о непроверенных Windows/elevation сценариях;
+- «как вы и просили, я с радостью...» — репозиторий от этого лучше не станет.
+
+## Мини-шаблоны
+
+### Для bugfix
+
+```text
+Коротко
+- Исправил ...
+- Основной риск был ...
+- Проверка: ...
+
+Что изменилось по файлам
+| Файл | Что изменилось | Зачем |
+|---|---|---|
+
+Важные места
+- `file`: ...
+
+Проверено
+- ...
+
+Не проверено
+- ...
+```
+
+### Для ревью без правок
+
+```text
+Коротко
+- Самая важная проблема: ...
+- Второй приоритет: ...
+- Быстрый выигрыш: ...
+
+Что я смотрел
+- ...
+
+Проблемы по важности
+1. Critical/High: ...
+2. Medium: ...
+3. Low: ...
+
+Что бы я сделал первым
+- ...
+```
+
+### Для плана изменений
+
+```text
+Коротко
+- Цель: ...
+- Затронет: ...
+- Не трогаем: ...
+
+План по файлам
+| Файл/зона | Что сделать | Почему |
+|---|---|---|
+
+Порядок работ
+1. ...
+2. ...
+3. ...
+
+Проверка
+- ...
+```