Laravel Copilot Workspace: как я собрал полный цикл разработки вокруг Copilot-агентов

Недавно в Visual Studio Code появился важный апдейт: редактор научился нормально работать с кастомными Copilot-агентами, описанными прямо в репозитории — в файлах .github/agents/*.agent.md. То есть теперь мы можем описать «агента» обычным текстовым файлом — и он появится в Copilot Chat как отдельный помощник со своей ролью.

Я довольно давно делаю инструменты для разработчиков, которые помогают нормально использовать ИИ в реальных проектах: ассистентов, утилиты, внутренние «методички». И когда GitHub Copilot получил поддержку custom agents, стало понятно, что можно собрать вокруг этого не просто набор промптов, а полноценный рабочий процесс.

Так появился репозиторий copilot-workspace-laravel — Laravel-workspace, где:

• есть каркас приложения;

• есть набор Copilot-агентов по этапам жизни проекта;

• есть папки для ТЗ, домена, архитектуры, документации, логов и релизов;

• есть общий файл инструкций для ИИ — .github/copilot-instructions.md.

Ниже расскажу, как это устроено и как этим пользоваться.

Зачем вообще агенты, если уже есть Copilot

Классический Copilot — это подсказки в коде и чат «обо всём сразу». Это удобно, но у этого подхода есть заметный минус: каждый раз приходится заново объяснять контекст:

• какие у нас правила по Laravel;

• где лежат требования и архитектура;

• как мы режем работу на блоки;

• куда складываем логи и релизы.

Я называю такой блок батчем: это порция работы, которую Copilot и разработчик могут осмысленно сделать за одну итерацию. Не «переписать весь монолит», а, например, «сделать регистрацию и вход пользователя с тестами».

С кастомными агентами можно сделать по-другому:

• завести агента по требованиям;

• завести агента-архитектора;

• завести агента-строителя кода;

• завести агента для тестов и ревью;

• завести агента для релизов и документации.

Каждому агенту мы:

• даём свою роль;

• прописываем, какие папки он читает и куда пишет;

• описываем формат результата и ограничения.

В итоге Copilot перестаёт быть «одним большим ИИ» и превращается в команду цифровых коллег, которые работают по шагам и по правилам проекта.

Что такое Laravel Copilot Workspace

В основе — обычный Laravel-проект на PHP 8.1+. Вокруг него собрана инфраструктура для работы с ИИ.

Ключевые элементы:

• .github/agents/*.agent.md — профили агентов Copilot. Здесь описаны:

  • имя и назначение;

  • какими инструментами агент может пользоваться;

  • какие папки и файлы он может читать и менять;

  • кому он может передавать управление дальше (handoff).

• .github/copilot-instructions.md — общие инструкции, которые подмешиваются ко всем запросам Copilot в этом репозитории:

  • что это Laravel-проект;

  • где искать требования и домен (inputs/**);

  • какие правила разработки учитывать (rules/**);

  • какие команды запускать для тестов и статического анализа;

  • на каком языке отвечать и оформлять артефакты.

По сути, .github/copilot-instructions.md — это единое ТЗ для ИИ по репозиторию. Любой агент приходит уже с этим контекстом и не спрашивает каждый раз: «а где у вас домен?», «а какие у вас слои?», «на каком языке отвечать?».

Отдельный момент: все инструкции у меня на русском языке. Для моделей Copilot нет принципиальной разницы, на каком языке написан промпт. Зато для разработчиков в команде так гораздо проще:

• читать правила;

• править тексты агентов;

• расширять инструкции под свои процессы.

Агенты: команда, которая работает по этапам

Все агенты в workspace устроены как конвейер:

00 ? 10 ? 20 ? 30 ? 40 ? 50 ? 60

Цифры в начале имени — это этап жизни проекта:

• 00 — помощь и навигация;

• 10 — требования и предметная область;

• 20 — архитектура и план батчей;

• 30 — реализация кода;

• 40 — качество (инструменты, тесты, ревью);

• 50 — документация;

• 60 — релизы и деплой-пакеты.

Благодаря такому неймингу:

• по числу сразу понятно, где в «жизни проекта» находится агент;

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

Дальше — короткий обзор этапов и агентов внутри них.

Этап 00: понять, что к чему

00-help-assistant — входная точка во весь workspace.

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

• «Есть старый проект на Laravel, хотим навести порядок и внедрить Copilot»;

• «Начинаем новый сервис, не хотим утонуть в хаосе через месяц»;

• «Нужно аккуратно вкатить крупную фичу и не сломать всё вокруг».

Агент:

• объясняет, что где лежит (inputs/, docs/, rules/, results/, packages/);

• показывает общую карту;

• предлагает, каких помощников вызвать дальше.

Через него же можно создать новых агентов: описать, какая роль нужна, а он соберёт черновик .agent.md, который уже можно отредактировать руками.

Этап 10: превратить хаос в ТЗ и домен

Здесь работают два агента.

10-requirements-create занимается оформлением требований. Вы даёте ему сырые материалы: текст задачи из трекера, куски переписки из чата, свои заметки. На выходе — более-менее аккуратное ТЗ в inputs/requirements/**:

• с выделенными сущностями и сценариями;

• с понятными целями;

• с явными ограничениями и допущениями.

10-domain-describe смотрит на задачу с точки зрения предметной области. Он:

• делает глоссарий терминов;

• выделяет бизнес-сущности и связи между ними;

• фиксирует правила и ограничения в inputs/domain/**.

В результате команда и агенты начинают говорить об одном и том же бизнесе одними и теми же словами.

Этап 20: архитектура и план батчей

Когда понятно «что делаем» и «в каком мире», приходит время «как».

20-architecture-plan помогает собрать архитектурный скелет:

• какие у нас слои (Domain, Application, Infrastructure, Http и т.д.);

• какие компоненты за что отвечают;

• где проходят границы ответственности.

Он оформляет результат в inputs/design/** и, если нужно, обновляет архитектурные документы в docs/.

20-batches-plan отвечает за план работ. Он берёт требования и архитектуру и режет их на батчи:

• заводит inputs/batches/pipeline.json со списком батчей и статусами;

• создаёт YAML-файлы для каждого батча с входами, выходами и критерием «готово».

Дальше другие агенты уже ориентируются на этот pipeline, а не на хаос задач «из головы».

Этап 30: реализация кода

Здесь агенты работают с настоящим кодом Laravel-приложения.

30-laravel-app-create нужен, если вы переносите подход в новый репозиторий. Он может:

• поднять каркас Laravel;

• помочь с базовой структурой и первичной настройкой;

• подготовить проект под дальнейшую работу с агентами.

В самом copilot-workspace-laravel каркас уже есть, поэтому этот агент больше про «размножение» подхода на другие проекты.

30-code-build — основной «строитель» кода.

Он:

• берёт первый pending-батч из inputs/batches/pipeline.json;

• смотрит на требования, домен и архитектуру;

• учитывает правила из rules/**;

• вносит изменения в app/**, routes/**, database/**, config/**, resources/**, tests/**;

• складывает логи и результаты в results/**.

В идеале вы не просто говорите: «сделай мне форму регистрации», а привязываете эту работу к конкретному батчу, у которого есть входы, выходы и связь с требованиями.

Этап 40: качество и проверки

Этот уровень отвечает за то, чтобы проект не превратился в «копипасту, которая как-то работает».

40-tools-init настраивает инструменты качества под конкретный проект. Он:

• подстраивает phpstan.neon;

• обновляет phpunit.xml;

• настраивает форматер (pint.json или .php-cs-fixer.dist.php);

• при необходимости помогает с deptrac.yaml.

Запускать его имеет смысл, когда:

• каркас Laravel уже есть;

• зависимости поставлены (composer install);

• структура проекта более-менее понятна.

После этого у вас не просто «где-то лежат конфиги», а есть рабочий набор инструментов, который можно запускать одной-двумя командами.

40-tests-run — «операционист», который просто делает проверки.

Он:

• запускает тесты;

• запускает статический анализ;

• прогоняет форматирование в режиме проверки;

• складывает отчёты в results/checks/**.

Так и люди, и агенты видят историю прогонов в одном месте.

40-code-review занимается автоматизированным ревью. Он:

• смотрит на diff;

• подсвечивает спорные места;

• предлагает улучшения;

• пишет отчёты в results/reviews/**.

Это не замена человеческому ревью, но хороший фильтр «очевидных косяков».

Этап 50: документация

На этом этапе работает один, но очень полезный агент — 50-docs-update.

Его задача — привести docs/** в соответствие с реальностью. Для этого он:

• читает ТЗ и домен в inputs/**;

• смотрит на архитектуру в inputs/design/**;

• анализирует код и результаты проверок (results/**);

• помогает создать или обновить документы в docs/.

На практике это означает, что документация:

• не отстаёт от кода на полгода;

• не живёт где-то в отдельной вики;

• может регулярно обновляться в пару шагов через агента.

Этап 60: релизы и деплой-пакеты

Финишная часть конвейера.

60-release-build собирает релизный слепок проекта:

• по заданному диапазону коммитов;

• с раскладкой по файлам в packages/releases/**;

• с README внутри, где описано, что в релиз вошло.

60-deploy-bundle-build превращает этот слепок в деплой-пакет:

• складывает всё нужное в packages/deploy/**;

• исключает лишнее (vendor, node_modules, .env и т.п.);

• добавляет инструкции по развертыванию.

То есть результат работы агентов — это не только «красивый код», но и понятный, воспроизводимый пакет, который можно отнести на сервер или отдать CI/CD.

Папки: что где лежит и как с этим живут агенты

Чтобы агенты работали осмысленно, у workspace есть несколько опорных папок. Каждая отвечает за свою часть картины.

Папка inputs/: входные данные для ИИ и команды

inputs/ — это всё, что отвечает на вопрос «что мы делаем и в каком мире»:

• ТЗ и постановки (requirements/);

• глоссарий, сущности и бизнес-правила (domain/);

• архитектурные решения (design/);

• батчи и pipeline.json (batches/);

• служебные промпты и данные (prompts/, data/).

Здесь работают в основном агенты уровней 10 и 20. Если упростить, inputs/ — это текстовая зона аналитики и архитектуры, удобная и для людей, и для ИИ.

Папка docs/: документация по проекту

docs/ отвечает за то, что обычно живёт в Confluence или Notion: обзоры, гайды, инструкции.

Сюда попадает:

• обзор проекта и подсистем;

• руководства для разработчиков;

• практические инструкции «как запускать/обновлять/поддерживать».

Эта папка тесно связана с агентом 50-docs-update. Он читает ТЗ, домен, архитектуру, код и логи и помогает держать содержимое docs/ в актуальном состоянии. Благодаря этому документация перестаёт быть «кладбищем старых описаний» и становится живой частью процесса.

Папка rules/: договорённости команды

rules/ — место для правил и стандартов:

• как делим код по слоям;

• где живёт бизнес-логика, а где инфраструктура;

• какие требования к производительности считаем разумными;

• как подходим к релизам и выкладке.

На rules/** смотрят и разработчики, и агенты 30-code-build, 40-*. Когда вы меняете эти файлы, вы фактически меняете «конституцию» проекта, и ИИ начинает работать по новым правилам вместе с командой.

Папка results/: история запусков и проверок

results/ — это дневник того, что уже происходило с проектом.

Здесь лежат:

• отчёты тестов и статического анализа (checks/);

• заметки по выполненным батчам (batches/);

• отчёты автоматизированного ревью (reviews/).

Эта папка полезна всем:

• разработчик может быстро посмотреть, когда и почему падали проверки;

• агенты могут опираться на эту историю и не повторять одни и те же шаги.

Папка packages/: релизы и деплой-пакеты

packages/ отвечает за поставку.

Внутри неё:

• releases/ — релизные слепки по коммитам;

• deploy/ — готовые деплой-пакеты.

Здесь работает в основном 60-я группа агентов. Эти папки помогают отделить «то, над чем мы сейчас работаем» от «того, что реально уехало или уедет на сервер».

Типичный рабочий цикл в этом workspace

В реальной жизни у меня получается примерно такая дорожка:

1. Сформулировать задачу по-человечески. Просто описываю, что нужно сделать и для кого.

2. Оформить требования через 10-requirements-create. Передаю сырые тексты агенту и получаю ТЗ в inputs/requirements/**.

3. Описать предметную область через 10-domain-describe. Агент собирает глоссарий, сущности и правила в inputs/domain/**.

4. Спланировать архитектуру и батчи (20-architecture-plan и 20-batches-plan). После этого появляется архитектурный скелет и понятный список батчей в inputs/design/** и inputs/batches/**.

5. Подготовить каркас и инструменты качества. Либо использую уже готовый copilot-workspace-laravel, либо поднимаю новый проект через 30-laravel-app-create. Затем запускаю 40-tools-init, чтобы привести phpstan, тесты и линтеры в рабочее состояние.

6. Реализовывать фичи батчами через 30-code-build. Берём по одному батчу из pipeline.json, работаем вместе с агентом, фиксируем результаты в results/**.

7. Прогонять проверки и ревью (40-tests-run, 40-code-review). Смотрим, что падает, что можно улучшить, и не держим это только в локальных логах.

8. Обновлять документацию через 50-docs-update. Когда фича или блок работ готовы, агент помогает привести docs/** в актуальное состояние.

9. Собирать релизы и деплой-пакеты через 60-release-build и 60-deploy-bundle-build. На выходе — понятный релизный слепок и готовый деплой-пакет в packages/**.

При этом:

• код, требования, домен, документация и релизы живут в одном репозитории;

• агенты знают, какие папки читать и куда писать;

• разработчик всегда может зайти в нужную директорию и увидеть, что происходит.

Как попробовать

Если хочется потрогать всё это руками, минимальный сценарий такой:

1. Клонировать репозиторий https://github.com/zabarov/copilot-workspace-laravel.

2. Выполнить базовую настройку Laravel в корне:

composer install cp .env.example .env php artisan key:generate 

3. Открыть проект в Visual Studio Code с включённым GitHub Copilot / Copilot Chat. IDE сама увидит .github/copilot-instructions.md и .github/agents/*.agent.md и покажет агентов в интерфейсе.

4. Для старта можно:

   • если вы только знакомитесь — вызвать 00-help-assistant и просто спросить «с чего нам начать в нашей ситуации?»;

   • если уже есть конкретная задача — начать с 10-requirements-create и оформить ТЗ;

   • если хотите сразу «навести порядок» — позвать 40-tools-init, а потом 50-docs-update, чтобы привести в чувства инструменты качества и документацию.

Немного про эксперимент и обратную связь

Для меня этот workspace — не «готовый продукт», а живой эксперимент. Я продолжаю его развивать, менять структуру, допиливать агентов и инструкции по мере того, как он используется в реальных задачах.

Если у вас появятся идеи, что можно улучшить, чего не хватает или что можно сделать проще — буду рад обратной связи:

• в комментариях к статье;

• в issue или pull request’ах в репозитории.

Такие штуки лучше всего развиваются, когда в них смотрят сразу несколько команд и делятся опытом.