Agent Workspace для AI coding agents: как разделить материалы, рабочие папки и артефакты

Agent workspace для AI coding agents — это управляемая рабочая среда, где агент получает материалы проекта, отдельную папку для задачи и место для передачи результатов. Его не стоит делать как одну общую директорию, куда все агенты читают и пишут без правил. Такая схема быстро смешивает контекст, временные файлы, результаты, доступы и следы работы.

Рабочая модель лучше разделяет четыре вещи: материалы для чтения, рабочее пространство задачи, артефакты выполнения и технические границы доступа. Материалы и процедуры обычно должны быть read-only и версионироваться. Изменения агент делает в отдельном project workspace, worktree или sandbox. Результаты передаются через shared artifacts и handoff summaries. Доступ к файловой системе ограничивается через MCP roots, permissions, audit trail и human review.

Эта страница не про то, что писать в AGENTS.md или SKILL.md. Для этого есть отдельная практика про Markdown, Skills и MCP. Здесь фокус другой: как организовать рабочую среду для нескольких агентов так, чтобы они не портили общий контекст, не перетирали файлы друг друга и не получали лишние полномочия.

Отдельный Agent Materials Workspace нужен, когда coding agent работает не как личная подсказка в IDE, а как участник командного процесса: читает документацию, меняет код, запускает проверки, готовит артефакты и передаёт результат человеку или другому агенту.

Он особенно полезен, если:

• с проектом работают несколько агентов или несколько разработчиков с разными агентами;
• агенту нужны общие инструкции, runbooks, шаблоны, примеры pull request и правила ревью;
• часть материалов должна быть общей, но править её можно только через review;
• задачи запускаются параллельно и не должны конфликтовать на уровне файлов;
• результаты работы нужно передавать дальше как отчёт, diff, JSON, лог, summary или пакет проверки;
• есть требования к секретам, доступам, внешней сети, shell-командам и audit trail.

Если агент используется только для локальной подсказки одному разработчику, обычно достаточно AGENTS.md, настроек IDE и ручного review. Если агент работает в background/cloud-режиме, получает MCP-доступы или запускает задачи параллельно, workspace-модель лучше спроектировать до пилота.

Смысл Agent Materials Workspace — не в новом названии папки, а в разделении ответственности. У каждого слоя должна быть своя роль, owner и правило изменения.

Такое разделение помогает обсуждать не “дать агенту папку”, а конкретные границы: что он читает, где пишет, как отдаёт результат и кто утверждает изменения в общих материалах.

Read-only materials — это материалы, которые агент должен использовать как источник контекста, но не должен менять в процессе обычной задачи. Они могут жить в основном репозитории, отдельном agent-materials repo, документационном хранилище или подключаться через MCP.

Правка shared materials должна идти через PR, owner review или отдельный promotion-процесс. Если агент нашёл полезное правило во время задачи, он может предложить изменение как артефакт, но не должен сам молча менять общий источник истины.

Писать агенту нужно не в общий слой материалов, а в область конкретной задачи. Это может быть branch, worktree, sandbox, temporary workspace или отдельная папка артефактов.

Главное правило: агент должен писать там, где результат можно проверить и откатить. Если несколько агентов пишут в одну и ту же папку без owner, locks и структуры, команда получает не ускорение, а скрытые конфликты.

Worktree и sandbox решают разные задачи. Worktree изолирует изменения кода и git index. Sandbox изолирует выполнение команд, файловую систему и иногда сеть. В командном пилоте часто нужны оба слоя.

Worktree не заменяет безопасность: агент всё ещё может читать то, что доступно процессу. Sandbox не заменяет review: изолированная команда может создать плохой diff. Поэтому workspace-модель должна связывать оба механизма с permissions, logs и human review.

Shared artifacts — это не “папка для всего”. Это слой передачи результатов: что агент сделал, что проверил, какие файлы изменил, где риски и какой следующий шаг нужен человеку или другому агенту.

Хороший handoff artifact обычно содержит:

• цель задачи и короткий итог;
• изменённые файлы или ссылки на diff;
• команды проверки и результат;
• что агент не проверил;
• обнаруженные риски;
• ссылки на логи, отчёты, screenshots или intermediate files;
• next step для reviewer или следующего агента.

Если артефакты нужны нескольким агентам, лучше использовать run-id, owner, timestamps и append-only подход. Если два агента могут менять один и тот же файл артефакта, нужен lock, очередь, API или другой механизм согласования.

MCP roots задают границы файловой системы, которые клиент показывает MCP-серверу. Это удобный механизм для workspace-модели: агент может видеть нужные директории, но не получает весь диск или home directory.

MCP не должен становиться обходом security-модели. Если агенту дали filesystem MCP на весь /home, это не управляемый workspace, а широкий доступ под новым названием. Roots должны быть минимальными, понятными и проверяемыми.

Shared materials должны развиваться: агенты находят повторяющиеся проверки, уточняют runbooks, предлагают новые templates. Но изменение общего слоя должно проходить отдельный review, иначе контекст начинает дрейфовать.

Практический процесс:

1. Агент во время задачи пишет предложение в artifacts или PR comment.
2. Человек проверяет, что правило действительно повторяемое, а не частный случай.
3. Изменение оформляется отдельным PR в agent-materials, docs или нужный repo.
4. Review проверяет смысл, безопасность, актуальность команд и отсутствие секретов.
5. После merge агентам становится доступна новая версия материалов.

Такой процесс медленнее, чем “пусть агент сам допишет общий Markdown”, но он сохраняет доверие к материалам. Общий контекст должен быть скучным, проверенным и предсказуемым. Для экспериментов есть рабочие пространства и артефакты.

Безопасность Agent Materials Workspace проверяется не только списком запретов. Нужно убедиться, что агент технически не может выйти за нужные границы или что рискованное действие остановится на review.

В пилоте полезно проверять не только успешные задачи. Дайте агенту сценарий рядом с секретами, большим diff, конфликтом worktree или устаревшим runbook. Если система держится только на том, что агент “должен был послушаться”, граница слабая.

Главный риск — принять файловую доступность за управляемость. То, что агент может прочитать или записать файл, ещё не означает, что команда сможет восстановить причину изменения, проверить источник контекста и безопасно повторить процесс.

После подготовки Agent Materials Workspace у команды должен быть понятный комплект, который можно приложить к пилоту или проектному обсуждению:

• список read-only materials и их владельцев;
• правило, где агент пишет код и временные файлы;
• схема worktree/sandbox для параллельных задач;
• структура artifacts/<run-id>/ или другой handoff layer;
• список MCP roots и read/write policy;
• правила для секретов, shell-команд и внешней сети;
• формат handoff summary;
• порядок promotion изменений в shared materials;
• критерии review и audit trail.

Такой комплект помогает запускать AI coding agents не как набор личных экспериментов, а как управляемый рабочий контур. Команда заранее понимает, где агент берёт контекст, где оставляет результат, что можно ревьюить и какие действия требуют отдельного подтверждения.