Рабочее окружение разработчика: инструменты и локальный стенд

Новый инженер выходит в понедельник. В 9:30 он получает ноутбук и доступ к репозиторию, в 9:35 делает git clone. Дальше есть два сценария.

В первом он открывает README.md, выполняет три команды, и в 9:52 у него на localhost:8000 крутится приложение с наполненной тестовыми данными базой. К обеду он отправляет первый pull request с исправлением опечатки в тексте ошибки — не потому что это ценно само по себе, а потому что так он проверяет, что весь конвейер от его клавиатуры до ревью работает.

Во втором он открывает вики, находит страницу «Настройка окружения», обновлённую 14 месяцев назад. Ставит Python — не тот. Ставит PostgreSQL — не той мажорной версии. Через два часа упирается в библиотеку, которая не собирается на его архитектуре процессора, идёт в чат, и трое коллег по очереди вспоминают, что «у них тоже так было, надо было что-то поставить через brew». К среде он запускает приложение. Первый pull request — в пятницу.

Разница не в квалификации человека и не в его ноутбуке, а в том, считает ли команда локальное окружение частью продукта или личным делом каждого. Эта глава — про то, как сделать первое: слои окружения, версии рантайма, локальные внешние сервисы, единая точка входа, редактор и отладчик, инструменты проектирования и проверка всего этого в первый день нового человека.

Окружение как продукт: метрика — время от clone до running

У окружения есть одна честная метрика: сколько времени проходит от git clone до момента, когда приложение отвечает на запрос и по нему можно пройтись отладчиком. Назовём её TTFR — time to first run. Её можно замерить: посадите нового человека (или коллегу с чистой машины) и засеките.

Хорошие цифры для типичного веб-сервиса: 10–20 минут на машине, где уже стоят Git и Docker. Плохие: «полдня», «зависит», «спроси у Игоря». Ответ «зависит» — это уже диагноз: процесс не описан детерминированно. Почему метрика важна ровно настолько, насколько кажется:

• TTFR — верхняя оценка стоимости любого эксперимента. Если поднять окружение дорого, инженер не станет проверять гипотезу «а что если переписать этот кусок иначе» — он будет спорить в комментариях вместо того, чтобы измерить.
• TTFR — это стоимость подключения человека к задаче. Аварийная ситуация в пятницу вечером, нужен второй человек — а у него не собирается проект, потому что он последние три месяца работал в соседнем сервисе.
• TTFR деградирует сам. Каждая новая зависимость, каждый новый внешний сервис, каждая «временная ручная настройка» его увеличивают. Если его не измерять, через год окружение поднимает только тот, кто его строил.

Отсюда главный тезис главы: «у меня работает» — это дефект процесса, а не характер разработчика. Фраза означает буквально следующее: на двух машинах, которые должны быть одинаковыми, состояние разное, и никто не знает, чем именно. Это тот же класс проблемы, что и «тест падает через раз» — недетерминированность, у которой есть причина, и причину можно устранить. Взгляд на окружение как на внутренний продукт с пользователями-инженерами — предмет платформенной инженерии; там же разбирается, как это измерять на масштабе компании: Опыт разработчика: что измерять и Окружения.

Слои окружения

Окружение — не «набор программ», а стек слоёв, где каждый следующий зависит от предыдущего. Понимание слоёв нужно, чтобы правильно локализовать проблему: «не собирается» на слое зависимостей лечится совсем не так, как «не собирается» на слое рантайма.

Ключевое наблюдение: слои 1–3 обязаны быть описаны в репозитории, слой 5 — личное дело инженера. Версия Node — это контракт команды, потому что от неё зависит поведение кода. Выбор между Neovim и IntelliJ IDEA — не контракт, потому что на результат не влияет. Смешивать эти категории вредно в обе стороны: заставлять всех пользоваться одной IDE — бессмысленное принуждение; оставлять версию рантайма на усмотрение каждого — источник багов, которые воспроизводятся только у одного человека.

Управление версиями рантайма

