Shadow Workspace & Git Worktrees(Тіньові робочі простори та 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. Агенту необхідно явно надати доступ до тестових змінних середовища для коректного проходження тестів.