Shadow Workspace & Git Worktrees

1. Обзор концепции и системная проблема

Когда автономный агент начинает изменять кодовую базу в активной директории разработчика, возникает критическое блокирование (Workflow Lockout). Если агент редактирует 25 файлов, компилирует код, устанавливает пакеты и запускает тесты, человек не может параллельно писать код, проверять свой локальный dev-сервер или переключать ветки: незакоммиченные изменения разработчика и агента неминуемо перемешиваются, вызывая конфликты.

Более того: если агент терпит неудачу, зависает или галлюцинирует, сброс рабочего дерева (git checkout -f или git clean) может случайно стереть незакоммиченную работу самого инженера.

Shadow Workspace (теневое рабочее пространство) на базе Git Worktrees решает эту проблему раз и навсегда. Агент получает полностью изолированную директорию на диске, привязанную к собственной ветке. Инженер продолжает писать код в своем любимом редакторе, пока фоновый агент параллельно выполняет сложный рефакторинг в теневом окружении без какого-либо влияния на активную рабочую станцию.

2. Архитектурная таксономия и ментальная модель

Архитектура взаимодействия с теневыми пространствами основана на распределении дисков и общей базе объектов Git:

┌─────────────────────────────────────────────────────────────┐
│                 SHARED REPOSITORY OBJECTS (.git)            │
└──────────────┬───────────────────────────────┬──────────────┘
               │                               │
               ▼                               ▼
┌─────────────────────────────┐ ┌─────────────────────────────┐
│  PRIMARY WORKSPACE (Human)  │ │ SHADOW WORKSPACE (AI Agent) │
│ • Branch: feature/payments  │ │ • Branch: agent/fix-auth    │
│ • Path: ~/projects/app      │ │ • Path: ~/.worktrees/task-42│
│ • Port: 3000 (Active)       │ │ • Port: 3001 (Isolated)     │
│ • Uncommitted local edits   │ │ • Automated ReAct Loop      │
└─────────────────────────────┘ └─────────────────────────────┘

1. Общее хранилище объектов (Single Object Database):
   • Все воркспейсы используют одну локальную базу Git-объектов (.git/objects). Нет необходимости повторно загружать гигабайты истории или делать медленный git clone.
2. Динамический агентский Worktree:
   • Создается за миллисекунды командой git worktree add -b <agent-branch> <shadow-path> <base-commit>.
   • Предоставляет агенту полностью чистое рабочее дерево без мусора и незавершенных правок человека.
3. Изоляция окружения (Environment Decoupling):
   • Собственные конфигурационные файлы окружения (.env.test), изолированные порты сети и собственные временные каталоги сборки.
4. Механизм слияния и очистки (Reconciliation & Cleanup):
   • После верификации и успешного прохождения тестов изменения оформляются как атомарный коммит, после чего теневой каталог безопасно удаляется (git worktree remove).

3. Технический пайплайн и внутренняя механика

Жизненный цикл задачи в теневом рабочем пространстве:

1. Инициация и выделение теневого пространства: Оркестратор (или разработчик через команду на подобие agy-run-in-worktree) генерирует уникальный ID задачи и создает каталог:

   git worktree add -b agent/auth-refactor ../shadow-auth main
   

2. Быстрое линкование зависимостей: Чтобы не ждать минутами выполнения npm install, оркестратор создает символические ссылки на общие node_modules или использует контентный кеш pnpm:

   ln -s $(pwd)/node_modules ../shadow-auth/node_modules
   

3. Автономная работа агента: Агент запускается с рабочей директорией Cwd = ../shadow-auth. Он самостоятельно:
   • Читает и редактирует файлы.
   • Запускает локальный сервер на изолированном порту (PORT=3005 npm run test:e2e).
   • Итерирует в ReAct-цикле до полного успеха.
4. Валидация результата: Все тесты проходят в теневом пространстве. Если агент испортил сборку, инженер не испытывает никаких проблем в своей основной IDE.
5. Фиксация и интеграция: Агент делает финальный коммит в ветку agent/auth-refactor. Оркестратор удаляет теневой каталог:

   git worktree remove ../shadow-auth
   

6. Презентация результата инженеру: Инженер видит сообщение о готовности задачи и может выполнить быстрый git merge или открыть PR.

4. Практические инженерные сценарии в продакшене

01. Параллельная разработка фичи без остановки работы разработчика

Инженер верстает новый экран настроек в ветке main:

• Одновременно запускает бэкграунд-агента для написания миграции базы данных и контроллеров в теневом пространстве.
• Агент запускает тесты, исправляет типы и готовит бэкенд-часть в изоляции.
• Инженер ни на секунду не прерывает верстку своего экрана.

02. Турнирное тестирование конкурирующих гипотез (Multi-Agent Bake-off)

Поиск самого быстрого алгоритма для обработки больших массивов данных:

• Оркестратор разворачивает три параллельные Worktrees: agent-a, agent-b, agent-c.
• Трем различным моделям (Claude 3.7 Sonnet, DeepSeek R1, GPT-4o) ставится одно задание оптимизации.
• Запускается бенчмарк; выбирается решение с наилучшим показателем latency, а два других воркспейса автоматически удаляются.

03. Безопасный запуск непроверенных агентских скриптов

Тестирование радикального обновления ядра системы:

• Если агент полностью сломает файловую структуру или сгенерирует неработоспособный код, разработчик просто удаляет директорию воркспейса за 1 секунду без страха повредить локальный Git-репозиторий.

5. Подводные камни, типовые ошибки и безопасность

• Конфликты занятых сетевых портов (Port Collisions): Если теневое рабочее пространство запускает тесты, которые неявно пытаются поднять веб-сервер на фиксированном порту 3000, они упадут с ошибкой EADDRINUSE, если этот порт занят разработчиком. Всегда настраивайте параметризацию портов.
• Блокировка веток (Worktree Branch Locks): Git запрещает монтировать одну и ту же ветку в двух разных Worktrees одновременно. Теневые агенты всегда должны работать в новых, уникальных ветках.
• Накопление дискового пространства: Если оркестратор аварийно завершает работу без шага очистки (git worktree remove), на диске могут оставаться десятки забытых папок репозитория. Периодически выполняйте git worktree prune.
• Утечка неподконтрольных файлов (.env.local): Файлы, находящиеся в .gitignore, не копируются автоматически в новый worktree. Агенту необходимо явно предоставить доступ к тестовым переменным окружения для корректного прохождения тестов.