Системный интерпретатор — ловушка. В macOS и большинстве дистрибутивов Linux Python и Perl — часть операционной системы: ими пользуются системные утилиты. Установка пакета глобально через sudo pip install в лучшем случае сломает ваш проект, в худшем — менеджер пакетов ОС. В Debian и Ubuntu это настолько частая беда, что появился PEP 668: системный Python теперь помечен как «externally managed» и просто отказывается ставить пакеты глобально.

Вторая проблема системного рантайма — вы не управляете его версией. Обновили ОС — уехал минор Python, и вместе с ним поведение какой-нибудь библиотеки. Третья — на одной машине живут несколько проектов, и им нужны разные версии.

Решение — менеджер версий: инструмент, который держит несколько рантаймов рядом и переключает их по контексту каталога.

Файл-манифест версии — это контракт, лежащий в репозитории рядом с кодом. Он делает две вещи: переключает версию автоматически при cd в каталог и служит единственным источником правды для CI. Если в .tool-versions написано nodejs 22.11.0, а сборка в CI использует Node 20 — это расхождение видно и лечится, а не всплывает в проде.

# .tool-versions в корне репозитория — читают и mise, и asdf
nodejs 22.11.0
python 3.12.7
golang 1.23.3

# После этого достаточно одной команды на новой машине:
mise install          # поставит ровно то, что записано в файле
node --version        # v22.11.0 — независимо от того, что стоит в системе

Отдельно про изоляцию зависимостей внутри одной версии рантайма. Python-виртуальные окружения (venv), node_modules в каталоге проекта, GOPATH/модульный кэш Go — всё это решает одну задачу: пакеты проекта A не должны быть видны проекту B. Правило простое: глобально ставим только менеджеры, всё остальное — локально в проект. Исключения — CLI-утилиты, не связанные с проектом (ripgrep, jq, gh); для Python их правильно ставить через pipx или uv tool install, которые кладут каждую утилиту в собственное окружение. Механику lock-файлов и разрешения версий подробно разбирает следующая глава.

Внешние зависимости локально: docker compose

Приложению почти никогда не нужен только рантайм: нужны база, кэш, иногда очередь и S3-совместимое хранилище. Три способа их получить:

1. Поставить на машину нативно. Быстро работает, но версия одна на все проекты, состояние копится годами, а на новой машине воспроизвести это состояние невозможно.
2. Поднять в контейнерах. Версия фиксируется в файле, состояние сбрасывается одной командой, на другой машине получится то же самое.
3. Ходить в общий стенд разработки. Соблазнительно, но означает, что вы не можете работать без сети, чужие эксперименты ломают ваши тесты, а ваши миграции ломают чужие.

Стандарт де-факто — второй вариант, и его язык — Docker Compose. Ниже рабочий файл для типичного сервиса: приложение, PostgreSQL, Redis, с healthcheck’ами и именованными томами.

# docker-compose.yml — локальный стенд разработки
services:
  db:
    # Тег с минором, а не latest: воспроизводимость важнее свежести
    image: postgres:16.4-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: devpassword   # локальный пароль, в прод не уезжает
      POSTGRES_DB: app_dev
    ports:
      - "5432:5432"                    # чтобы ходить psql/DBeaver с хоста
    volumes:
      - pgdata:/var/lib/postgresql/data
      # Скрипты отсюда выполняются один раз при создании тома
      - ./deploy/initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      # «Контейнер запущен» и «БД готова принимать запросы» — разные события,
      # между ними несколько секунд
      test: ["CMD-SHELL", "pg_isready -U app -d app_dev"]
      interval: 5s
      retries: 10
      start_period: 10s

  cache:
    image: redis:7.4-alpine
    command: ["redis-server", "--appendonly", "yes"]
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 10

  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: dev                      # multi-stage: отдельная стадия для разработки
    environment:
      DATABASE_URL: postgresql://app:devpassword@db:5432/app_dev
      REDIS_URL: redis://cache:6379/0
      LOG_LEVEL: debug
    ports:
      - "8000:8000"
      - "5678:5678"                    # порт отладчика
    volumes:
      # Код монтируем с хоста — правка в редакторе видна без пересборки образа
      - ./src:/app/src:cached
      # Анонимный том поверх, чтобы зависимости из образа не затирались хостовыми
      - /app/.venv
    depends_on:
      db:
        condition: service_healthy     # ждём именно готовности, а не старта
      cache:
        condition: service_healthy

