Topic: Appendix B. Compatibility with Qwen Code
Difficulty level: Medium
Estimated study time: 2-3 hours
Prerequisites: Basic understanding of working with CLI (command-line interface)
Experience using version control systems (Git)
General understanding of the principles of LLM and AI assistants in development
Familiarity with CI/CD concepts and script writing (Bash/Python)
Learning objectives: Distinguish between the built-in capabilities of Qwen Code and processes that require user implementation.
Correctly apply the "Canonical Scale" (Standard, Recommendation, Frontier) to classify workflows.
Create and integrate custom commands within the .qwen/commands/ directory structure.
Design safe integrations with external APIs using MCP servers and allowlists.
Understand the roles (Verifier, Implementor, Safety, Coordinator) and how they are distributed between the model, scripts, and the human.
Overview: This guide focuses on the architecture and compatibility of production processes using Qwen Code. The material helps developers draw a clear boundary between the platform's standard capabilities and custom extensions. You will learn how to scale processes from basic CLI usage to complex orchestration with external APIs, without compromising system security and predictability. The guide relies on the concept of three maturity levels (the Canonical Scale) and provides practical advice on implementing hooks, scripts, and commands.
Key concepts: Canonical Scale: A three-level model for classifying processes: Standard (built-in Qwen Code features), Recommendation (custom commands, scripts, and skills stored in the repository), and Frontier (complex production orchestration with external services like Kubernetes or Grafana).
Built-in Qwen Code layer: Basic functionality available out of the box: /plan (planning), /review (code review), /skills (skills), memory management (/memory), shell command invocation (!command), and headless mode for CI (qwen -p).
Custom commands: Project-specific instructions formatted as Markdown files (e.g., .qwen/commands/sdd/specify.md). They allow standardizing steps such as clarifying requirements (/clarify) or generating tasks, invoked via /sdd:clarify.
Project scripts: Deterministic checks (e.g., validate_schema.py or check_invariants.py) written in Python or Bash. Unlike LLMs, they give an unambiguous "green" or "red" status without the risk of model hallucinations.
Hooks and guardrails: Qwen Code's protection and trigger system, using official events (PreToolUse, PostToolUse, UserPromptSubmit, etc.) to monitor model actions in real time.
MCP (Model Context Protocol): A specification for securely connecting external APIs (Jira, Grafana, etc.). It requires creating allowlists (lists of permitted actions), separating read/write permissions, and strict policies regarding secrets.
Practice exercises: Name: Creating a custom command /sdd:clarify
Problem: You need to standardize the requirements clarification process in your team. The /clarify command is not built into Qwen Code. Create the file structure and a basic prompt template for this command.
Solution: 1. Create a directory at the project root: .qwen/commands/sdd/. 2. Inside it, create the file clarify.md. 3. Add the following text to the file: 'You are a business analyst. Analyze the context from {{args}} and @specs/. Ask clarifying questions to resolve ambiguity before planning. Stopping condition: ask no more than 5 questions and wait for the user's answers.'. 4. Invoke the command in the CLI: /sdd:clarify Payment gateway integration.
Complexity: intermediate
Name: Setting up a secure MCP server for monitoring
Problem: The team wants Qwen Code to be able to check alerts in Grafana. Describe the allowlist architecture for the MCP server so that the model cannot modify dashboards or execute malicious commands.
Solution: 1. Create an MCP server that acts as a proxy to the Grafana API. 2. In the allowlist, add only tools with 'read-only' access (e.g., get_alerts, query_metrics). 3. Forbid any write tools (create_dashboard, delete_panel). 4. Ensure that Grafana API tokens are stored in orchestrator environment variables and are not passed into QWEN.md.
Complexity: advanced
Name: Classifying processes by the Canonical Scale
Problem: Distribute the following three tasks across the levels of the Canonical Scale: A) Automatic fixing of typos in code using Qwen. B) A Python script to check specification coverage. C) Integration with PagerDuty to automatically create incidents.
Solution: A) Standard (basic auto-editing feature of Qwen Code). B) Recommendation (project script in the scripts/spec_ci/ directory, acting as a deterministic check). C) Frontier (requires an external orchestrator and MCP server to integrate with the PagerDuty API).
Complexity: beginner
Case studies: Name: Implementing Spec CI (Specification Gateway) in an Enterprise project
Scenario: A large development team uses an approach where requirements are first described in specifications and then the code is written. Qwen Code is used to assist in writing specifications.
Challenge: Sometimes Qwen Code generated specifications that did not match the company's internal JSON format or contained logical contradictions. Manual verification of this took too much time.
Solution: The team applied the "Recommendation" level. They wrote project scripts (validate_schema.py and check_coverage.py) that run in GitHub Actions. Qwen Code was used via the qwen -p flag to generate drafts, but the final acceptance of the specification depended exclusively on the deterministic script, not on the persuasiveness of the LLM's response.
Result: Specification reliability increased to 100%. Developers stopped receiving unexpected parsing errors, and the validation process became fully automated.
Lessons learned: Relying validation on the persuasiveness of the model's (LLM) response is unacceptable in production.
The green check status should depend on the validation code, not on the absence of errors in generation.
Related concepts: Specification Gateway (Spec CI)
Canonical Scale (Recommendation)
Project scripts
Name: Secure integration with cloud infrastructure
Scenario: A developer wants to use Qwen Code to triage issues in a Kubernetes cluster and update tickets in Jira.
Challenge: Granting direct access through shell commands (!command) could lead to accidental deletion of resources in Kubernetes or token leaks in chat history.
Solution: Use of the "Frontier" level. Instead of direct access, an MCP server with a strict allowlist was deployed: Kubernetes tools were limited to read-only (get_pods, describe_logs), and explicit confirmation conditions were configured for Jira. Access tokens were hidden in environment variables and never ended up in QWEN.md.
Result: Qwen Code successfully helps diagnose failures and update tickets. The risk of accidentally executing destructive commands (e.g., deleting pods) was reduced to zero thanks to guardrails and the MCP architecture.
Lessons learned: Production APIs should not become unrestricted shell commands.
Prohibiting the transmission of secrets in prompts is critical for project security.
Related concepts: MCP (Model Context Protocol)
LLM Security
Guardrails
Study tips: Remember the main rule of validation: if the result depends on the model's opinion or response, it is not yet a production process. True validation must be entrusted to project scripts.
Always start with the "Standard". Do not try to immediately implement the "Frontier" (Kubernetes, orchestrators) if the basic built-in Qwen Code commands satisfy you.
Explore the structure of the .qwen/commands/ folder. Creating your own .md files with stopping rules is the fastest way to adapt Qwen Code to your processes.
When working with external services, always mentally design the MCP server: determine which actions are 'read-only' and which require 'rollback'.
Additional resources: Official qwen code documentation (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/
MCP (model context protocol) documentation: https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/
Official qwen code documentation (hooks): https://qwenlm.github.io/qwen-code-docs/en/users/features/hooks/
OWASP Top 10 for LLM applications (security): https://owasp.org/www-project-top-10-for-large-language-model-applications/
Google SRE book (for understanding orchestration principles): https://sre.google/sre-book/
Summary: Appendix B establishes a clear boundary between the built-in features of Qwen Code and the processes that the team must implement on their own. Using the Canonical Scale (Standard, Recommendation, Frontier) helps correctly assess the complexity of adoption. The key takeaway: Qwen Code is a powerful assistant, but at critical nodes (specification validation, file arbitration, security) the system must rely on deterministic project scripts and strictly configured guardrails via hooks and MCP servers.