249 lines
8.7 KiB
Markdown
249 lines
8.7 KiB
Markdown
# 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. ...
|
||
|
||
Проверка
|
||
- ...
|
||
```
|