volumes:
  pgdata:
  redisdata:

Три детали, которые отличают рабочий файл от скопированного из туториала:

• condition: service_healthy, а не голый depends_on. Без healthcheck Docker считает зависимость выполненной, как только процесс в контейнере стартовал. PostgreSQL к этому моменту ещё несколько секунд поднимает кластер, приложение падает на первом подключении, и появляются самодельные sleep 10 в entrypoint.
• Именованные тома, а не bind-mount для данных БД. Именованный том живёт под управлением Docker, переживает docker compose down и убивается явным docker compose down -v. Каталог с хоста для данных PostgreSQL на macOS и Windows ещё и заметно медленнее.
• Пины версий образов. postgres:latest сегодня и через полгода — разные мажорные версии с разным форматом данных.

Порядок событий при docker compose up полезно представлять целиком — именно здесь ломается большинство «у меня не поднимается».

Когда полноценный стенд не нужен

Поднимать весь прод-подобный набор сервисов на каждый запуск теста — дорого. Полезная градация:

Отдельный инструмент, который стоит знать: Testcontainers — библиотека, которая поднимает контейнеры из кода теста и гасит их после. Тест сам объявляет, что ему нужна PostgreSQL 16, получает случайный порт и чистую базу. Это снимает конфликт «тесты требуют, чтобы стенд был поднят заранее» и делает прогон в CI идентичным локальному. Подробнее про уровни и границы — Интеграционное тестирование; про образы, теги и реестры — Контейнеры и реестры.

Devcontainers и облачные окружения

Следующий шаг после «внешние сервисы в контейнерах» — сама разработка внутри контейнера. Спецификация Dev Containers описывает окружение файлом .devcontainer/devcontainer.json: базовый образ, установленные инструменты, расширения редактора, команды после создания. Поддерживают VS Code, JetBrains-семейство, GitHub Codespaces.

Что это даёт: TTFR падает почти до нуля, машина инженера остаётся чистой, версии инструментов одинаковы у всех, включая CI. Что это стоит: заметный оверхед файловой системы на macOS и Windows (код в контейнере через виртуализацию медленнее), сложность отладки «внутри двух слоёв», часть привычных инструментов остаётся снаружи. Облачные варианты — GitHub Codespaces и Gitpod — добавляют мощную машину под рукой и независимость от ноутбука, но стоят денег помесячно и требуют устойчивого интернета: в поезде вы не работаете. Разумная позиция: описывать окружение через devcontainer полезно почти всегда (это исполняемая документация), а вот запускаться внутри него — по желанию инженера.

Единая точка входа: Makefile, task, just

Даже идеально настроенное окружение бесполезно, если команды для работы с ним лежат в голове или в вики. Проблема документации в том, что она не ломается, когда устаревает — просто тихо врёт. Скрипт ломается сразу и громко, поэтому его чинят. Отсюда правило: любое повторяющееся действие должно иметь одно короткое имя. Инструмент почти не важен — GNU Make, Task, just, npm-скрипты. Важно, что make test работает в любом репозитории компании и означает одно и то же.

# Makefile — единственная точка входа в проект.
# Правило: то, что делает CI, должно вызываться теми же целями.
.DEFAULT_GOAL := help
SHELL := /bin/bash
COMPOSE := docker compose

.PHONY: help setup dev down test lint fmt migrate seed psql logs clean

help: ## Показать доступные команды (список строится из комментариев ниже)
	@grep -E '^[a-z-]+:.*?## ' $(MAKEFILE_LIST) | sed 's/:.*## /\t/'

