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

Урок 1 из 5 в модуле «Часть 14. Собственный процесс через навыки Qwen Code»

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

Источник

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

Когда вы несколько раз повторили запрос для спецификации фичи, его пора автоматизировать. В Qwen Code для этого подходят навыки агента. Навык — это директория с SKILL.md, где описано, когда и как агент должен применять конкретный процесс. Навык может быть личным или проектным.

Личный навык:

~/.qwen/skills/feature-spec/SKILL.md

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

.qwen/skills/feature-spec/SKILL.md

Для команды лучше проектный навык: он попадает в Git и становится частью инженерного процесса.

Если ваш проект параллельно используют несколько разных агентов, навыки можно дополнить файлом AGENTS.md в корне репозитория — это межагентный стандарт правил, который читает не только Qwen Code, но и другие совместимые инструменты. Подробнее о роли AGENTS.md рядом с QWEN.md — в части 15.

Создание навыка

mkdir -p .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

Включить автоматические проверки, ручной проход, проверку отклонений и критерии готовности.

## Ограничения

- Соблюдать specs/tech-stack.md.
- Не добавлять зависимости без явного одобрения.
- Оставлять фазу пригодной для самостоятельной поставки.
- Не редактировать несвязанные файлы.

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

Запустите Qwen Code:

qwen

Посмотрите список:

/skills

Попросите явно:

Используй навык feature-spec, чтобы начать следующую фичу из дорожной карты.
Код не реализуй.

Если навык не сработал, проверьте:

файл лежит в .qwen/skills/feature-spec/SKILL.md;
YAML-шапка начинается и заканчивается ---;
name без пробелов;
description конкретно говорит, когда применять навык;
Qwen Code был перезапущен после создания навыка.

Навык против слеш-команды

Навык вызывается моделью или через /skills; он описывает возможность. Слеш-команду пользователь вызывает явно. Для спецификации фичи в SDD удобнее навык: агент может сам понять, что он нужен, когда пользователь пишет «начни следующую фичу».

Если вашей команде нужен жёсткий интерфейс, можно дополнительно сделать пользовательскую команду, но для начала достаточно навыка.

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

Когда процесс растёт, вынесите шаблоны:

.qwen/skills/feature-spec/
  SKILL.md
  templates/
    requirements.md
    plan.md
    validation.md

В SKILL.md:

Используй templates/requirements.md как начальную структуру.

Не копируй комментарии шаблона в итоговые спецификации.

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

Второй полезный навык:

.qwen/skills/changelog/SKILL.md

Пример:

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

# Журнал изменений

1. Посмотреть git log и git diff относительно main.
2. Создать или обновить CHANGELOG.md.
3. Использовать заголовки с датами.
4. Писать краткие пункты, понятные заинтересованным людям.
5. Не включать шумные внутренние детали.

Правила эскалации: когда агент обязан остановиться

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

Чтобы агент не угадывал, удобно вынести в QWEN.md (или в навык) явные правила эскалации:

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

- если в спецификации фичи остаются разные интерпретации одного требования;

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

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

Это не «вежливость». Это контракт: агент обязан вернуть контроль человеку, как только встречает условие из списка. Те же правила можно дополнительно подкрепить хуком Stop (см. часть 17), который не даст агенту завершиться, пока он молча принял спорное решение.

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

Каждая длинная сессия имеет цену в двух смыслах: токены и качество. Чем дольше идёт сессия, тем больше у агента старого контекста и тем легче ему случайно подтянуть в текущую задачу решения из соседней. На длинных сессиях наблюдается явление, которое в исследовательских работах называют «деградацией контекста» (context rot): сфокусированный короткий ввод даёт лучший результат, чем большой нерелевантный. Тот же принцип применим и к управляемой памяти агента — подробнее в части 19.

Несколько простых правил гигиены:

запускайте /clear между ролями (интервью → реализация → проверка → перепланирование);
держите одну сессию ограниченной по времени; если сессия длится больше часа, скорее всего, пора закрыть её и начать чистую;
не подсовывайте агенту папки целиком, если можно подсунуть конкретные файлы;
для длинных задач используйте @file явно, а не «он сам найдёт»;
при подозрении на путаницу — /clear, чтение QWEN.md и активной спецификации с нуля.

Если в Qwen Code включена опция автоматического сжатия контекста, она помогает, но не заменяет /clear. Сжатие сохраняет резюме истории — оно полезно для длинной непрерывной задачи, но именно резюме часто становится источником ложных подсказок в следующей задаче. /clear гарантирует, что в новой роли агент работает только с тем, что записано в репозитории.