Учебный гайд: Часть 14. Собственный процесс через навыки Qwen Code

Тема: Часть 14. Собственный процесс через навыки Qwen Code

Уровень сложности: Средний

Расчётное время изучения: 4-6 часов (теория + практика)

Предварительные требования: Базовое знание Qwen Code и работы с CLI-агентами

Понимание Git и ветвления

Опыт работы с Markdown

Знакомство с концепцией SDD (Specification-Driven Development)

Пройденные части 1-13 курса (особенно работа с QWEN.md)

Цели обучения: Создавать и настраивать навыки (skills) агента в Qwen Code для автоматизации повторяющихся процессов

Различать личные и проектные навыки, обосновывать выбор типа навыка для командной работы

Формулировать эффективные description в YAML-шапке SKILL.md для корректного автоматического обнаружения навыка

Внедрять правила эскалации, предотвращающие нежелательные автономные действия агента

Применять техники гигиены контекста для поддержания качества длительных сессий с агентом

Обзор: Эта часть курса посвящена автоматизации повторяющихся инженерных процессов через систему навыков (skills) Qwen Code. Вы научитесь превращать часто повторяемые запросы в структурированные, переиспользуемые навыки агента, создавать проектные и личные навыки, внедрять правила эскалации для безопасной работы агента и управлять контекстом длительных сессий. Основной фокус — на практическом применении: спецификация фичей в SDD-формате и ведение журнала изменений как примеры типовых навыков, которые ускоряют работу команды и стандартизируют инженерные практики.

Ключевые концепции: Навык агента (skill): Директория с файлом SKILL.md, содержащая описание конкретного процесса: когда и как агент должен его применять. Навык — это единица автоматизации повторяющихся запросов в Qwen Code. В отличие от слеш-команды, навык вызывается моделью автоматически или через /skills, описывая возможность, а не жёсткий интерфейс.

Личный навык: Навык, расположенный в ~/.qwen/skills/<name>/SKILL.md. Доступен только текущему пользователю на данной машине. Подходит для индивидуальных предпочтений и экспериментов, но не попадает в систему контроля версий.

Проектный навык: Навык, расположенный в .qwen/skills/<name>/SKILL.md внутри репозитория. Попадает в Git, становится частью инженерного процесса команды, обеспечивает консистентность между всеми разработчиками и агентами, работающими с проектом.

Yaml-шапка skill.md: Метаданные в формате YAML между маркерами --- в начале файла SKILL.md. Содержит обязательные поля name (без пробелов) и description (конкретное описание условий применения). Корректная шапка критична для обнаружения навыка агентом.

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

Деградация контекста (context rot): Пhenomenon ухудшения качества работы агента на длительных сессиях из-за накопления нерелевантного контекста. Старые решения из соседних задач случайно подтягиваются в текущую работу, снижая точность и релевантность выдачи.

Гигиена контекста: Совокупность практик управления контекстом агента: регулярное использование /clear между сменой ролей, ограничение длительности сессий, явное указание файлов через @file вместо передачи целых директорий, перезапуск с чтением QWEN.md при подозрении на путаницу.

Вспомогательные файлы навыка: Дополнительные ресурсы в директории навыка (templates/, примеры, сниппеты), которые SKILL.md может ссылать для расширения функциональности без раздувания основного файла. Шаблоны не копируются с комментариями в итоговые спецификации.

Agents.md: Межагентный стандарт правил в корне репозитория, дополняющий QWEN.md. Читается не только Qwen Code, но и другими совместимыми инструментами. Обеспечивает консистентность при параллельном использовании нескольких разных агентов в одном проекте.

Практические упражнения: Название: Создание базового навыка спецификации фичи

Проблема: В вашем проекте регулярно создаются SDD-спецификации новых фич по дорожной карте. Повторяющийся запрос: «Создай спецификацию для следующей фазы из roadmap.md». Необходимо автоматизировать этот процесс через навык агента. Создайте проектный навык feature-spec с корректной YAML-шапкой, процессом из 8 шагов, тремя выходными файлами (requirements.md, plan.md, validation.md) и ограничениями. Проверьте обнаружение через /skills.