setup: ## Первый запуск на чистой машине
	mise install                      # рантаймы из .tool-versions
	uv sync --frozen                  # зависимости строго из lock-файла
	cp -n .env.example .env || true   # локальный конфиг, .env в .gitignore
	$(COMPOSE) build
	$(MAKE) migrate seed

dev: ## Поднять стенд и приложение
	$(COMPOSE) up --detach --wait     # --wait ждёт healthy, а не просто старта
	@echo "http://localhost:8000"

down: ## Погасить стенд, данные сохранить
	$(COMPOSE) down

test: ## Прогнать тесты так же, как это делает CI
	$(COMPOSE) run --rm app pytest -q --maxfail=1

lint: ## Статические проверки
	uv run ruff check src tests
	uv run mypy src

fmt: ## Отформатировать код
	uv run ruff format src tests

migrate: ## Применить миграции
	$(COMPOSE) run --rm app alembic upgrade head

seed: ## Загрузить демо-данные
	$(COMPOSE) run --rm app python -m app.seed

psql: ## Открыть psql в контейнере с базой
	$(COMPOSE) exec db psql -U app -d app_dev

clean: ## Снести всё, включая данные
	$(COMPOSE) down --volumes --remove-orphans

Цель help с автогенерацией из комментариев — маленький, но важный приём: make без аргументов показывает список возможностей, и человеку не надо читать сам файл. Эти же цели вызываются из конвейера, поэтому «локально прошло, в CI упало» становится редкостью — подробнее в главах Качество в потоке и CI/CD.

Работа с базой данных из окружения разработчика

Классификация СУБД по модели данных и способу доступа — тема слоя данных и трека databases. Здесь нас интересует только инструментальная часть: чем инженер трогает базу каждый день.

• CLI-клиент. psql для PostgreSQL, mysql, redis-cli, mongosh. Незаменим по двум причинам: он есть в любом контейнере и он единственный, что доступен на проде через bastion. Стоит выучить хотя бы \dt, \d+ table, \timing, \x в psql.
• GUI-клиент. DBeaver (бесплатный, универсальный, на Java), DataGrip от JetBrains, pgAdmin для PostgreSQL, встроенные клиенты IDE. Ценность GUI не в кликах, а в просмотре плана запроса, диаграмме связей и быстром сравнении схем двух окружений.
• Локальная БД в контейнере. Правило: мажорная версия локально совпадает с продовой. Различия между PostgreSQL 14 и 16 в планировщике вполне достаточны, чтобы запрос вёл себя по-разному.
• Миграции. Схема БД живёт в репозитории как код: Alembic, Flyway, Liquibase, golang-migrate, миграции ORM. Ручное «зайти и добавить колонку» ломает воспроизводимость мгновенно.
• Сиды и фикстуры. Пустая база — плохой стенд: на ней не видно ни производительности, ни граничных случаев. Полезно держать скрипт seed, который создаёт реалистичный набор: пользователя-администратора, обычного пользователя, десяток сущностей в разных состояниях. Копировать прод-дамп нельзя — это персональные данные (см. Приватность и комплаенс); правильный путь — генератор синтетики или обезличенный дамп.

Про выбор конкретной СУБД под задачу — Выбор и миграция, про PostgreSQL как рабочую лошадку — отдельная глава, про Redis в роли кэша — здесь.

Редактор и IDE: в чём разница по существу

Спор «IDE против редактора» обычно ведут не о том: разница не в подсветке синтаксиса и не в количестве кнопок, а в том, есть ли у инструмента модель проекта. Текстовый редактор видит файл как последовательность символов: ищет подстроку, подсвечивает по регулярным выражениям, дополняет словами из буфера. IDE строит индекс — парсит исходники, разрешает импорты, знает типы, знает, что вот этот user есть экземпляр класса User из models/user.py и что метод save переопределён в трёх наследниках. Из наличия индекса вытекает всё остальное:

