Part 4. Environment Setup

SDD is IDE-agnostic: the process can be carried out in any environment that can work with files and shell commands. The primary tool in this tutorial is Qwen Code CLI. It runs in the terminal inside a repository and works with files, shell commands, project settings, skills, and MCP.

Terminal Windows

It is most convenient to keep at least two windows (or two tabs/panes in tmux):

1. Qwen Code Window. This is where qwen runs in interactive mode; you communicate with the agent and read its reports.
2. Verification Window. This is where you manually run git status, git diff, npm run typecheck, npm test, curl. This window is needed to double-check the agent's outputs, rather than taking them at its word.

Commands via ! inside Qwen Code launch a shell in the same session, which is convenient for quick checks. But make merge and commit decisions by looking at a separate verification window where no side effects from the agent can occur.

Installing Qwen Code

Check the current documentation before installation. At the time this material was prepared, the official repository indicates Node.js 22+ for manual installation.

Option via npm:

npm install -g @qwen-code/qwen-code@latest
qwen --version

Option via Homebrew:

brew install qwen-code
qwen --version

Qwen Cloud also publishes an installation script for users in the Alibaba Cloud / DashScope region. Use it only if this distribution channel suits you, and verify the current flags with the README of the Qwen Code repository — the call below may be outdated:

bash -c "$(curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh)"

Authentication

As of May 2026, the free Qwen OAuth tier is no longer a reliable option: official Qwen Code materials state that the free tier was discontinued on April 15, 2026. The practical path is an API key or Alibaba Cloud Coding Plan.

Interactive setup:

qwen
/auth

Or via a separate command:

qwen auth
qwen auth status

Do not put keys in QWEN.md, AGENTS.md, specifications, or Git. Use environment variables or .qwen/settings.json with references to them.

Minimal .qwen/settings.json

Create a project configuration:

mkdir -p .qwen

Example without secrets:

{
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3-coder-plus"
  },
  "$version": 3
}

If you are using an OpenAI-compatible endpoint, store the key in an environment variable:

export BAILIAN_API_KEY="..."

And reference the variable in settings:

{
  "env": {
    "BAILIAN_API_KEY": "$BAILIAN_API_KEY"
  },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "baseUrl": "https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
        "envKey": "BAILIAN_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "qwen3-coder-plus"
  },
  "$version": 3
}

QWEN.md as Project Persistent Memory

Qwen Code reads QWEN.md at the start of a session. If the project already has AGENTS.md, Qwen may also use it, so do not duplicate the same content. For SDD, it is convenient to make QWEN.md short and reference the specifications.

Example:

# QWEN.md

This project uses SDD.

Rules:
- Do not implement product features until there is a specification for them.

- Source of truth about the product: @specs/mission.md, @specs/tech-stack.md, and @specs/roadmap.md.
- For each feature branch, a folder @specs/YYYY-MM-DD-feature-name/ with requirements.md, plan.md, and validation.md is needed.
- Before writing files for a new specification, ask the human about boundaries, decisions, and context.
- Make only targeted changes. Do not refactor unrelated code.
- Always report which files you changed and which verification commands you ran.

Main commands:
- npm run typecheck
- npm test
- npm run dev

Qwen Code Commands Needed for SDD

Inside an interactive session:

/help
/auth
/model
/clear
/context
/compress
/summary
/resume
/stats
/skills
/memory
/init
/remember
/forget
/dream
/review

/remember, /forget, and /dream relate to Qwen Code's built-in memory and are covered in detail in part 19. /review is a built-in change review (if supported by your version). For the full list and exact semantics, check the documentation: https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/.

Working with files:

@README.md Briefly describe the project's intent.
@specs/roadmap.md What is the next uncompleted phase?

Shell commands:

!git status
!npm test
!rg "TODO|FIXME" .

Headless mode for automation:

qwen -p "Read @specs/roadmap.md and name the next uncompleted phase. Do not modify files."

Practice

1. Install Qwen Code.
2. Set up authentication.
3. In the tutorial project, create .qwen/settings.json.
4. Create QWEN.md.
5. Run:

qwen

Then enter:

Read @QWEN.md and @README.md.
Tell me if this repository is ready for creating an SDD constitution.
Do not write files.

Review Questions

1. How is QWEN.md different from specs/mission.md?
2. Why can't API keys be stored in specifications?
3. When should you use qwen -p, and when interactive qwen?