Решение: 1. Создайте директорию: mkdir -p .qwen/skills/feature-spec

1. Создайте файл .qwen/skills/feature-spec/SKILL.md с содержимым:

--- name: feature-spec description: Создаёт новую SDD-спецификацию фичи из следующей незавершённой фазы дорожной карты. Используйте перед началом следующей фичи, написанием спецификации или подготовкой новой фазы перед реализацией. --- # Спецификация фичи ## Процесс

1. Прочитать specs/roadmap.md
2. Найти первую незавершённую фазу
3. Создать ветку phase-N-kebab-name
4. Задать человеку три группы вопросов: границы, решения, контекст
5. Прочитать specs/mission.md и specs/tech-stack.md
6. Создать specs/YYYY-MM-DD-feature-name/
7. Записать requirements.md, plan.md, validation.md
8. Не реализовывать код

## Файл requirements.md — границы, за границами, решения, контекст, открытые вопросы ## Файл plan.md — пронумерованные группы задач, каждая проверяется отдельно ## Файл validation.md — автоматические проверки, ручной проход, проверка отклонений, критерии готовности ## Ограничения: соблюдать tech-stack.md, не добавлять зависимости без одобрения, оставлять фазу пригодной для поставки, не редактировать несвязанные файлы

1. Перезапустите Qwen Code
2. Выполните /skills — убедитесь, что feature-spec отображается
3. Проверьте вызов: «Используй навык feature-spec, чтобы начать следующую фичу из дорожной карты. Код не реализуй»
4. Если навык не сработал, проверьте: путь к файлу, корректность YAML-шапки (--- в начале и конце), отсутствие пробелов в name, конкретность description, перезапуск агента

Сложность: beginner

Название: Расширение навыка вспомогательными шаблонами

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

Решение: 1. Создайте директорию templates внутри навыка: mkdir -p .qwen/skills/feature-spec/templates

1. Создайте .qwen/skills/feature-spec/templates/requirements.md с начальной структурой:

# Требования ## Границы <!-- Что входит в фичу --> ## За границами <!-- Что явно не входит --> ## Решения <!-- Принятые архитектурные решения --> ## Контекст <!-- Почему приняты именно такие решения --> ## Открытые вопросы <!-- Что требует уточнения -->

1. Аналогично создайте templates/plan.md и templates/validation.md
2. Обновите SKILL.md, добавив в процесс:

«Используй templates/requirements.md как начальную структуру. Не копируй комментарии шаблона в итоговые спецификации.»

1. Проверьте, что агент корректно использует шаблоны без переноса комментариев-инструкций в выходные файлы
2. Закоммитьте изменения: git add .qwen/skills/ && git commit -m "Add feature-spec skill with templates"

Сложность: intermediate

Название: Внедрение правил эскалации

Проблема: Агент в вашем проекте несколько раз принимал спорные решения самостоятельно: добавлял зависимости без согласования, изменял файлы вне границ спецификации, редактировал tech-stack.md. Необходимо формализовать правила эскалации в QWEN.md или навыке, чтобы агент обязательно останавливался и запрашивал подтверждение.

Решение: 1. Откройте или создайте QWEN.md в корне репозитория (или добавьте в существующий SKILL.md)

1. Добавьте раздел «Правила эскалации»:

Остановись и спроси человека, не действуй, в следующих случаях:

• если в спецификации фичи остаются разные интерпретации одного требования;
• если ты собираешься изменить файл вне границ текущей спецификации;
• если ты собираешься добавить новую зависимость, не указанную в tech-stack.md;
• если ты собираешься изменить tech-stack.md, mission.md или roadmap.md;
• если требуется выполнить миграцию, drop, delete или rm с нетривиальным радиусом;
• если ты не нашёл файл, на который ссылается пользователь;
• если результат не совпадает с фактом из validation.md, и факт не помечен как «отложен»;
• если запрос пользователя противоречит ранее принятым правилам QWEN.md.