LSP и DAP стёрли границу. До 2016 года каждая IDE реализовывала понимание каждого языка сама — отсюда и рынок из десятка продуктов, где каждый был хорош ровно в своём языке. Microsoft вынесла эту логику в отдельный процесс и стандартизировала протокол общения: Language Server Protocol для навигации, дополнения и рефакторинга, Debug Adapter Protocol — для отладки. Теперь один языковой сервер (gopls, rust-analyzer, pyright, clangd) обслуживает VS Code, Neovim, Emacs, Helix и Zed одинаково.

Практическое следствие: Vim с настроенным LSP сегодня — это IDE, а VS Code без языкового сервера — подсвеченный блокнот. Выбор инструмента перестал определять доступные возможности и стал вопросом эргономики. Что честно осталось за коммерческими IDE (прежде всего за семейством JetBrains): глубокий автоматический рефакторинг с анализом всего проекта, работа с большими корпоративными кодовыми базами на Java/C#, интегрированные профайлер и клиент БД, отладка сложных сценариев вроде удалённых JVM. Разбор — JetBrains и VS Code.

Критерии выбора

1. Ваша ОС. Кроссплатформенность нужна не вам лично, а команде: если половина на macOS, а половина на Linux, инструкции должны работать у всех.
2. Основной язык. Для Java/Kotlin и C# специализированная IDE даёт заметный выигрыш. Для Go, Python, TypeScript разница с хорошо настроенным редактором невелика.
3. Размер репозитория. На проекте в миллион строк скорость индексации становится главным критерием — редактор, который «думает» три секунды на каждое дополнение, отравляет день.
4. Командная работа. Общие настройки форматирования и линтинга должны жить в репозитории (.editorconfig, конфиг форматтера), а не в настройках IDE каждого.
5. Цена и лицензия. Здесь всё меняется слишком быстро, чтобы приводить числа: смотрите актуальный прайс вендора. Важнее знать, что бесплатные варианты (VS Code, Neovim, Community-редакции JetBrains, Apache NetBeans, Eclipse) закрывают большинство задач.

Честная актуализация ландшафта

Обзоры «10 лучших IDE» стареют быстрее, чем кажется. Состояние на сегодня:

• Atom — архивирован GitHub 15 декабря 2022 года. Его наследие живо иначе: Atom дал миру Electron, а его команда во многом сделала VS Code возможным. Использовать сегодня нельзя — обновлений безопасности нет.
• Brackets — Adobe прекратила поддержку в 2021 году, передав проект сообществу; развитие фактически остановилось. Живая замена для фронтенда — VS Code с расширениями.
• Komodo IDE — ActiveState прекратила коммерческое развитие в 2022 году.
• AngularJS (первый Angular, не путать с современным Angular) — официальная поддержка закончилась 31 декабря 2021 года. Упоминания «поддержка AngularJS» в описаниях инструментов — признак устаревшего текста.
• NetBeans живёт как проект Apache, Eclipse — как основа множества корпоративных инструментов, Sublime Text развивается, Vim/Neovim и Emacs переживут нас всех.

Полноценное сравнение живых инструментов — трек editors: обзор, сравнение, легаси-среды, современные редакторы, навигация по коду.

Терминал как часть окружения

Терминал — не «для тех, кто не осилил кнопки». Это единственный интерфейс, который одинаков на вашем ноутбуке, в контейнере, на сервере и в CI. Что стоит настроить один раз:

• Оболочка и история. Zsh или fish с поиском по истории (Ctrl+R, а лучше fzf поверх неё). Половина повторяющихся команд уже есть в истории.
• Быстрый поиск и навигация. ripgrep (rg) уважает .gitignore и на порядок быстрее grep -r; связка rg --files | fzf заменяет диалог «открыть файл», а zoxide даёт z api вместо cd ~/work/company/services/api.
• Мультиплексор. tmux или Zellij: сессия переживает закрытие терминала и обрыв SSH.
• dotfiles под Git. Конфиги оболочки, редактора, Git — в отдельном репозитории со скриптом установки. Переезд на новую машину превращается из дня в десять минут. Это ровно та же идея воспроизводимости, что и для проекта, применённая к себе.

