Тема: Приложение B. Совместимость с Qwen Code
Уровень сложности: Средний (Средний)
Расчётное время изучения: 2-3 часа
Предварительные требования: Базовое понимание работы с CLI (интерфейс командной строки)
Опыт использования систем контроля версий (Git)
Общее понимание принципов работы LLM и AI-ассистентов в разработке
Знакомство с концепциями CI/CD и написанием скриптов (Bash/Python)
Цели обучения: Различать встроенные возможности Qwen Code и процессы, требующие пользовательской реализации.
Правильно применять «Каноническую шкалу» (Стандарт, Рекомендация, Фронтир) для классификации рабочих процессов.
Создавать и интегрировать пользовательские команды в структуре каталога .qwen/commands/.
Проектировать безопасные интеграции с внешними API с использованием MCP-серверов и разрешительных списков (allowlists).
Понимать роли (Верификатор, Имплементор, Safety, Координатор) и то, как они распределяются между моделью, скриптами и человеком.
Обзор: Данное руководство посвящено архитектуре и совместимости production-процессов с использованием Qwen Code. Материал помогает разработчикам провести четкую границу между штатными возможностями платформы и пользовательскими расширениями. Вы узнаете, как масштабировать процессы от базового использования CLI до сложной оркестрации с внешними API, не нарушая при этом безопасности и предсказуемости системы. Руководство опирается на концепцию трех уровней зрелости (Каноническую шкалу) и дает практические советы по внедрению хуков, скриптов и команд.
Ключевые концепции: Каноническая шкала: Трехуровневая модель классификации процессов: Стандарт (встроенные функции Qwen Code), Рекомендация (пользовательские команды, скрипты и навыки, хранящиеся в репозитории) и Фронтир (сложная production-оркестрация с внешними сервисами вроде Kubernetes или Grafana).
Встроенный слой qwen code: Базовый функционал, доступный сразу: /plan (планирование), /review (ревью кода), /skills (навыки), управление памятью (/memory), вызов shell-команд (!command) и headless-режим для CI (qwen -p).
Пользовательские команды: Специфичные для проекта инструкции, оформленные в виде Markdown-файлов (например, .qwen/commands/sdd/specify.md). Позволяют стандартизировать шаги, такие как уточнение требований (/clarify) или генерация задач, вызывая их через /sdd:clarify.
Проектные скрипты: Детерминированные проверки (например, validate_schema.py или check_invariants.py), написанные на Python или Bash. В отличие от LLM, они дают однозначный «зеленый» или «красный» статус без риска галлюцинаций модели.
Хуки (hooks) и guardrails: Система защиты и триггеров Qwen Code, использующая официальные события (PreToolUse, PostToolUse, UserPromptSubmit и др.) для контроля за действиями модели в реальном времени.
Mcp (model context protocol): Спецификация для безопасного подключения внешних API (Jira, Grafana и др.). Требует создания allowlists (списков разрешенных действий), разделения прав на чтение/запись и строгих политик в отношении секретов.
Практические упражнения: Название: Создание пользовательской команды /sdd:clarify
Проблема: Вам нужно стандартизировать процесс уточнения требований в вашей команде. Команда /clarify не встроена в Qwen Code. Создайте структуру файлов и базовый шаблон промпта для этой команды.
Решение: 1. Создайте директорию в корне проекта: .qwen/commands/sdd/. 2. Внутри создайте файл clarify.md. 3. Добавьте в файл текст: 'Ты бизнес-аналитик. Проанализируй контекст из {{args}} и @specs/. Задай уточняющие вопросы, чтобы устранить неоднозначность перед планированием. Условие остановки: задай не более 5 вопросов и дождись ответов пользователя.'. 4. Вызовите команду в CLI: /sdd:clarify Интеграция платежного шлюза.
Сложность: intermediate
Название: Настройка безопасного MCP-сервера для мониторинга
Проблема: Команда хочет, чтобы Qwen Code мог проверять алерты в Grafana. Опишите архитектуру разрешительного списка (allowlist) для MCP-сервера, чтобы модель не могла изменять дашборды или выполнять вредоносные команды.
Решение: 1. Создайте MCP-сервер, который выступает прокси к Grafana API. 2. В allowlist добавьте только инструменты с доступом 'только для чтения' (например, get_alerts, query_metrics). 3. Запретите любые пишущие инструменты (create_dashboard, delete_panel). 4. Убедитесь, что API-токены Grafana хранятся в переменных окружения оркестратора, а не передаются в QWEN.md.
Сложность: advanced
Название: Классификация процессов по Канонической шкале
Проблема: Распределите следующие три задачи по уровням Канонической шкалы: A) Автоматическое исправление опечаток в коде с помощью Qwen. B) Скрипт на Python для проверки покрытия спецификаций. C) Интеграция с PagerDuty для автоматического создания инцидентов.
Решение: A) Стандарт (базовая функция авто-редактирования Qwen Code). B) Рекомендация (проектный скрипт в директории scripts/spec_ci/, работающий как детерминированная проверка). C) Фронтир (требуется внешний оркестратор и MCP-сервер для интеграции с API PagerDuty).
Сложность: beginner
Кейсы: Название: Внедрение Spec CI (Шлюза спецификаций) в Enterprise-проекте
Сценарий: Крупная команда разработки использует подход, при требования сначала описываются в спецификациях, а затем пишется код. Qwen Code используется для помощи в написании спецификаций.
Задача: Иногда Qwen Code генерировал спецификации, которые не соответствовали внутреннему JSON-формату компании или содержали логические противоречия. Проверка этого руками занимала слишком много времени.
Решение: Команда применила уровень «Рекомендация». Они написали проектные скрипты (validate_schema.py и check_coverage.py), которые запускаются в GitHub Actions. Qwen Code использовался через флаг qwen -p для генерации черновиков, но финальное принятие спецификации зависело исключительно от детерминированного скрипта, а не от убедительности ответа LLM.
Результат: Надежность спецификаций выросла до 100%. Разработчики перестали получать неожиданные ошибки при парсинге, а процесс валидации стал полностью автоматизирован.
Извлечённые уроки: Зависимость валидации от убедительности ответа модели (LLM) недопустима в production.
Зеленый статус проверки должен зависеть от кода валидации, а не от отсутствия ошибок в генерации.
Связанные концепции: Шлюз спецификации (Spec CI)
Каноническая шкала (Рекомендация)
Проектные скрипты
Название: Безопасная интеграция с облачной инфраструктурой
Сценарий: Разработчик хочет использовать Qwen Code для триажа проблем в кластере Kubernetes и обновления тикетов в Jira.
Задача: Передача прямого доступа через shell-команды (!command) могла привести к случайному удалению ресурсов в Kubernetes или утечке токенов в истории чата.
Решение: Использование уровня «Фронтир». Вместо прямого доступа был развернут MCP-сервер с жестким allowlist: инструменты Kubernetes ограничились только чтением (get_pods, describe_logs), а для Jira были настроены явные условия подтверждения. Токены доступа были скрыты в переменных окружения и никогда не попадали в QWEN.md.
Результат: Qwen Code успешно помогает диагностировать сбои и обновлять тикеты. Риск случайного выполнения деструктивных команд (например, удаления подов) был сведен к нулю благодаря guardrails и архитектуре MCP.
Извлечённые уроки: Production API не должны становиться неограниченными shell-командами.
Запрет на передачу секретов в подсказках критичен для безопасности проекта.
Связанные концепции: MCP (Model Context Protocol)
Безопасность LLM
Ограждения (Guardrails)
Советы по изучению: Запомните главное правило проверки: если результат зависит от мнения или ответа модели, это еще не production-процесс. Истинная валидация должна быть доверена проектным скриптам.
Всегда начинайте с «Стандарта». Не пытайтесь сразу внедрять «Фронтир» (Kubernetes, оркестраторы), если вас устраивают базовые встроенные команды Qwen Code.
Изучите структуру папки .qwen/commands/. Составление собственных .md файлов с правилами остановки — это самый быстрый способ адаптировать Qwen Code под ваши процессы.
При работе с внешними сервисами всегда мысленно проектируйте MCP-сервер: определите, какие действия относятся к 'только чтение', а какие требуют 'отката' (rollback).
Дополнительные ресурсы: Официальная документация qwen code (команды): https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/
Qwen code headless mode: https://qwenlm.github.io/qwen-code-docs/en/users/features/headless/
Документация по mcp (model context protocol): https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/
Официальная документация qwen code (хуки): https://qwenlm.github.io/qwen-code-docs/en/users/features/hooks/
Owasp top 10 для llm приложений (безопасность): https://owasp.org/www-project-top-10-for-large-language-model-applications/
Google sre book (для понимания принципов оркестрации): https://sre.google/sre-book/
Резюме: Приложение B фиксирует четкую границу между встроенными функциями Qwen Code и процессами, которые команда должна реализовать самостоятельно. Использование Канонической шкалы (Стандарт, Рекомендация, Фронтир) помогает правильно оценивать сложность внедрения. Ключевой вывод: Qwen Code является мощным ассистентом, но в критических узлах (валидация спецификаций, файловый арбитраж, безопасность) система должна опираться на детерминированные проектные скрипты и строго настроенные ограждения (guardrails) через хуки и MCP-серверы.