В каждом таком случае выведи короткое объяснение, что именно неоднозначно, и предложи 2–3 конкретных варианта на выбор. Не выбирай за человека.

1. Протестируйте на сценарии: попросите агента добавить библиотеку, отсутствующую в tech-stack.md — убедитесь, что он остановился с вариантами
2. Дополнительно: изучьте хук Stop из части 17 для программной проверки соблюдения правил

Сложность: intermediate

Название: Создание навыка журнала изменений

Проблема: Команда тратит время на ручное обновление CHANGELOG.md перед слиянием фич. История коммитов разрозненная, форматирование непоследовательное. Создайте навык changelog, который автоматизирует процесс на основе git log и git diff.

Решение: 1. Создайте директорию: mkdir -p .qwen/skills/changelog

1. Создайте .qwen/skills/changelog/SKILL.md:

--- name: changelog description: Обновляет CHANGELOG.md по истории Git и изменениям текущей ветки перед слиянием ветки фичи. --- # Журнал изменений

1. Посмотреть git log и git diff относительно main
2. Создать или обновить CHANGELOG.md
3. Использовать заголовки с датами
4. Писать краткие пункты, понятные заинтересованным людям
5. Не включать шумные внутренние детали
6. Перезапустите Qwen Code, проверьте через /skills
7. Создайте тестовую ветку с несколькими коммитами, попросите агент использовать навык changelog
8. Проверьте результат: даты в заголовках, отсутствие внутренних деталей вроде «рефакторинг функции X», наличие понятных описаний для пользователей
9. Используйте навык перед реальным слиянием в main

Сложность: beginner

Название: Диагностика и устранение проблем с обнаружением навыка

Проблема: Вы создали навык, но агент не видит его в /skills или не применяет при явном запросе. Систематически диагностируйте и устраните проблему.

Решение: 1. Проверьте путь: файл должен быть в .qwen/skills/<name>/SKILL.md (проектный) или ~/.qwen/skills/<name>/SKILL.md (личный)

1. Проверьте YAML-шапку:

• Начинается и заканчивается точными маркерами --- (без пробелов, без BOM)
• Поле name без пробелов, только латиница, дефисы, подчёркивания
• Поле description конкретно описывает условия применения, не общие фразы вроде «полезный навык»

1. Проверьте права доступа: файл должен быть читаем
2. Проверьте перезапуск: Qwen Code кэширует навыки при старте, изменения требуют перезапуска
3. Проверьте синтаксис Markdown: сломанные заголовки или таблицы могут мешать парсингу
4. Проверьте отсутствие конфликтов имён: два навыка с одинаковым name недопустимы
5. Если всё корректно — проверьте версию Qwen Code, возможно, требуется обновление
6. Временное решение: используйте явный импорт через /load или эквивалентную команду вашей версии

Сложность: intermediate

Название: Оптимизация длительной сессии с гигиеной контекста

Проблема: Вы работаете с агентом над сложной задачей уже 90 минут. Замечены признаки деградации контекста: агент ссылается на решения из предыдущей задачи, предлагает нерелевантные файлы, путает границы текущей фичи. Примените техники гигиены контекста для восстановления качества работы.

Решение: 1. Выполните /clear для полной очистки контекста сессии

1. Перечитайте QWEN.md с нуля: «Прочитай QWEN.md и следуй его правилам»
2. Перечитайте активную спецификацию: «Прочитай specs/YYYY-MM-DD-feature-name/requirements.md и все связанные файлы»
3. Явно укажите нужные файлы через @file вместо «найди сам» или передачи целых директорий
4. Разбейте оставшуюся работу на подзадачи по 15-20 минут каждая
5. Между подзадачами используйте /clear и перечитывайте только релевантный контекст
6. Если включено автоматическое сжатие контекста — помните, что оно сохраняет резюме, которое может содержать ложные подсказки; /clean предпочтительнее для смены роли
7. Документируйте промежуточные результаты в файлах проекта, не полагайтесь на память сессии

Сложность: advanced

