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

Skill: Communication Reporting

Когда использовать

Используй этот skill в каждом ответе пользователю после анализа, правки кода, ревью, аудита, планирования рефакторинга или подготовки PR. Особенно если задача затрагивает несколько файлов, backend/frontend boundary, security, Windows services или UI.

Цель

Писать так, чтобы человек с опытом разработки быстро понял суть без чтения технической простыни. Не упрощать до детского сада, но объяснять по-человечески: что поменялось, где, зачем, как проверить, где риск.

Пользователь не обязан продираться через внутренний монолог агента и каталог аббревиатур. У него есть жизнь, возможно даже вне репозитория, страшно представить.

Базовый формат ответа

Для нетривиальных изменений используй такую структуру:

Коротко
- 2-4 пункта: главный результат, важный риск, что проверить.

Что изменилось по файлам
| Файл | Что изменилось | Зачем |
|---|---|---|
| src/... | Кратко | Человеческая причина |

Важные места
- 3-6 конкретных мест: файл + функция/секция + смысл.

Как проверить
- Команды или ручные шаги.

Что не проверено
- Честно и коротко.

Риски
- Только реальные риски, не философия.

Если изменение маленькое, можно сократить до:

Коротко: ...

Файлы:
- `path`: что и зачем.

Проверка: ...

Правила ясности

• Сначала вывод, потом детали.
• Не писать длиннее, чем нужно для решения задачи.
• Не перечислять каждую строку diff. Указывать только смысловые изменения.
• Всегда называть конкретные файлы.
• Для сложных мест указывать функцию, модуль или секцию, если это помогает найти код.
• Если используешь термин, рядом дать короткое человеческое объяснение.
• Не использовать аббревиатуры без расшифровки при первом упоминании, кроме очевидных: UI, JSON, URL, API.
• Не писать «улучшена архитектура» без объяснения, что именно стало проще или безопаснее.
• Не писать «всё готово», если часть проверок не запускалась.
• Не скрывать ошибки окружения. Если cargo или Windows недоступны, так и сказать.

Как объяснять технические изменения

Плохо:

Refactored orchestration layer and extracted imperative use-case side effects into composable boundaries.

Хорошо:

Вынес запуск service-команд из большого `commands.rs` в отдельный модуль. Теперь Tauri command только принимает запрос и возвращает ошибку, а вся Windows-логика лежит отдельно. Так проще тестировать и меньше шанс сломать соседние команды.

Плохо:

Added CSP hardening.

Хорошо:

Включил CSP в `src-tauri/tauri.conf.json`. Это ограничивает, какие скрипты/ресурсы может загрузить webview, и снижает ущерб, если в UI когда-нибудь появится XSS.

Уровни детализации

По умолчанию — средний уровень:

• достаточно конкретно, чтобы разработчик понял diff;
• без пересказа каждой строки;
• без внутренних рассуждений агента;
• без длинной теории.

Если пользователь просит глубже, добавь раздел:

Детальнее
- ...

Если пользователь просит совсем кратко, оставь только:

Коротко
Файлы
Проверка

Таблица файлов

Для 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.

Как писать про риски

Риск должен быть конкретным:

Плохо:

Есть некоторые риски.

Хорошо:

Риск: я не запускал real Windows service flow, поэтому install/start/stop надо проверить на Windows 10/11 с UAC.

Плохо:

Может быть несовместимость.

Хорошо:

Риск: если у пользователя уже стоит чужая служба с похожим именем ProxiFyre, fuzzy detection может показать ее кандидатом. Управлять ей нельзя без проверки `PathName`.

Как писать про проверки

Разделяй выполненное и невыполненное:

Проверено
- `npm run build` — прошел.
- Markdown-файлы открываются, битых путей не нашел.

Не проверено
- `cargo test` — не запускал, в среде нет Rust toolchain.
- Windows service flow — не проверял, нужна Windows-машина с UAC.

Не объединять это в мутное «тесты частично пройдены». Машины и люди заслуживают хотя бы грамм конкретики.

Запрещенный стиль

Не писать:

• огромные абзацы без заголовков;
• «магия», «оптимизировано», «улучшено» без конкретики;
• внутренний дневник действий агента;
• цепочки мыслей;
• список всех строк diff;
• рекламный тон;
• уверенные заявления о непроверенных Windows/elevation сценариях;
• «как вы и просили, я с радостью...» — репозиторий от этого лучше не станет.

Мини-шаблоны

Для bugfix

Коротко
- Исправил ...
- Основной риск был ...
- Проверка: ...

Что изменилось по файлам
| Файл | Что изменилось | Зачем |
|---|---|---|

Важные места
- `file`: ...

Проверено
- ...

Не проверено
- ...

Для ревью без правок

Коротко
- Самая важная проблема: ...
- Второй приоритет: ...
- Быстрый выигрыш: ...

Что я смотрел
- ...

Проблемы по важности
1. Critical/High: ...
2. Medium: ...
3. Low: ...

Что бы я сделал первым
- ...

Для плана изменений

Коротко
- Цель: ...
- Затронет: ...
- Не трогаем: ...

План по файлам
| Файл/зона | Что сделать | Почему |
|---|---|---|

Порядок работ
1. ...
2. ...
3. ...

Проверка
- ...