Практика повседневной работы в терминале разобрана в Терминал и рабочий процесс, автоматизация редактора — в Автоматизация в редакторе, а Git-часть окружения — в Контроле версий и хуках.

Инструменты проектирования и дизайна

Инженер рисует не потому, что любит рисовать, а потому что схема — самый дешёвый способ обнаружить, что участники разговора имели в виду разные вещи.

Свободные схемы. draw.io / diagrams.net — бесплатный редактор с настольной версией и хранением файлов где угодно, включая репозиторий: формат .drawio можно положить рядом с кодом. Excalidraw хорош там, где нужна нарочито черновая, «на салфетке» картинка — она не выглядит окончательным решением и потому провоцирует обсуждение.

Figma. Стандарт для интерфейсного дизайна, и инженеру важно понимать, что именно оттуда приходит:

• Прототип — кликабельная сборка экранов со связями и переходами. Из него видно поведение, которого нет на статичном макете: что происходит при пустом списке, при ошибке, при загрузке. Требуйте прототип, а не картинку.
• Компоненты — переиспользуемые элементы: главный компонент и его экземпляры, правка главного расходится по всем. Это прямой аналог компонентов в коде, и если дизайн-система в Figma собрана из компонентов, её реально отобразить в библиотеку UI один в один.
• Совместное редактирование и комментарии — обсуждение привязано к конкретному элементу, а не к строке в чате. Вопрос «что тут при ошибке валидации?» остаётся рядом с местом, к которому относится.
• История версий — Figma сама сохраняет срезы, версии можно называть и восстанавливать. Это отвечает на вопрос «мы делаем по вчерашнему макету или по позавчерашнему».

Про то, как прототип встраивается в работу с требованиями, — Прототипирование.

Diagram-as-code — нынешний стандарт для технических схем. Схема, описанная текстом, лежит в репозитории, проходит ревью в том же pull request, что и код, и меняется вместе с ним; схема в облаке через год оказывается ссылкой на аккаунт уволившегося сотрудника.

Практическое правило: схема без текста бесполезна, а текст без схемы — часто тоже. Как выбирать тип диаграммы и что писать рядом — Диаграммы в документации; формальные нотации — UML и BPMN.

Карта инструментов инженера

Отладка как навык

Отладчик — самый недооценённый инструмент в списке. Типичный цикл «добавил print, перезапустил, посмотрел, добавил ещё print» стоит минуты на итерацию. Точка останова даёт весь стек, все локальные переменные и возможность выполнить произвольное выражение в контексте — за один запуск.

Три способа увидеть, что происходит, и границы их применимости:

Отладчик умеет больше, чем «шаг вперёд»: условные точки останова (i == 9999), точки останова на исключении, watch за изменением переменной, изменение значения на лету, обратная отладка в некоторых средах. Условная точка останова заменяет if x == target: import pdb; pdb.set_trace() и не требует правки кода. Метод, который работает всегда, — бинарный поиск причины. Баг живёт между известным «здесь ещё хорошо» и «здесь уже плохо». Каждая проверка делит этот отрезок пополам: по коду (данные на входе функции корректны?), по времени (когда это сломалось — git bisect), по конфигурации (отключаем половину флагов). Логарифм — ваш друг: 1024 коммита проверяются за 10 шагов.

Воспроизводимый минимальный пример — не формальность, а инструмент. Пока вы сокращаете сценарий до минимума, вы либо находите причину сами (чаще всего), либо получаете артефакт, который можно приложить к issue или показать коллеге. Правило: если баг не воспроизводится командой, его нельзя считать исправленным — вы не сможете проверить исправление.

База по чтению ошибок и стектрейсов — Ошибки и отладка; когда «баг» на самом деле про скорость, начинать надо с измерения, а не с догадок — Измерение производительности.

Онбординг: первый день как тест окружения

Проверить окружение можно только одним способом — прогнать через него человека, который его не строил. Отсюда полезная практика: каждый новый инженер проходит README дословно и правит всё, что не сработало, в тот же день. Это его первый pull request и лучший вклад, который он может сделать. Дальше — усиление: README, который проверяется CI. Если инструкции по настройке представляют собой не прозу, а вызовы make setup && make test, отдельная задача в конвейере запускает их на чистом раннере. Инструкция сломалась — билд красный, а не «через полгода выяснилось».

