Часть 4. Настройка окружения

SDD не зависит от IDE: процесс можно вести в любой среде, которая умеет работать с файлами и командами оболочки. В этом учебнике основной инструмент — Qwen Code CLI. Он запускается в терминале внутри репозитория и работает с файлами, командами оболочки, настройками проекта, навыками и MCP.

Окна терминала

Удобнее всего держать минимум два окна (или две вкладки/панели tmux):

1. Окно Qwen Code. В нём запущен qwen в интерактивном режиме; вы общаетесь с агентом, читаете его отчёты.
2. Окно проверки. В нём вы вручную запускаете git status, git diff, npm run typecheck, npm test, curl. Это окно нужно, чтобы перепроверять выводы агента, а не доверять им на слово.

Команды через ! внутри Qwen Code запускают оболочку в той же сессии, и это удобно для быстрых проверок. Но решения о слиянии и коммите принимайте, глядя в отдельное окно проверки, где никаких побочных действий агента быть не может.

Установка Qwen Code

Проверьте актуальную документацию перед установкой. На момент подготовки этих материалов официальный репозиторий указывает Node.js 22+ для ручной установки.

Вариант через npm:

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

Вариант через Homebrew:

brew install qwen-code
qwen --version

Qwen Cloud также публикует установочный скрипт для пользователей региона Alibaba Cloud / DashScope. Используйте его только если вам подходит этот канал распространения, и сверьте актуальные флаги с README репозитория Qwen Code — нижеуказанный вызов может устареть:

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

Аутентификация

По состоянию на май 2026 года бесплатный тариф Qwen OAuth больше не является надёжным вариантом: официальные материалы Qwen Code сообщают, что бесплатный тариф был прекращён 15 апреля 2026 года. Практичный путь — API-ключ или Alibaba Cloud Coding Plan.

Интерактивная настройка:

qwen
/auth

Или через отдельную команду:

qwen auth
qwen auth status

Не кладите ключи в QWEN.md, AGENTS.md, спецификации или Git. Используйте переменные окружения или .qwen/settings.json со ссылками на них.

Минимальный .qwen/settings.json

Создайте проектную конфигурацию:

mkdir -p .qwen

Пример без секретов:

{

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

Если используете OpenAI-совместимую конечную точку, храните ключ в переменной окружения:

export BAILIAN_API_KEY="..."

А в настройках ссылайтесь на переменную:

{
  "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 как постоянная память проекта

Qwen Code читает QWEN.md при старте сессии. Если в проекте уже есть AGENTS.md, Qwen тоже может использовать его, поэтому не дублируйте одно и то же. Для SDD удобно сделать QWEN.md коротким и ссылаться на спецификации.

Пример:

# QWEN.md

В этом проекте используется SDD.

Правила:
- Не реализуй продуктовые фичи, пока для них нет спецификации.

- Источник правды о продукте: @specs/mission.md, @specs/tech-stack.md и @specs/roadmap.md.
- Для каждой ветки фичи нужна папка @specs/YYYY-MM-DD-feature-name/ с requirements.md, plan.md и validation.md.
- Перед записью файлов новой спецификации спроси человека о границах, решениях и контексте.
- Вноси только точечные изменения. Не рефакторь несвязанный код.
- Всегда сообщай, какие файлы изменил и какие команды проверки запускал.

Основные команды:
- npm run typecheck
- npm test
- npm run dev

Команды Qwen Code, которые нужны для SDD

Внутри интерактивной сессии:

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

/remember, /forget и /dream относятся к встроенной памяти Qwen Code и подробно разбираются в части 19. /review — встроенный обзор изменений (если поддерживается вашей версией). Полный список и точную семантику сверяйте с документацией: https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/.

Работа с файлами:

@README.md Кратко опиши намерение проекта.
@specs/roadmap.md Какая следующая незавершённая фаза?

Команды оболочки:

!git status

!npm test
!rg "TODO|FIXME" .

Режим без интерфейса для автоматизации:

qwen -p "Прочитай @specs/roadmap.md и назови следующую незавершённую фазу. Файлы не изменяй."

Практика

1. Установите Qwen Code.
2. Настройте аутентификацию.
3. В учебном проекте создайте .qwen/settings.json.
4. Создайте QWEN.md.
5. Запустите:

qwen

Затем введите:

Прочитай @QWEN.md и @README.md.
Скажи, готов ли этот репозиторий к созданию конституции SDD.
Файлы не записывай.

Контрольные вопросы

1. Чем QWEN.md отличается от specs/mission.md?
2. Почему API-ключи нельзя хранить в спецификациях?
3. Когда использовать qwen -p, а когда интерактивный qwen?