nifodea/.agent/src/PROTOCOLS/04_ENVIRONMENT_SETUP.md

Протокол 04: Настройка окружения (SETUP)

Цель

Обеспечить рабочее окружение, в котором исполнительный агент может сразу выполнять задачи.

Вход

• .agent/analysis-report.md
• .agent/design-report.md (опционально, для greenfield)
• .agent/task-manifest.json
• .agent/checkpoints.json (фаза environment: pending)

Поведение в зависимости от типа проекта

Фаза SETUP работает по-разному для existing и greenfield/scaffold проектов.

---

Ветка A: existing/scaffold проект

4A.1. Зависимости

• Установить все зависимости согласно документации проекта
• Если есть requirements.txt, pyproject.toml, package.json, Cargo.toml и т.д. — выполнить установку
• Если в проекте используется виртуальное окружение (venv, .venv, conda) — активировать или создать
• Если в проекте используется Docker — проверить, что образ собирается

Правило: если установка зависимостей требует нестандартных шагов, описанных в README — строго следовать им. Если шаги не описаны — запросить у пользователя.

4A.2. Конфигурация

• Проверить наличие конфигурационных файлов (.env.example, .env, config.yaml)
• Если есть .env.example, скопировать в .env с настройками по умолчанию
• Если проекту требуется БД — проверить строку подключения, при необходимости создать БД или использовать SQLite для разработки
• Настроить pre-commit хуки, если они есть в проекте

4A.3. Линтеры и форматтеры

• Запустить линтер на всём проекте: записать результат
• Если линтер выдаёт ошибки — не исправлять, только зафиксировать в отчёте
• Убедиться, что исполнительный агент может запускать линтер (записать команду)

4A.4. Baseline-тесты

• Запустить все тесты проекта
• Записать в .agent/baseline-test-report.log:
  • Команда запуска
  • Общее количество тестов
  • Пройдено / упало / пропущено
  • Время выполнения
  • Список упавших тестов (если есть)
• Если тесты не проходят — указать это в отчёте, но не исправлять

4A.5. Сборка проекта

• Выполнить полную сборку/компиляцию проекта
• Записать результат (успех/ошибка с логом)
• Сборка должна проходить без ошибок. Если не собирается — остановиться, сообщить пользователю.

---

Ветка B: greenfield проект

4B.1. Инициализация проекта

• Создать базовую структуру директорий согласно design-report.md
• Инициализировать пакетный менеджер:
  • Python: pyproject.toml (poetry, pdm, hatch) или requirements.txt
  • Node: package.json и npm init / yarn init
  • Go: go mod init
  • Rust: cargo init
• Настроить базовый конфиг: .env.example, config/ и т.д.
• Настроить линтер/форматтер: ruff, eslint, gofmt и т.д.

4B.2. Scaffold-код

Создать пустые заглушки для модулей, описанных в design-report:

# app/services/cashflow.py — заглушка
class CashflowService:
    """TBD — реализация в задаче T3"""
    pass

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

4B.3. Установка зависимостей

• Установить базовые зависимости согласно стеку из design-report
• Если проект использует БД — установить драйвер/ORM
• Если проект использует API — установить фреймворк (FastAPI, Express и т.д.)
• Установить dev-зависимости: линтер, тестовый раннер, type stubs

4B.4. Базовые тесты (scaffold)

• Создать пустой тестовый файл для каждого модуля
• Настроить тестовый раннер (pytest, jest и т.д.)
• Записать в .agent/baseline-test-report.log: "0 tests — greenfield, scaffold готов"

4B.5. Проверка сборки

• Убедиться, что проект импортируется без ошибок
• Убедиться, что линтер проходит (без кода он должен проходить)
• Убедиться, что тестовый раннер запускается (0 tests, exit code 0)

---

Выход

• Работоспособное окружение / инициализированный проект
• .agent/baseline-test-report.log — результат прогона тестов
• .agent/setup-report.log — лог установки зависимостей и сборки

Обновить checkpoints.json: phases.environment = "completed".

Критерии завершения фазы

• Зависимости установлены / проект инициализирован
• Проект собирается / импортируется без ошибок
• Baseline-тесты запущены, результат записан
• .agent/baseline-test-report.log и .agent/setup-report.log созданы
• checkpoints.json обновлён

Если проект не собирается — фаза считается проваленной, checkpoints.json отмечает phases.environment = "failed", управление возвращается пользователю.