Project rules in Qwen Code: context files and token savings

An agent without project rules does "something average": its own style, extra files, the wrong test commands. Qwen Code solves this with several mechanisms, and each has its own price in tokens. Below we go through Qwen Code rules per the project documentation: what goes into QWEN.md, how the .qwen/rules/ folder works, where skills and MCP fit, and how not to send the model extra text on every request. Token prices are as of October 18, 2026.

Where the agent gets its rules

The documentation describes four sources of instructions:

The main consequence: everything in QWEN.md is paid for on every request of every session. So a long file with "rules for every case" costs money and is also followed less well: the documentation says directly that the longer the file, the less reliably the agent follows it.

QWEN.md: what to write and where to keep it

Files live in three places:

• ~/.qwen/QWEN.md for you across all projects;
• QWEN.md in the repository root for the whole team (committed);
• .qwen/QWEN.local.md for you only in this project. Add it to .gitignore yourself, it is not done automatically.

If the repository already has an AGENTS.md, Qwen Code reads it too, so no need to duplicate. Other files can be pulled in with a reference like @docs/git-workflow.md inside QWEN.md. The /init command creates a starting version: the agent studies the repository and proposes build and test commands.

What to write: commands (pytest -q, make lint), constraints ("do not touch migrations/"), architecture agreements. What not to write: anything the agent will see by reading the code. A short file example:

Project: FastAPI backend

## Commands
- Tests: `pytest -q`
- Linter: `ruff check .`

## Rules
- New endpoints only in `app/api/`, schemas in `app/schemas/`.
- Do not change files in `migrations/` unless explicitly asked.
- User-facing error texts in Russian.
- Before changing a public function, find all its call sites.

That is about ten lines and around 150 tokens. That is the size to aim for.

Conditional rules: .qwen/rules

The .qwen/rules/ folder in the project (and ~/.qwen/rules/ for personal ones) holds Markdown files. If a file starts with a paths: block, the rule is conditional: it stays out of the prompt until the agent reads or edits a matching file, and is then added once per session.

---
description: How we write React components
paths:
  - 'src/**/*.tsx'
---

Function components only. The test sits next to the component.
Do not move one screen's state into a global store.

While you edit a Makefile, this text costs nothing. A rule without paths: behaves like QWEN.md and is paid for every time. Project rules in .qwen/rules/, per the docs, load when the workspace is trusted.

Skills and MCP

Skills suit procedures the agent picks itself: "how to write a migration", "how to cut a release". A SKILL.md lives in .qwen/skills/skill-name/, and only the name and description enter the prompt. Personal skills live in ~/.qwen/skills/.

MCP connects external tools: a database, a task tracker. Servers are described in mcpServers in settings.json or added with a command like qwen mcp add --transport http name address. An important detail: the schema of every connected tool also goes into every request. Disable what you do not use.

What it costs in tokens

You can measure the prefix right in a session: the /context detail command shows a breakdown, including per context file. Look at it on the first step of a session, while the dialog is empty.

Now money. Suppose the constant part of the prompt (QWEN.md and unconditional rules) takes P tokens and a session makes N = 60 requests. Extra input = P × N. Take P = 3,000 and P = 12,000:

This is a calculation without cache. A repeating prefix is exactly what caches well. For GPT models the gateway sees cache reads in both formats: for gpt-6.1-sol a read costs $0.013 per 1M, so in the example above at P = 12,000 that is 0.72 × 0.013 = $0.00936 instead of $0.1944. For Claude the discount works only in the Anthropic format, while in the OpenAI format (/v1/chat/completions) all input is billed at the input price. Qwen Code itself, per its docs, uses caching when working by API key, and the /stats command shows the share of tokens served from cache. More on caching: prompt cache reads and writes↗.

Each request is an ordinary chat completions↗ call in which your rule files are part of the system message, so the price follows the table above. Connecting Qwen Code to Zukko: address https://api.zukko.pro/v1, a key from the dashboard↗, see Qwen Code CLI: connecting↗.

How to shorten the rules

1. Keep only permanent facts in QWEN.md: commands, hard bans, project vocabulary.
2. Move anything shaped like "when doing X, do Y" into a conditional rule or a skill.
3. Do not restate what the code shows: directory structure, function names.
4. Check /context detail after every noticeable addition.
5. Separate personal and team: QWEN.local.md does not belong in a shared repository.

The same logic applies to other agents and their files (CLAUDE.md in Claude Code, AGENTS.md in Codex), as well as to rules in Cursor↗.

FAQ

Does Qwen Code read a CLAUDE.md file?

The Qwen Code documentation mentions AGENTS.md, and has nothing confirming CLAUDE.md. If you already have rules, put the common part into AGENTS.md or reference it from QWEN.md with @.

How do rules differ from skills?

A rule is tied to an area of code (via paths:) and fires on its own. A skill describes a procedure, and the agent decides whether it is needed. A skill's body loads only when invoked.

How do I check that the agent sees the rules file?

Run /context detail: it lists all context files. You can also simply ask the agent which project instructions it sees.

Will the rules work with a non-Qwen model?

Yes, it is a feature of the program, not of the model. How accurately a given model follows rules, test on your own tasks.