|
| 1 | +# Qwen Code Best Practices |
| 2 | + |
| 3 | +Use this file for Qwen Code-specific operating practice. Use `../routing.md` |
| 4 | +for host-neutral owner selection and `codex.md`/`claude.md` for other host |
| 5 | +references. Do not copy Qwen-only workflow advice into shared docs unless there |
| 6 | +is matching surface evidence. |
| 7 | + |
| 8 | +## Operating Frame |
| 9 | + |
| 10 | +Treat Qwen Code as a configured teammate, not a one-off assistant. Start with |
| 11 | +the right task context, move repeated guidance into `QWEN.md` and `AGENTS.md`, |
| 12 | +configure Qwen Code for the real workflow, connect external systems through |
| 13 | +MCP, turn repeated work into Skills and extensions, and automate only stable |
| 14 | +workflows. |
| 15 | + |
| 16 | +## Prompt Shape |
| 17 | + |
| 18 | +A strong first prompt has four parts: |
| 19 | + |
| 20 | +- **Goal**: the change, bug, review, artifact, or decision needed. |
| 21 | +- **Context**: files, folders, docs, examples, logs, errors, or other material |
| 22 | + Qwen Code should inspect. |
| 23 | +- **Constraints**: architecture rules, safety limits, review standards, platform |
| 24 | + requirements, and do-not-touch boundaries. |
| 25 | +- **Done when**: tests, checks, behavior, output files, or review evidence that |
| 26 | + prove the task is complete. |
| 27 | + |
| 28 | +## Durable Guidance |
| 29 | + |
| 30 | +Use `QWEN.md` and `AGENTS.md` for repository guidance that should load |
| 31 | +automatically: |
| 32 | + |
| 33 | +- repo layout and important directories |
| 34 | +- build, test, lint, and local run commands |
| 35 | +- engineering conventions and review expectations |
| 36 | +- safety constraints and do-not rules |
| 37 | +- what "done" means and how to verify work |
| 38 | + |
| 39 | +Keep context files short and practical. Put large or conditional detail in |
| 40 | +linked references. Use project-level `.qwen/settings.json` for repo-specific |
| 41 | +behavior and global `~/.qwen/settings.json` for personal defaults. |
| 42 | + |
| 43 | +When Qwen Code repeats a mistake, update durable guidance only when the lesson |
| 44 | +is reusable. |
| 45 | + |
| 46 | +## Configuration |
| 47 | + |
| 48 | +Qwen Code configuration should match the actual environment: |
| 49 | + |
| 50 | +- Use `~/.qwen/settings.json` for personal defaults (model, approval mode, |
| 51 | + permissions). |
| 52 | +- Use `<project>/.qwen/settings.json` for repo-specific behavior. |
| 53 | +- Use `.qwen/` for project-scoped skills, agents, hooks, and worktrees. |
| 54 | +- Keep approval and sandbox settings tight until a trusted workflow needs more |
| 55 | + access. |
| 56 | + |
| 57 | +## Skills and Extensions |
| 58 | + |
| 59 | +Turn a repeated workflow into a Skill when it has stable triggers, inputs, |
| 60 | +steps, outputs, and validation. Install extensions from marketplaces or local |
| 61 | +sources; each extension records its install marker under |
| 62 | +`~/.qwen/extensions/<name>/.qwen-extension-install.json` with a `source` |
| 63 | +pointer to the real plugin root. |
| 64 | + |
| 65 | +## External Context |
| 66 | + |
| 67 | +Use MCP when Qwen Code needs context or actions outside the repository. MCP |
| 68 | +servers are configured in `~/.qwen/settings.json` under `mcpServers` (user) or |
| 69 | +`<project>/.mcp.json` (project). Project-level `.qwen/settings.json` can also |
| 70 | +carry `mcpServers`. Start with one or two MCP tools that remove a real repeated |
| 71 | +manual step. |
| 72 | + |
| 73 | +## Session Controls |
| 74 | + |
| 75 | +Keep one Qwen Code session per coherent unit of work. Session transcripts are |
| 76 | +recorded as JSONL under `~/.qwen/projects/<workspace-slug>/chats/`. The slug |
| 77 | +replaces every non-alphanumeric character with `-` (matching Qwen's native |
| 78 | +`sanitizeCwd`; on Windows the path is lowercased first). Use worktrees when |
| 79 | +concurrent |
| 80 | +sessions could edit the same files. Use subagents for bounded exploration, |
| 81 | +testing, or independent review. |
| 82 | + |
| 83 | +## Harness Projection |
| 84 | + |
| 85 | +For readiness reports, separate static presence from quality and execution: |
| 86 | + |
| 87 | +- `QWEN.md`, `AGENTS.md`, `.qwen/settings.json`, Skills, extensions, MCP config, |
| 88 | + and hooks are configured-surface evidence. |
| 89 | +- Test output, build logs, reviewed diffs, session transcripts, and automation |
| 90 | + histories are execution evidence. |
| 91 | +- Do not claim a Qwen Code practice is effective from file presence alone. |
0 commit comments