QFE

Персональные занятия

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

Провожу сейчас такие занятия с двумя людьми. Но если вам тоже интересен такой формат, то напишите мне, пожалуйста. Я с удовольствием вам помогу :)

Пишите в личку — @elenashliaga.

Проверка работы агента

Агент выполнил поручение — например, переписал инструкцию. Дальше начинается ваша часть работы: проверить результат. Разберём, зачем это делать и как.

🔍 Агент может ошибаться, поэтому его работу проверяют.

Агент похож на стажёра: старательный, но пока без опыта и чувства контекста. Он может удалить нужный раздел, перепутать версии продукта или уверенно вставить в инструкцию неверную команду. Поэтому результат проверяйте как работу стажёра: доверяйте, но сверяйтесь.

🔍 Diff покажет, что именно изменилось.

Diff, difference (разница) — это подсвеченные правки: разница между файлом «до» и «после». Представьте правки редактора в совместном документе: добавленное подсвечено одним цветом, удалённое — другим. Вы читаете их и принимаете выборочно. Так же просматривают diff, когда агент поправил Markdown-файлы в git.

🔍 Просите агента объяснить, что он изменил и почему.

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

🔍 Не получилось — останавливайте и переформулируйте.

Если агент портит документ снова и снова, не правьте за ним вслепую. Остановите его и уточните формулировку задачи. А большое поручение вроде «перепиши всю документацию» дробите на разделы: их проще проверять по одному, и агент не запутается.

Как вы проверяете работу агента? Поделитесь в комментариях. ✨

Инструменты агента

Чтобы агент работал с вашей документацией, ему нужны инструменты — возможности, через которые он действует самостоятельно. Вот три главных.

🛠 Правка файлов — агент сам вносит правки в ваш .md-файл.

Агент открывает документ в формате Markdown (язык разметки документации) и переписывает нужные места: обновляет устаревший раздел, чинит оформление таблицы, дописывает пропущенный абзац. Это как редактор, который вносит правки прямо в документ, а не присылает их письмом. Вам остаётся проверить результат.

🛠 Запуск команд — агент выполняет действия в терминале (командной строке).

Например, собирает документацию или показывает историю изменений файла в git. Перед опасным — скажем, удалить файл — агент обычно спрашивает разрешение и показывает команду. Это исполнитель поручения, который согласует с вами важные шаги, а мелочи берёт на себя.

🛠 Поиск по проекту — агент сам находит нужные файлы и места в документации.

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

Инструменты превращают агента из собеседника в помощника, который делает работу руками. Какой инструмент вы бы поручили агенту первым? ✨

Как формулировать задачу агенту

Агент выполнит почти любую просьбу. Но качество результата зависит от того, как вы её сформулировали.

✍️ Чем точнее задача, тем меньше кругов правок.

Промпт — это текстовое задание для агента. Он работает как техническое задание для стажёра-техписателя: по расплывчатой просьбе стажёр угадывает, что вы имели в виду, а по точной сразу делает нужное.

✍️ Хороший промпт строится из четырёх частей.

Сначала назовите контекст — что за документ и для кого он. Затем задачу — что именно сделать. После этого ограничения — чего не менять и какой стиль соблюдать. И наконец формат результата — как оформить ответ.

✍️ Сравните плохой промпт и хороший.

❌ «Улучши документацию.»

✅ «Это инструкция по установке для новичков (контекст). Перепиши раздел „Установка“ простым языком (задача). Не меняй смысл и команды, сохрани разметку Markdown, стиль по doc-style.md (ограничения). Ответ — готовый текст раздела (формат).»

Вторая просьба длиннее, зато агент вернёт текст, готовый для документа.

Какую часть формулы вы чаще всего забываете? ✨

Использование Copilot: кейсы и примеры промптов

Copilot — ИИ-помощник, который работает в редакторе кода и понимает задачи, описанные обычным языком. Он как коллега, который берёт на себя рутину, но результат почти всегда требует вашей проверки. Для техписателя это особенно удобно, когда документация лежит в git (системе контроля версий) рядом с кодом — помощник видит файлы проекта и может их создавать, проверять и редактировать.

Задачу для Copilot называют промптом. Хороший промпт короткий, но самодостаточный: в нём есть контекст и ожидаемый результат. Разберём четыре кейса — промпты можно копировать и подставлять свои файлы.

📝 Кейс 1. Завести файл со стилем документации.

Сначала опишите правила стиля в отдельном файле — тогда Copilot будет придерживаться их в каждой задаче, а не угадывать стиль заново. Промпт:


Создай файл doc-style.md — правила стиля нашей документации: обращение на «вы», простые слова без канцелярита, первое упоминание термина сразу поясняем. Оформи чек-листом.


Внутри может получиться, например, такой чек-лист:


- Обращаемся к читателю на «вы».
- Пишем «используйте» вместо «осуществляйте».
- Новый термин объясняем при первом упоминании.


📝 Кейс 2. Проверить существующую документацию.

Канцелярит — это бюрократический язык: «осуществлять», «в рамках». Искать такие обороты и длинные абзацы вручную утомительно, поэтому поручите поиск Copilot, а решение об исправлениях оставьте себе. Промпт:


Проверь install.md по правилам из doc-style.md: найди канцелярит, длинные абзацы и непояснённые термины. Покажи проблемы списком с цитатами.


📝 Кейс 3. Написать новую документацию.

Черновые заметки есть у каждого техписателя, но собирать из них ровный текст — долгая работа. Copilot напишет раздел в вашем стиле, а вы отредактируете результат как текст коллеги. Промпт:


Напиши раздел «Установка» для инструкции новичка: шаги нумерованным списком, один шаг — одно действие, стиль по doc-style.md. Вот мои черновые заметки: …


📝 Кейс 4. Собрать changelog из истории изменений.

Changelog — список изменений продукта для пользователей. История уже хранится в git — по одному коммиту на каждую порцию правок, — и Copilot может переписать её человеческим языком. Промпт:


Посмотри последние 10 коммитов и собери черновик changelog для пользователей: что нового, что изменилось, что исправлено. Без технического жаргона.


🌼 Упражнение

Выберите кейс, который ближе к вашей работе, и попробуйте его на своём проекте.

1. Скопируйте промпт и подставьте название своего файла.
2. Отправьте промпт Copilot.
3. Прочитайте результат и внесите свои правки.

Получилось? Если нет, то задавайте вопросы в комментариях. 💖