# Часть 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 запускают оболочку в той же сессии, и это удобно для быстрых проверок. Но решения о слиянии и коммите принимайте, глядя в отдельное окно проверки, где никаких побочных действий агента быть не может.

## Языковые серверы (LSP) при работе вне IDE

Когда агент работает из терминала без открытой IDE, теряется информация, которую обычно даёт редактор: типы, переходы к определению, осмысленные автодополнения. Без этого агент чаще опирается на догадки об именах и сигнатурах. Языковые серверы (LSP, Language Server Protocol) возвращают эти данные в рабочий процесс: проверку типов в реальном времени, go-to-definition и автодополнения, основанные на реальном коде, а не на предположениях.

- Идея переносима между инструментами: к рабочему процессу агента подключается LSP-интеграция для нужного языка (например, для TypeScript или Python), и агент получает те же подсказки, что и в IDE.
- Это общая практика, а не родная функция Qwen Code. В экосистеме Claude Code она оформлена как отдельные LSP-плагины (`typescript-lsp`, `pyright-lsp`); здесь описывается как приём, который вы переносите в своё окружение и помечаете соответственно, не выдавая за встроенную возможность Qwen Code.
- Свяжите LSP с проверками типов перед коммитом и пушем: подсказки сервера в ходе работы и финальный `npm run typecheck` в окне проверки решают разные задачи — первый предупреждает ошибки на лету, второй подтверждает их отсутствие перед слиянием.

## Установка Qwen Code

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

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

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

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

```bash
brew install qwen-code
qwen --version
```

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

```bash
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.

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

```bash
qwen
/auth
```

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

```bash
qwen auth
qwen auth status
```

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

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

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

```bash
mkdir -p .qwen
```

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

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

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

```bash
export BAILIAN_API_KEY="..."
```

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

```json
{
  "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` коротким и ссылаться на спецификации.

Пример:

```markdown
# 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

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

```text
/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/.

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

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

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

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

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

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

## Практика

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

```bash
qwen
```

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

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

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

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