Правила проекта в Qwen Code: контекстные файлы и экономия токенов

Агент без правил проекта делает «в среднем по больнице»: свой стиль, лишние файлы, не те команды для тестов. Qwen Code решает это несколькими механизмами, и у каждого своя цена в токенах. Ниже разбираем qwen code rules по документации проекта: что кладётся в QWEN.md, как работает каталог .qwen/rules/, где нужны навыки (skills) и MCP, и как не отправлять модели лишнее на каждом запросе. Цены токенов даны на 18 октября 2026.

Откуда агент берёт правила

В документации описано четыре источника инструкций:

Главное следствие: всё, что лежит в QWEN.md, оплачивается на каждом запросе каждой сессии. Поэтому длинный файл с «правилами на все случаи» стоит денег и ещё и хуже соблюдается: в документации прямо сказано, что чем длиннее файл, тем менее надёжно агент ему следует.

QWEN.md: что писать и где хранить

Файлы лежат в трёх местах:

• ~/.qwen/QWEN.md для вас во всех проектах;
• QWEN.md в корне репозитория для всей команды (коммитится);
• .qwen/QWEN.local.md только для вас в этом проекте. Добавьте его в .gitignore сами, автоматически это не делается.

Если в репозитории уже есть AGENTS.md, Qwen Code прочитает и его, дублировать не нужно. Другие файлы можно подключить ссылкой @docs/git-workflow.md внутри QWEN.md. Начальный вариант создаёт команда /init: агент изучит репозиторий и предложит команды сборки и тестов.

Что стоит записать: команды (pytest -q, make lint), ограничения («не трогать migrations/»), договорённости об архитектуре. Что не стоит: всё, что агент увидит сам, читая код. Пример короткого файла:

Проект: бэкенд на FastAPI

## Команды
- Тесты: `pytest -q`
- Линтер: `ruff check .`

## Правила
- Новые эндпоинты только в `app/api/`, схемы в `app/schemas/`.
- Не менять файлы в `migrations/` без явной просьбы.
- Тексты ошибок для пользователя на русском.
- Перед правкой публичной функции найти все её вызовы.

Это около десятка строк и порядка 150 токенов. Именно такой размер и стоит держать.

Условные правила: .qwen/rules

Каталог .qwen/rules/ в проекте (и ~/.qwen/rules/ для личных) хранит Markdown-файлы. Если в начале файла есть блок paths:, правило условное: оно не попадает в промпт, пока агент не прочитает или не отредактирует подходящий файл, а потом добавляется один раз за сессию.

---
description: Как мы пишем React-компоненты
paths:
  - 'src/**/*.tsx'
---

Только функциональные компоненты. Тест лежит рядом с компонентом.
Состояние одного экрана не выносим в глобальное хранилище.

Пока вы правите Makefile, этот текст ничего не стоит. Правило без paths: ведёт себя как QWEN.md и оплачивается каждый раз. Правила проекта в .qwen/rules/, по документации, загружаются, когда рабочая папка доверенная.

Навыки и MCP

Навыки подходят для процедур, которые агент выбирает сам: «как оформить миграцию», «как собрать релиз». В каталоге .qwen/skills/имя-навыка/ лежит SKILL.md, в промпт попадают только имя и описание. Личные навыки лежат в ~/.qwen/skills/.

MCP подключает внешние инструменты: базу данных, трекер задач. Серверы описываются в mcpServers в settings.json или добавляются командой вида qwen mcp add --transport http имя адрес. Важная деталь: схема каждого подключённого инструмента тоже входит в каждый запрос. Отключайте то, чем не пользуетесь.

Сколько это стоит в токенах

Измерить префикс можно прямо в сессии: команда /context detail показывает разбивку, в том числе по файлам контекста. Смотрите её на первом шаге сессии, пока диалог пуст.

Теперь деньги. Допустим, постоянная часть промпта (QWEN.md и безусловные правила) занимает P токенов, а сессия делает N = 60 запросов. Дополнительный вход = P × N. Возьмём P = 3 000 и P = 12 000:

Это расчёт без кэша. Повторяющийся префикс как раз и хорошо кэшируется. Для GPT-моделей шлюз видит чтение кэша в обоих форматах: у gpt-6.1-sol оно стоит $0,013 за 1M, то есть в примере выше на P = 12 000 это 0,72 × 0,013 = $0,00936 вместо $0,1944. Для Claude скидка работает только в Anthropic-формате, а в OpenAI-формате (/v1/chat/completions) весь вход идёт по цене входа. Сам Qwen Code, по документации, использует кэширование при работе по API-ключу, а команда /stats показывает долю токенов, отданных из кэша. Подробнее о кэше: чтение и запись кэша промптов↗.

Каждый запрос идёт как обычный вызов chat completions↗, где ваши файлы правил входят в системное сообщение, так что цена считается по таблице выше. Подключение Qwen Code к Zukko: адрес https://api.zukko.pro/v1, ключ из кабинета↗, см. Qwen Code CLI: подключение↗.

Как сократить правила

1. Оставьте в QWEN.md только вечные факты: команды, жёсткие запреты, словарь проекта.
2. Всё формата «когда делаешь X, поступай так» вынесите в условное правило или навык.
3. Не переписывайте то, что видно из кода: структуру каталогов, названия функций.
4. Сверяйтесь с /context detail после каждого заметного добавления.
5. Разделяйте личное и командное: QWEN.local.md не для общего репозитория.

Похожая логика действует и для других агентов с их файлами (CLAUDE.md в Claude Code, AGENTS.md в Codex), а также для правил в Cursor↗.

Частые вопросы

Читает ли Qwen Code файл CLAUDE.md?

В документации Qwen Code упомянут AGENTS.md, а про CLAUDE.md там ничего подтверждающего нет. Если у вас уже есть правила, положите общую часть в AGENTS.md или сошлитесь на неё из QWEN.md через @.

Чем правила отличаются от навыков?

Правило привязывается к области кода (по paths:) и срабатывает само. Навык описывает процедуру, и агент решает, нужен ли он. Тело навыка загружается только при вызове.

Как проверить, что агент видит файл правил?

Запустите /context detail: там перечислены все файлы контекста. Также можно просто спросить у агента, какие инструкции проекта он видит.

Будут ли правила работать с моделью не от Qwen?

Да, это функция самой программы, а не модели. Насколько точно конкретная модель следует правилам, проверьте на своих задачах.