Тема: Приложение B. Совместимость с Qwen Code
Уровень сложности: Средний
Расчётное время изучения: 6-8 часов (теория + практика)
Предварительные требования: Базовое знакомство с Qwen Code и его CLI-интерфейсом
Понимание основ Git и структуры репозиториев
Опыт работы с Markdown-файлами и конфигурациями
Базовые знания Python или другого скриптового языка
Понимание концепций CI/CD (желательно)
Цели обучения: Различать три уровня зрелости (Стандарт, Рекомендация, Фронтир) и правильно классифицировать production-процессы по слоям реализации
Создавать пользовательские команды в структуре .qwen/commands/ с правильным именованием и контрактами остановки
Проектировать воспроизводимые проверки в виде проектных скриптов, независимых от убедительности ответа модели
Настраивать хуки Qwen Code (PreToolUse, PostToolUse, UserPromptSubmit и др.) для ограждений (guardrails)
Интегрировать внешние production API через MCP-серверы с разрешительным списком инструментов и защитой секретов
Обзор: Приложение B фиксирует критически важную границу между встроенными возможностями Qwen Code и процессами, которые необходимо реализовать в проекте самостоятельно. Второй том курса описывает production-процессы вокруг Qwen Code: часть встроена в инструмент, часть требует пользовательских команд, навыков, хуков, MCP-серверов или обычных скриптов. Учебное пособие строится вокруг канонической шкалы из трёх уровней зрелости — Стандарт, Рекомендация и Фронтир — которая определяет ожидания от читателя и слой реализации. Понимание этой границы предотвращает ошибку, при которой проектируемый процесс принимается за штатную CLI-команду, и позволяет правильно архитектурно распределять ответственность между встроенным инструментом, проектной конфигурацией и внешней оркестрацией.
Ключевые концепции: Каноническая шкала трёх уровней зрелости: Система классификации, не оценивающая качество идеи, а определяющая границу ожиданий от читателя. Стандарт — работает в обычном Qwen Code без дополнительной платформы, базовый материал курса, встроенные возможности. Рекомендация — полезно оформить в проекте при повторяющемся процессе, требует файлов репозитория: пользовательские команды, навыки, хуки или скрипты. Фронтир — production-оркестрация вокруг Qwen Code, нужна командам с внешними API, SRE-процессами и бюджетированием моделей, реализуется через внешний оркестратор, MCP, внешние сервисы.
Встроенный слой qwen code: Базовые возможности, используемые как есть без дополнительной конфигурации: /plan (режим планирования без правок и shell-выполнения), /review (встроенное ревью кода с детерминированными проверками и параллельными ревью-агентами), /skills (просмотр и явный запуск навыков), /memory, /remember, /forget (управление памятью и QWEN.md), /mcp и qwen mcp add (подключение MCP-серверов), @path (добавление файла/каталога в контекст), !command (shell-команды в интерактивной сессии), qwen -p "..." (безголовый запуск для CI и скриптов).
Пользовательские команды: Механизм расширения Qwen Code через создание Markdown-файлов в структуре .qwen/commands/<namespace>/<command>.md. Команды вызываются как /<namespace>:<<command>, содержат подсказки с {{args}}, ссылками на @specs/... и правилами остановки. Позволяют воспроизвести поведение команд первого тома (например, /clarify) без неявных допущений о их встроенности.
Проектные скрипты: Воспроизводимые проверки, не зависящие от модели, оформленные как обычные скрипты в директории проекта. Зелёный статус CI должен зависеть от кода проверки, а не от убедительности ответа модели. Примеры: check_coverage.py, validate_schema.py, mutate_specs.py, run_duel.py, compile.py для бюджета.
Хуки (hooks): Официальные события Qwen Code для реализации ограждений (guardrails): PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, Stop, SubagentStop, Notification, PreCompact и другие. Требуют использования точных имён событий из актуальной документации, а не свободных вариантов.
Mcp-серверы и внешние api: Метод интеграции production API (Grafana, PagerDuty, Kubernetes, Jira) без превращения их в неограниченные shell-команды. Требуют разрешительного списка (allowlist) инструментов: только-чтение для triage, отдельные пишущие инструменты для безопасных действий, явные условия подтверждения и отката, запрет на передачу секретов в подсказках, следах и QWEN.md.
Роли production-процесса: Верификатор (Verifier) — голосует через /review, отдельную сессию, под-агента или скрипт. Имплементор (Implementor) — голосует через Qwen Code в режиме default/auto-edit после утверждённого плана. Safety — голосует с veto при critical_risk через отдельную сессию или скрипт проверки blast radius. Координатор (Coordinator) — non-voting protocolist, реализуется человеком, CI или внешним оркестратором.
Файловый арбитраж (tribunal): Не встроенная команда; комбинация /review, скриптов, отчётов и правил в validation.md для разрешения конфликтов при одновременном редактировании.
Шлюз спецификации (spec ci): GitHub Actions или локальные скрипты, которые могут использовать qwen -p только как вспомогательный слой, но основная проверка — детерминированный код.
Хранитель бюджета (budget keeper): Внешний сервис или скрипт; Qwen Code сам не управляет суточной квотой ярусов моделей.
Практические упражнения: Название: Классификация процессов по уровням зрелости
Проблема: Даны пять production-процессов: (1) запуск /plan для декомпозиции задачи, (2) автоматическая проверка покрытия тестами через скрипт check_coverage.py, (3) интеграция с Kubernetes для rolling deployment, (4) использование /review для code review, (5) пользовательская команда /sdd:validate для проверки спецификации. Классифицируйте каждый процесс по канонической шкале (Стандарт, Рекомендация, Фронтир). Обоснуйте решение для каждого случая.
Решение: 1) Стандарт — /plan является встроенной командой Qwen Code, не требует дополнительных файлов. 2) Рекомендация — скрипт check_coverage.py требует создания файла в репозитории, воспроизводим без модели, полезен при повторении. 3) Фронтир — Kubernetes — внешний оркестратор, требует production-инфраструктуры, SRE-процессов. 4) Стандарт — /review встроена в Qwen Code с детерминированными проверками. 5) Рекомендация — пользовательская команда требует создания .qwen/commands/sdd/validate.md, относится к проектному слою. Ключевой критерий: нужны ли файлы в репозитории (Рекомендация) или внешние сервисы (Фронтир).
Сложность: beginner
Название: Создание пользовательской команды clarify
Проблема: В первом томе использовалась команда /clarify для уточнения требований до планирования. Она не встроена в Qwen Code. Создайте структуру файлов и содержание Markdown-файла для пользовательской команды /sdd:clarify, которая воспроизводит поведение из первого тома. Определите контракт остановки и правила использования {{args}} и @specs/.
Решение: Структура: .qwen/commands/sdd/clarify.md. Содержание файла должно включать: (1) описание цели — уточнение неоднозначных требований перед планированием; (2) шаблон с {{args}} для передачи контекста; (3) ссылки на @specs/ для загрузки спецификаций; (4) правила остановки — команда останавливается, когда все неоднозначности разрешены и сформирован список уточнённых требований; (5) инструкцию не начинать планирование или редактирование кода. Пример вызова: /sdd:clarify 'требования к API аутентификации'. Контракт остановки: выход при достижении состояния 'все вопросы уточнены, ответы задокументированы в формате списка'.
Сложность: intermediate
Название: Проектирование MCP-сервера для безопасной интеграции
Проблема: Команда использует Grafana для мониторинга и PagerDuty для алертинга. Необходимо предоставить Qwen Code доступ к этим сервисам без превращения их в неограниченные shell-команды. Спроектируйте архитектуру MCP-сервера с разрешительным списком инструментов, определите условия подтверждения для пишущих операций и механизм защиты секретов.
Решение: Архитектура MCP-сервера: (1) Инструменты только-чтения: grafana_query_metrics (promQL-запросы), grafana_list_dashboards, pagerduty_list_incidents, pagerduty_get_incident_details — для triage и проверки, без подтверждения. (2) Пишущие инструменты с явным подтверждением: pagerduty_acknowledge_incident (требует подтверждения с указанием причины), pagerduty_escalate_incident (требует двойного подтверждения). (3) Условия отката: для pagerduty_create_incident — проверка обязательных полей, лимит 5 инцидентов в час, автоматическая отмена при ошибке 5xx. (4) Защита секретов: API-ключи хранятся в переменных окружения сервера, не передаются в подсказках; QWEN.md не содержит endpoint-адресов с credentials; логирование запросов маскирует заголовки авторизации. (5) Конфигурация: qwen mcp add pagerduty-ops --url http://localhost:3001/sse --tools allowlist:grafana_query_metrics,grafana_list_dashboards,pagerduty_list_incidents,pagerduty_acknowledge_incident.
Сложность: advanced
Название: Настройка хуков для ограждений
Проблема: Необходимо реализовать guardrails для сценария: (1) запретить выполнение shell-команд, содержащих rm -rf / или DROP TABLE, (2) логировать все обращения к внешним API перед выполнением, (3) архивировать контекст сессии перед компактизацией памяти. Выберите подходящие официальные события Qwen Code и опишите конфигурацию хуков.
Решение: (1) PreToolUse — проверка аргументов инструмента shell_execute на наличие запрещённых паттернов: rm -rf /, DROP TABLE, TRUNCATE. При совпадении — отмена выполнения с уведомлением пользователя. (2) PreToolUse или PostToolUse — логирование обращений к внешним API: фиксация endpoint, метода, временной метки в структурированном логе. (3) PreCompact — архивирование текущего контекста сессии в файл .qwen/archive/sessions/<timestamp>.md перед компактизацией памяти. Важно: использовать точные имена событий из документации — PreToolUse, PostToolUse, PreCompact — а не варианты вроде pretooluse. Конфигурация хуков требует сверки с актуальной документацией Qwen Code по формату и параметрам.
Сложность: intermediate
Название: Разделение ответственности в Spec CI
Проблема: Команда хочет автоматически проверять спецификации при каждом PR. Обсуждается два подхода: (A) использовать qwen -p 'проверь спецификацию' как основной механизм, (B) создать скрипт validate_schema.py с детерминированными проверками, а qwen -p использовать только для генерации отчётов. Примените принципы Приложения B для выбора правильного подхода и опишите архитектуру.
Решение: Правильный подход — (B), соответствует слою Рекомендации/Фронтира. Архитектура: (1) Основная проверка — скрипт validate_schema.py, проверяющий JSON Schema, целостность ссылок, дублирование идентификаторов. Зелёный статус CI зависит только от кода проверки. (2) Вспомогательный слой — qwen -p 'сгенерируй читаемый отчёт по результатам validate_schema.py', используется только для форматирования вывода, не влияет на pass/fail. (3) Интеграция в GitHub Actions: шаг 'Validate Schema' запускает python scripts/spec_ci/validate_schema.py --strict; шаг 'Generate Report' опционально использует qwen -p для улучшения читаемости. (4) Принцип: зелёный статус не должен зависеть от убедительности ответа модели — это ключевое требование Приложения B для проектных скриптов.
Сложность: intermediate
Кейсы: Название: Миграция команды разработки с неявных предположений на явную архитектуру Qwen Code
Сценарий: Команда из 12 разработчиков полгода использовала Qwen Code для разработки микросервисной платформы. Члены команды неформально использовали команды вроде '/clarify', '/specify', '/tasks', считая их встроенными в Qwen Code. При onboarding новых разработчиков возникали постоянные конфликты: команды не работали в новых проектах, поведение отличалось между сессиями, невозможно было воспроизвести процессы в CI.
Задача: Неявные предположения о встроенности команд приводили к: (1) фрагментации процессов — каждый разработчик имел своё понимание шагов; (2) невозможности воспроизведения в CI — команды, работающие в интерактивном режиме, отсутствовали в headless; (3) отсутствия документации — контракты остановки были устными; (4) рисков при масштабировании — новые члены команды тратили недели на выяснение 'как это работает у нас'.
Решение: Команда провела аудит по методологии Приложения B. Шаг 1: Классификация всех используемых процессов по канонической шкале. Оказалось, что /plan и /review — Стандарт, а /clarify, /specify, /tasks, /validate — требуют создания пользовательских команд. Шаг 2: Создание структуры .qwen/commands/sdd/ с namespace 'sdd' (Software Design Document), включающей clarify.md, specify.md, tasks.md, validate.md, constitution.md. Каждый файл содержал явный контракт остановки, шаблоны с {{args}}, ссылки на @specs/. Шаг 3: Перенос детерминированных проверок в проектные скрипты: validate_schema.py, check_coverage.py, mutate_specs.py. Шаг 4: Настройка Spec CI в GitHub Actions с qwen -p только для отчётов. Шаг 5: Документирование границ: в README явно указано, какие команды встроены, какие — проектные.
Результат: Через 3 недели: время onboarding сократилось с 2 недель до 2 дней; 100% воспроизводимость CI-проверок; единый язык процессов между командами; возможность версионирования команд через Git. Команда смогла масштабироваться до 20 разработчиков без деградации процессов. Ключевое изменение мышления: переход от 'Qwen Code всё умеет' к 'мы явно проектируем, что Qwen Code делает, а что — наш проект'.
Извлечённые уроки: Неявные предположения о встроенности — главный источник фрагментации процессов в командах
Каноническая шкала — инструмент коммуникации, а не только архитектурный; она синхронизирует ожидания между разработчиками
Пользовательские команды с явными контрактами остановки дороже в создании, но бесплатны в масштабировании
Зелёный статус CI должен зависеть от кода, а не от модели — это нелегко принять, но критично для production
Связанные концепции: Каноническая шкала трёх уровней зрелости
Пользовательские команды
Проектные скрипты
Шлюз спецификации (Spec CI)
Название: Интеграция SRE-процессов через MCP-сервер для финтех-компании
Сценарий: Финтех-компания с регуляторными требованиями использовала Qwen Code для разработки платёжного шлюза. Требовалась интеграция с PagerDuty для эскалации инцидентов, Grafana для проверки метрик перед деплоем, и внутренним API для аудита. Прямые shell-команды с API-ключами в подсказках создавали критические риски безопасности.
Задача: Регуляторные требования: (1) все действия с production-системами должны быть аудируемы; (2) API-ключи не должны попадать в логи и подсказки; (3) эскалация инцидентов требует двойного подтверждения; (4) откат изменений должен быть возможен в течение 5 минут. При этом разработчики хотели использовать Qwen Code для операционных задач без переключения контекста.
Решение: Архитектура по принципам Приложения B (слой Фронтир): (1) MCP-сервер 'ops-bridge' на Go, развёрнутый внутри VPC, с разрешительным списком из 8 инструментов. Только-чтение: grafana_query_metrics, pagerduty_list_incidents, pagerduty_get_incident_details, audit_log_query. Пишущие с подтверждением: pagerduty_acknowledge_incident (требует reason ≥ 20 символов), pagerduty_escalate_incident (требует approval_code из SMS), audit_log_append (только структурированные записи). (2) Запрет на shell-доступ к production через хук PreToolUse — блокировка любых !command, содержащих kubectl, ssh, curl к production domains. (3) Секреты: API-ключи в HashiCorp Vault, MCP-сервер аутентифицируется через mTLS; QWEN.md содержит только описание инструментов, never endpoint URLs with credentials. (4) Хук PostToolUse логирует все вызовы в структурированный audit trail. (5) Бюджетирование через внешний Budget Keeper — отдельный сервис, отслеживающий стоимость вызовов моделей и блокирующий при превышении суточной квоты.
Результат: Прошёл аудит регулятора без замечаний по части AI-инструментов. Время реакции на инциденты сократилось на 40% за счёт доступа к метрикам из Qwen Code. Нулевой инцидентов с утечкой credentials. Бюджет моделей контролируем и предсказуем. Команда получила 'единое окно' для разработки и операций без нарушения security boundary.
Извлечённые уроки: Production API через MCP с allowlist — единственный приемлемый способ для регулируемых индустрий
Хуки PreToolUse/PostToolUse — критически важны для defense in depth, но требуют точных имён событий из документации
Внешний Budget Keeper необходим, потому что Qwen Code не управляет суточными квотами — это фронтирный слой по определению
QWEN.md никогда не должен содержать чувствительных данных, даже в зашифрованном виде
Связанные концепции: MCP-серверы и внешние API
Хуки (Hooks)
Хранитель бюджета (Budget Keeper)
Фронтир — уровень зрелости
Советы по изучению: Создайте физическую или цифровую 'карту решений': для любого production-процесса задавайте вопрос 'Можно ли это сделать встроенной командой Qwen Code?' → если да, это Стандарт; если требует файлов проекта, но не внешних сервисов — Рекомендация; если нужны Kubernetes, Grafana, внешние API — Фронтир
Практикуйтесь на реальном репозитории: создайте .qwen/commands/demo/ с 2-3 пользовательскими командами, вызовите их, проверьте воспроизводимость после git clone в другую директорию
Для понимания хуков: заведите тестовый проект, настройте логирование PreToolUse и PostToolUse, проанализируйте, какие события генерируются при разных действиях — это даст интуицию о точках перехвата
Изучайте MCP через призму безопасности: для каждого инструмента, который вы добавляете, явно документируйте 'что худшее может произойти' и как allowlist/подтверждение это предотвращает
Парное обучение: один человек проектирует процесс как 'всё встроено в Qwen Code', второй — как 'всё внешние скрипты'; затем применяете каноническую шкалу для синтеза — это тренирует архитектурное мышление
Ведите 'журнал границ': записывайте случаи, когда вы или коллеги предполагали встроенность команды, а она оказалась проектной — это типичная ошибка, и её паттерны повторяются
Для headless-режима (qwen -p): настройте минимальный CI-пайплайн в GitHub Actions или GitLab CI, чтобы почувствовать разницу между интерактивной сессией и автоматизированным запуском
Изучайте связь между ролями второго тома (Верификатор, Имплементор, Safety, Координатор) и конкретными механизмами Qwen Code — создайте таблицу соответствия для своего проекта
Дополнительные ресурсы: Документация qwen code — commands: 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/
Документация qwen code — hooks: https://qwenlm.github.io/qwen-code-docs/en/users/features/hooks/
Документация qwen code — skills: https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/
Документация qwen code — memory: https://qwenlm.github.io/qwen-code-docs/en/users/features/memory/
Документация qwen code — mcp: https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/
Документация qwen code — approval mode: https://qwenlm.github.io/qwen-code-docs/en/users/features/approval-mode/
Документация qwen code — code review: https://qwenlm.github.io/qwen-code-docs/en/users/features/code-review/
Github spec kit: https://github.com/github/spec-kit
Aws kiro documentation overview: https://aws.amazon.com/documentation-overview/kiro/
Owasp top 10 for llm applications: https://owasp.org/www-project-top-10-for-large-language-model-applications/
Google sre book: https://sre.google/sre-book/
Goodhart's law (википедия): https://en.wikipedia.org/wiki/Goodhart%27s_law
Спецификация протокола mcp (model context protocol): Рекомендуется изучить официальную спецификацию Anthropic для глубокого понимания архитектуры MCP-серверов
Резюме: Приложение B устанавливает архитектурную границу между встроенными возможностями Qwen Code и процессами, которые команды должны реализовывать самостоятельно. Ключевой инструмент — каноническая шкала из трёх уровней зрелости (Стандарт, Рекомендация, Фронтир), которая определяет ожидания и слой реализации. Встроенные команды (/plan, /review, /skills, /memory, /mcp, @path, !command, qwen -p) используются как есть. Пользовательские команды требуют создания .qwen/commands/<namespace>/<command>.md с явными контрактами остановки. Проектные скрипты обеспечивают воспроизводимость независимо от модели. Хуки реализуют ограждения через официальные события Qwen Code. MCP-серверы с разрешительным списком инструментов интегрируют внешние API безопасно. Понимание этой границы предотвращает ошибку неявных предположений о встроенности, обеспечивает масштабируемость процессов и делает production-использование Qwen Code предсказуемым и аудируемым.