Две критические точки на этой диаграмме — make dev и первый merge. Если стенд не поднялся до обеда, день потерян и человек начинает сомневаться в себе вместо того, чтобы сомневаться в процессе. Если PR не влился в первый день, инженер не узнал, как в этой команде вообще происходит доставка изменений.

Как писать README, который выдерживает такую нагрузку, — README; организационная сторона первых недель — Онбординг и Первые 90 дней.

Типичные ошибки

• Инструкция в вики вместо скрипта. Документ не выполняется, значит, никто не узнает, что он устарел. Всё, что можно выполнить, должно быть кодом; проза остаётся для объяснения «почему», а не «как».
• Глобальные пакеты. sudo pip install, npm install -g для библиотек проекта, системный PostgreSQL «чтобы быстрее». Через три проекта машина превращается в уникальный артефакт, который невозможно воспроизвести.
• Разъезд версий между локалью и CI. Локально Node 22, в конвейере Node 20, в проде образ с Node 18. Симптом — «в CI падает, локально работает». Лечится единственным источником версий, который читают все.
• Стенд, который не поднимается локально. «Тестируем сразу на dev-стенде» означает очередь из инженеров на один стенд, взаимное блокирование и невозможность отладки. Это чинится приоритетно, потому что отравляет всё остальное.
• docker compose без healthcheck. Приводит к sleep 15 в entrypoint и гонкам, которые воспроизводятся у одного человека раз в неделю.
• Секреты в .env, закоммиченном в репозиторий. Самая дорогая ошибка списка. .env — в .gitignore, в репозитории лежит .env.example с ключами и пустыми значениями. Реальные секреты — в менеджере секретов; локальные — заведомо ненастоящие. Git помнит всё: удаление файла следующим коммитом ничего не удаляет, ключ надо ротировать. См. Управление секретами и Окружения, конфигурация и секреты.
• Идеальное окружение, которое строит один человек. Если make setup понимает только его автор, это не автоматизация, а новая точка отказа. Проверка простая: работает ли это на машине коллеги.
• Прод-дамп на ноутбуке. Удобно и незаконно. Синтетика или обезличивание — единственный приемлемый путь.

Мини-итог

• У окружения есть измеримая метрика — время от git clone до работающего приложения с отладчиком. Меряйте её на новых людях, а не на себе.
• Слои 1–3 (рантайм, зависимости, внешние сервисы) описываются файлами в репозитории; слой инструментов — личное дело инженера. Версия рантайма фиксируется манифестом (.tool-versions, .nvmrc) и читается одинаково локально и в CI, а системный интерпретатор трогать нельзя.
• Внешние сервисы поднимаются docker compose с healthcheck’ами и condition: service_healthy. Testcontainers — там, где стенд нужен только тестам.
• Единая точка входа (make setup, make dev, make test) переживает документацию, потому что ломается громко.
• Разница IDE и редактора — не подсветка, а индекс проекта; LSP и DAP сделали эту разницу вопросом настройки, а не бренда.
• Схемы живут рядом с кодом как текст. Figma даёт прототип, компоненты и историю версий; diagram-as-code даёт проверяемость и жизнь в ревью.
• Отладчик, логи и трассировка решают разные задачи; бинарный поиск причины работает всегда.
• Первый день нового человека — самый честный тест окружения. Если он в него не проходит, чините окружение, а не человека.

Что дальше

Сборка и зависимости — что происходит между исходником и артефактом: менеджеры пакетов, lock-файлы, разрешение версий, воспроизводимая сборка и жизнь с чужим кодом.

Источники

• Dev Containers Specification, Docker Compose file reference, Testcontainers
• Language Server Protocol и Debug Adapter Protocol
• PEP 668 — Externally Managed Environments, mise
• The Twelve-Factor App — принцип паритета окружений; C4 model