# Часть 14. Собственный процесс через навыки Qwen Code Когда вы несколько раз повторили запрос для спецификации фичи, его пора автоматизировать. В Qwen Code для этого подходят навыки агента. Навык — это директория с `SKILL.md`, где описано, когда и как агент должен применять конкретный процесс. Навык может быть личным или проектным. Личный навык: ```text ~/.qwen/skills/feature-spec/SKILL.md ``` Проектный навык: ```text .qwen/skills/feature-spec/SKILL.md ``` Для команды лучше проектный навык: он попадает в Git и становится частью инженерного процесса. Если ваш проект параллельно используют несколько разных агентов, навыки можно дополнить файлом `AGENTS.md` в корне репозитория — это межагентный стандарт правил, который читает не только Qwen Code, но и другие совместимые инструменты. Подробнее о роли `AGENTS.md` рядом с `QWEN.md` — в [части 15](part-15-agent-replaceability.md). ## Создание навыка ```bash mkdir -p .qwen/skills/feature-spec ``` `SKILL.md`: ```markdown --- 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: ```bash qwen ``` Посмотрите список: ```text /skills ``` Попросите явно: ```text Используй навык feature-spec, чтобы начать следующую фичу из дорожной карты. Код не реализуй. ``` Если навык не сработал, проверьте: - файл лежит в `.qwen/skills/feature-spec/SKILL.md`; - YAML-шапка начинается и заканчивается `---`; - `name` без пробелов; - `description` конкретно говорит, когда применять навык; - Qwen Code был перезапущен после создания навыка. ## Навык против слеш-команды Навык вызывается моделью или через `/skills`; он описывает возможность. Слеш-команду пользователь вызывает явно. Для спецификации фичи в SDD удобнее навык: агент может сам понять, что он нужен, когда пользователь пишет «начни следующую фичу». Если вашей команде нужен жёсткий интерфейс, можно дополнительно сделать пользовательскую команду, но для начала достаточно навыка. ## Вспомогательные файлы Когда процесс растёт, вынесите шаблоны: ```text .qwen/skills/feature-spec/ SKILL.md templates/ requirements.md plan.md validation.md ``` В `SKILL.md`: ```markdown Используй templates/requirements.md как начальную структуру. Не копируй комментарии шаблона в итоговые спецификации. ``` ## Навык для журнала изменений Второй полезный навык: ```text .qwen/skills/changelog/SKILL.md ``` Пример: ```markdown --- name: changelog description: Обновляет CHANGELOG.md по истории Git и изменениям текущей ветки перед слиянием ветки фичи. --- # Журнал изменений 1. Посмотреть git log и git diff относительно main. 2. Создать или обновить CHANGELOG.md. 3. Использовать заголовки с датами. 4. Писать краткие пункты, понятные заинтересованным людям. 5. Не включать шумные внутренние детали. ``` ## Правила эскалации: когда агент обязан остановиться Хороший агент отличается от плохого не тем, что он умнее, а тем, что он знает, когда остановиться и спросить. По умолчанию большинство CLI-агентов стремятся завершить задачу любой ценой: если контекста не хватает, они угадывают. Это полезное свойство для коротких задач и плохое — для работы по SDD. Чтобы агент не угадывал, удобно вынести в `QWEN.md` (или в навык) явные правила эскалации: ```text Остановись и спроси человека, не действуй, в следующих случаях: - если в спецификации фичи остаются разные интерпретации одного требования; - если ты собираешься изменить файл вне границ текущей спецификации; - если ты собираешься добавить новую зависимость, не указанную в tech-stack.md; - если ты собираешься изменить tech-stack.md, mission.md или roadmap.md; - если требуется выполнить миграцию, drop, delete или rm с нетривиальным радиусом; - если ты не нашёл файл, на который ссылается пользователь; - если результат не совпадает с фактом из validation.md, и факт не помечен как «отложен»; - если запрос пользователя противоречит ранее принятым правилам QWEN.md. В каждом таком случае выведи короткое объяснение, что именно неоднозначно, и предложи 2–3 конкретных варианта на выбор. Не выбирай за человека. ``` Это не «вежливость». Это контракт: агент обязан вернуть контроль человеку, как только встречает условие из списка. Те же правила можно дополнительно подкрепить хуком `Stop` (см. часть 17), который не даст агенту завершиться, пока он молча принял спорное решение. ## Гигиена контекста и стоимости Каждая длинная сессия имеет цену в двух смыслах: токены и качество. Чем дольше идёт сессия, тем больше у агента старого контекста и тем легче ему случайно подтянуть в текущую задачу решения из соседней. На длинных сессиях наблюдается явление, которое в исследовательских работах называют «деградацией контекста» (`context rot`): сфокусированный короткий ввод даёт лучший результат, чем большой нерелевантный. Тот же принцип применим и к управляемой памяти агента — подробнее в [части 19](part-19-agent-memory-sqlite.md). Несколько простых правил гигиены: - запускайте `/clear` между ролями (интервью → реализация → проверка → перепланирование); - держите одну сессию ограниченной по времени; если сессия длится больше часа, скорее всего, пора закрыть её и начать чистую; - не подсовывайте агенту папки целиком, если можно подсунуть конкретные файлы; - для длинных задач используйте `@file` явно, а не «он сам найдёт»; - при подозрении на путаницу — `/clear`, чтение `QWEN.md` и активной спецификации с нуля. Если в Qwen Code включена опция автоматического сжатия контекста, она помогает, но не заменяет `/clear`. Сжатие сохраняет резюме истории — оно полезно для длинной непрерывной задачи, но именно резюме часто становится источником ложных подсказок в следующей задаче. `/clear` гарантирует, что в новой роли агент работает только с тем, что записано в репозитории. ## Гигиена контекстного окна Сжатие истории и `/clear` управляют тем, что накопилось за сессию. Но есть второй источник расхода окна, про который часто забывают: подключённые инструменты и MCP. Каждый активный инструмент добавляет своё описание и схему параметров в системный промпт — ещё до того, как вы напишете первый запрос. Чем больше инструментов включено, тем меньше окна остаётся под собственно работу. Правило простое: держите много MCP и инструментов в конфиге, но активируйте мало одновременно. Практический ориентир — меньше десяти включённых MCP и меньше восьмидесяти активных инструментов на проект. Эффект перегруза легко недооценить. Окно в ~200k токенов при избытке включённых инструментов может фактически сжаться до ~70k полезных, а качество рассуждений заметно деградирует — модель тратит внимание на разбор десятков описаний вместо задачи. Цифры «200k → 70k» здесь — иллюстрация порядка величины, а не точный закон: реальная потеря зависит от числа инструментов и размера их схем. Практика для Qwen Code: - посмотрите, какие MCP подключены сейчас — через `qwen /mcp` или аналогичную команду списка MCP; - отключите неиспользуемые в `.qwen/settings.json` либо в `.mcp.json` репозитория, оставив включёнными только нужные текущему проекту; - держите в конфиге широкий набор, но включайте под конкретный проект небольшое подмножество. Этот приём пришёл из экосистемы Claude Code, но он переносим: суть не в конкретной команде, а в том, что описание каждого инструмента занимает место в системном промпте. Автор гайда «Everything Claude Code» держит 14 MCP в конфиге и включает лишь ~5–6 на проект. Грубая иллюстрация зависимости (числа условны, для порядка величины): | Включённых инструментов | Примерный полезный контекст | Качество рассуждений | | ----------------------- | --------------------------- | -------------------- | | < 30 | близко к полному окну | стабильное | | ~80 | заметно меньше окна | приемлемое | | сильно > 80 | ~треть окна | деградирует | Правило «< 80 активных инструментов» — это не магический порог, а граница, за которой стоит остановиться и спросить себя, всё ли подключённое реально нужно текущей задаче. ## Codemaps: навигация без траты контекста Когда агенту нужно понять незнакомую кодовую базу, он по умолчанию «исследует» её: открывает файлы, читает их целиком, строит картину с нуля. Это дорого по контексту — особенно на больших проектах, где половина окна уходит на exploration ещё до первой полезной правки. Codemap снимает эту проблему. Это компактная карта кодовой базы: ключевые модули, точки входа, важные связи между ними. Агент читает карту вместо того, чтобы заново обходить дерево файлов. Карта стоит несколько сотен токенов и заменяет тысячи, потраченных на чтение исходников. Codemap удобно вынести в навык как вспомогательный файл рядом с `SKILL.md`: ```text .qwen/skills/feature-spec/ SKILL.md codemap.md ``` Пример `codemap.md`: ```markdown # Карта кодовой базы ## Точки входа - src/main.py — запуск приложения, разбор аргументов - src/api/routes.py — HTTP-маршруты ## Ключевые модули - src/core/ — доменная логика, не зависит от фреймворка - src/adapters/ — внешние интеграции (БД, очереди) - src/config/ — загрузка настроек из .env и settings ## Связи - routes.py вызывает core/, никогда не обращается к adapters/ напрямую - adapters/ подключаются через интерфейсы из core/ports.py ``` В `SKILL.md` достаточно сослаться на карту: ```markdown Перед исследованием прочитай codemap.md. Открывай конкретные файлы из карты, а не обходи дерево целиком. Если карта устарела относительно кода, остановись и сообщи об этом. ``` Карту полезно держать в Git и обновлять вместе со структурой проекта. Устаревший codemap опаснее отсутствующего: он уверенно направляет агента не туда. Поэтому в навыке стоит явно требовать сверки карты с фактическим деревом. ## Команды и навыки: что переживёт время Раздел «Навык против слеш-команды» выше описывает выбор с точки зрения вызова: навык агент может подобрать сам, команду пользователь вызывает явно. Есть и второй угол зрения — какой слой переживёт время. Слой команд удобен и привычен, но по своей роли это в первую очередь дань совместимости: тонкие обёртки и точки входа для тех, кто привык к слеш-командам. Долговечная логика — описание процесса, ограничения, шаблоны — должна жить в навыках (`SKILL.md`), которые агент способен подобрать сам по контексту запроса. Команда тогда становится не местом, где хранится логика, а коротким ярлыком, который на эту логику ссылается. Практический вывод: если процесс начался как команда, переносите его суть в навык, а команду оставляйте тонкой обёрткой. Тогда тот же процесс будет работать и при явном вызове, и когда агент сам решит, что навык уместен. Пример. Был повторяемый запрос, оформленный как команда «собери журнал изменений». Durable-часть переносится в навык: ```text .qwen/skills/changelog/SKILL.md ``` Сам навык `changelog` уже описан выше. Команда же сводится к одной строке, делегирующей работу навыку: ```markdown Используй навык changelog, чтобы обновить CHANGELOG.md перед слиянием ветки. ``` Логика — в навыке, команда — лишь ярлык. При обновлении процесса вы правите один `SKILL.md`, а не расходитесь по копиям в командах. ## Экономный поиск и модульность Два приёма экономят токены за счёт того, *как* агент ищет и *что* он удерживает в окне. Первый — предпочитать целевой поиск сплошному. Семантический поиск по коду экономнее текстового: по данным mgrep (Mixedbread) он даёт около 50% экономии токенов и примерно вдвое меньше токенов на бенчмарке из 50 задач поиска — при сопоставимом или лучшем качестве результата. Конкретный инструмент тут вторичен; переносимая идея в том, чтобы искать прицельно, а не прогонять сплошной grep по всей базе и заливать окно совпадениями. На практике это значит: давайте агенту конкретные файлы и пути через `@file`, сужайте область поиска, не подсовывайте папки целиком, если можно подсунуть нужное. Второй — модульная кодовая база. Файлы в сотни, а не тысячи строк экономят токены и повышают шанс сделать задачу правильно с первого раза: небольшой файл агент удерживает в контексте целиком и видит его поведение, а не фрагмент. Гигантский файл приходится читать частями, и именно на стыках частей рождаются ошибки. Поэтому правило «модульность вместо мегафайлов» — это не только про чистоту кода, но и про токены и про надёжность работы агента. ## Практика 1. Создайте `.qwen/skills/feature-spec/SKILL.md`. 2. Перезапустите Qwen Code. 3. Вызовите `/skills`. 4. Создайте новую спецификацию фичи через навык. 5. Создайте навык для журнала изменений. 6. Перед слиянием используйте навык для журнала изменений. ## Контрольные вопросы 1. Когда повторяемый запрос должен стать навыком? 2. Почему проектный навык лучше личного для командного процесса? 3. Что должно быть в `description`, чтобы агент правильно находил навык?