Кейсы: Название: Внедрение SDD-навыков в финтех-стартапе: от хаоса к стандартизации

Сценарий: Финтех-стартап с 12 разработчиками и 3 продуктовыми командами. Каждая команда использовала разный формат спецификаций фич: одни писали в Google Docs, другие — в Notion, третье — вообще обходились устными договорённостями. При ротации разработчиков между командами требовалось 2-3 дня на адаптацию к новому формату. Введение Qwen Code не решило проблему: агент генерировал спецификации в том формате, который видел последним в контексте, что приводило к фрагментации.

Задача: Необходимо было: (1) стандартизировать формат SDD-спецификаций для всех команд, (2) сделать этот формат автоматически применяемым агентом без дополнительных инструкций, (3) обеспечить версионирование и эволюцию формата, (4) минимизировать время адаптации при ротации.

Решение: Техлид создал проектный навык feature-spec в корневом репозитории компании (mono-repo с 40+ сервисами). Навык включал: строгий процесс из 8 шагов, три выходных файла с детальными требованиями к содержимому, шаблоны в поддиректории templates/, и правила эскалации, запрещающие агенту отклоняться от tech-stack.md. Дополнительно был создан навык changelog для единообразного ведения журналов изменений. Для межкомандной консистентности в корень mono-repo добавили AGENTS.md с базовыми правилами, читаемыми всеми инструментами команды.

Результат: Через 3 недели после внедрения: время создания спецификации сократилось с 4 часов до 45 минут (включая время на уточняющие вопросы агента); адаптация при ротации сократилась до 2 часов (достаточно прочитать SKILL.md); 94% спецификаций принимались без доработки на ревью (против 60% ранее); единый CHANGELOG позволил автоматизировать генерацию release notes; команда выявила и исправила 7 случаев, когда агент пытался добавить неодобренные зависимости, благодаря правилам эскалации.

Извлечённые уроки: Проектные навыки в корневом репозитории эффективнее личных навыков отдельных разработчиков для масштабирования практик

Правила эскалации — не избыточная бюрократия, а экономия: 7 предотвращённых инцидентов с зависимостями сэкономили неделю работы на откат изменений

Шаблоны в templates/ ускоряют работу агента и повышают консистентность, но требуют явного правила «не копируй комментарии»

AGENTS.md необходим при использовании нескольких инструментов (Qwen Code, Cursor, собственные скрипты) — предотвращает дивергенцию правил

Связанные концепции: Проектный навык

Правила эскалации

Вспомогательные файлы навыка

AGENTS.md

Гигиена контекста

Название: Спасение от деградации контекста в агентной сессии длительного рефакторинга

Сценарий: Команда из 4 разработчиков проводила масштабный рефакторинг ядра платёжной системы. Один разработчик использовал Qwen Code для последовательной обработки 15 связанных сервисов в одной сессии длительностью 3 часа. Начиная с 8-го сервиса, агент стал предлагать решения, характерные для 3-го сервиса (устаревшая архитектура, уже отменённая), и пытался изменить tech-stack.md, «оптимизируя» под паттерн, который команда сознательно отказалась.

Задача: Диагностировать и остановить деградацию контекста без потери прогресса; понять, почему автоматическое сжатие контекста не спасло; восстановить корректную работу агента; предотвратить повторение в будущих длительных сессиях.

Решение: Разработчик применил экстренную гигиену контекста: /clear, перечитывание QWEN.md и активной спецификации, явное указание @file для конкретного сервиса вместо «обработай оставшиеся». Для оставшихся 7 сервисов разбил работу на отдельные сессии по 20 минут каждая с обязательным /clear между ними. Промежуточные результаты фиксировались в файлах проекта, а не в памяти сессии. Выявлено, что автоматическое сжатие сохранило «резюме» устаревших решений как «важный контекст», что и стало источником ложных подсказок.

Результат: Последние 7 сервисов обработаны корректно, без отклонений от утверждённой архитектуры. Разработчик задокументировал инцидент во внутренней базе знаний. Команда ввела правило: сессии агента ограничены 45 минутами, принудительный /clear и перечитывание QWEN.md между этапами. В последующих рефакторингах подобных инцидентов не наблюдалось.

Извлечённые уроки: Автоматическое сжатие контекста помогает для длинной непрерывной задачи, но вредит при последовательных разных задачах — резюме становится источником ложных подсказок

/clear гарантирует чистый старт, но требует дисциплины документирования промежуточных результатов в файлах

Ограничение длительности сессии (45 минут) — простое и эффективное правило, легко проверяемое в ретроспективе

Явное указание файлов через @file критично после /clear: агент не «догадается» о контексте из предыдущей сессии

Связанные концепции: Деградация контекста

Гигиена контекста

Правила эскалации

Проектный навык

Советы по изучению: Начните с создания личного навыка в ~/.qwen/skills/, отладьте его на своём проекте, затем перенесите в проектный — так вы избежете коммитов нерабочих версий в Git

Проверяйте YAML-шапку валидатором (например, yamllint) — невидимые ошибки в форматировании часто приводят к необнаружению навыка

Ведите «дневник эскалации»: записывайте случаи, когда агент должен был остановиться, но не остановился — по ним дополняйте правила

Используйте технику «параллельного сравнения»: создайте один и тот же навык двумя способами (через SKILL.md и через слеш-команду), протестируйте на одной задаче, зафиксируйте различия в поведении агента

Практикуйте «стресс-тест гигиены»: намеренно создавайте длинную сессию с переключением ролей, чтобы научиться распознавать ранние признаки деградации контекста

Создайте «навык для навыков» — мета-навык, который помогает создавать новые навыки по шаблону, с корректной YAML-шапкой и структурой

Изучайте чужие проектные навыки в open-source репозиториях — сообщество Qwen Code активно делится best practices

Комбинируйте визуальное, аудиальное и кинестетическое обучение: читайте SKILL.md вслух для проверки ясности инструкций, рисуйте блок-схемы процессов, пишите навыки от руки перед цифровым вводом для лучшего запоминания структуры

Дополнительные ресурсы: Официальная документация qwen code: https://github.com/QwenLM/Qwen-Code (актуальные примеры навыков и обновления формата)

Часть 15 курса — agents.md и межагентная совместимость: part-15-agent-replaceability.md (в репозитории курса)

Часть 17 курса — хук stop для программной проверки эскалации: part-17-stop-hooks.md (в репозитории курса)

Часть 19 курса — управляемая память агента на sqlite: part-19-agent-memory-sqlite.md (в репозитории курса)

Yaml specification 1.2: https://yaml.org/spec/1.2.2/ (для глубокого понимания требований к шапке SKILL.md)

Примеры проектных навыков от сообщества: https://github.com/search?q=path%3A.qwen%2Fskills+SKILL.md&type=code (поиск публичных репозиториев)

Исследование context rot в llm-агентах: https://arxiv.org/abs/2404.06910 (академический анализ деградации контекста)

Интерактивный тренажёр yaml-шапок: https://www.yamllint.com/ (проверка синтаксиса метаданных навыков)

Резюме: Ключевые выводы части 14: (1) Повторяющиеся запросы следует автоматизировать через навыки агента — это экономит время и стандартизирует процессы. (2) Проектные навыки (.qwen/skills/) предпочтительнее личных (~/.qwen/skills/) для командной работы, так как версионируются в Git и доступны всем участникам. (3) Корректная YAML-шапка с конкретным description критична для автоматического обнаружения навыка агентом. (4) Правила эскалации — обязательный контракт безопасности, предотвращающий нежелательные автономные действия агента при неопределённости. (5) Гигиена контекста (/clear, ограничение длительности сессий, явное указание файлов) не менее важна, чем качество навыков — деградация контекста разрушает эффективность даже идеально написанных инструкций. (6) Навыки и слеш-команды дополняют друг друга: навыки — для автоматического применения, команды — для явного вызова. (7) Вспомогательные файлы (templates/) позволяют масштабировать сложные навыки без раздувания SKILL.md.