Laravel Tackle: Як запустити AI Coding Agent у вашому Laravel-застосунку

Laravel Tackle, створений Jordan Dalton, — це ШІ-агент для кодингу, який працює через Artisan-команди безпосередньо у вашому застосунку. Оскільки він запускається разом із фреймворком, агент має доступ до тих самих інструментів, що й розробник: він може переглядати список routes, читати винятки в Telescope, виконувати SELECT-запити до бази даних та запускати Pint після завершення редагування.

Робота всередині застосунку також змінює підхід до безпеки. Обмеження шляхів, білий список Artisan та ліміти витрат на сесію прописані у PHP-коді пакета, а не в інструкціях промпту, які модель могла б ігнорувати. Пакет побудований на laravel/ai і за замовчуванням використовує Claude, хоча через AI_CODE_PROVIDER його можна перемикнути на OpenAI, Gemini, Groq або локальну модель через Ollama.

Пакет пропонує кілька агентів:

• ai:code — інтерактивна сесія: REPL із режимом планування, слеш-командами, можливістю додавати зображення та історією, що зберігається між запусками.
• ai:run — той самий агент, але для автоматизації: виконує одне завдання, повертає код виходу та підтримує --output=json для роботи в pipeline.
• ai:fix — вузькоспеціалізована сесія для виправлення помилок на основі скопійованого винятку, ID із Sentry (--sentry=ID) або GitHub issue (--issue=N).
• ai:review — аналізує diff або Pull Request і залишає коментарі до коду із зазначенням рівня критичності.
• ai:upgrade — допомагає оновити Composer-пакет до мажорної версії, спираючись на офіційний гайд з оновлення у директорії vendor/.
• The self-healer — стежить за помилками у чергах та запланованих завданнях, виправляє код в ізольованому worktree та відкриває Pull Request.
• Tackle Remote — допоміжний пакет, що надає інтерфейс для мобільного браузера з можливістю підтвердження дій.

# Встановлення

Tackle потребує PHP 8.3 та Laravel 12 або 13. Встановіть пакет і опублікуйте конфігурації:

composer require jordandalton/laravel-tackle
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan vendor:publish --tag="tackle-config"

Опублікований config/ai.php вже містить блок для Anthropic, тож залишається лише додати API-ключ у .env:

ANTHROPIC_API_KEY=sk-ant-...

Для зміни провайдера достатньо двох змінних. Для Ollama знадобляться ще дві, оскільки локальна модель безкоштовна, а вбудований каталог цін не має для неї тарифів:

AI_CODE_PROVIDER=ollama
AI_CODE_MODEL=deepseek-coder-v2
AI_CODE_PRICE_INPUT=0
AI_CODE_PRICE_OUTPUT=0

Перед першою сесією зафіксуйте зміни в Git (commit або stash). Агент редагує файли «на місці», якщо не увімкнено режим worktree, тому git checkout -- . буде безпечним способом скасувати зміни лише за умови, що ваша робота вже збережена.

# Сесія кодингу

Команда php artisan ai:code відкриває REPL. Введіть завдання і спостерігайте за викликами інструментів та git diff --stat, який Laravel Prompts виводить після кожного кроку.

Режим планування (--plan) — це найважливіша функція. У цьому режимі агент спочатку досліджує код і формує пронумерований план зі змінами та можливими ризиками. Ви можете вибрати: Execute (виконати), Revise (переглянути) або Cancel (скасувати). Те саме можна зробити для окремого завдання прямо в сесії:

> /plan expire abandoned carts on a nightly schedule

Доступ до Shell має чотири режими, які можна змінювати для кожної сесії:

php artisan ai:code --off          # RunShell заборонено
php artisan ai:code --approve      # підтвердження кожної команди (за замовчуванням)
php artisan ai:code --allowlist    # лише команди з shell_allowlist
php artisan ai:code --yolo         # без жодних підтверджень

Режим --off ідеально підходить для запитань. Він залишає доступ до читання коду (наприклад, щоб запитати, як працює автентифікація), але забороняє агенту будь-що запускати.

Логи сесій зберігаються в storage/ai-code/, а прапорець --session=search-rewrite дозволяє розділяти історію для різних завдань. Коли обсяг бесіди перевищує 60 000 символів, Tackle автоматично підсумовує старі повідомлення. Команда /compact запускає цей процес примусово, а /clear повністю очищує історію.

# Межі безпеки

Усі правила в config/tackle.php перевіряються перед запуском будь-якого інструмента, і жодна інструкція в промпті не може їх змінити:

return [
    'budget_usd' => env('AI_CODE_BUDGET', 1.00),
 
    'shell' => [
        'local'      => env('AI_CODE_SHELL', 'approve'),
        'staging'    => env('AI_CODE_SHELL', 'approve'),
        'production' => env('AI_CODE_SHELL', 'off'),
    ],
 
    'artisan_allowlist' => [
        'local'      => ['make:*', 'migrate:*', 'db:seed', 'route:list', 'test'],
        'staging'    => ['migrate', 'route:list'],
        'production' => ['route:list'],
    ],
 
    'worktree' => [
        'local'      => env('AI_CODE_WORKTREE', false),
        'staging'    => env('AI_CODE_WORKTREE', false),
        'production' => env('AI_CODE_WORKTREE', true),
    ],
 
    'protected_paths' => ['.env', '.env.*', 'storage/*', 'vendor/*', '.git/*'],
];

protected_paths блокує як читання, так і запис, тому агент не зможе побачити ваш .env. Деструктивні Artisan-команди (migrate:fresh тощо) потребують ручного підтвердження в терміналі. Ліміт бюджету є жорстким: сесія переривається при його досягненні, а на 80% витрат з'являється попередження.

Режим worktree корисний, коли ви хочете перевірити diff перед тим, як зміни потраплять у ваш основний код. Редагування відбувається в тимчасовій робочій копії Git, а в заголовку сесії відображається worktree: on. Тимчасові файли видаляються автоматично, а tackle:prune очищує залишки після аварійних завершень.

# Інструкції проєкту

На початку сесії кожен агент завантажує файл TACKLE.md із кореня проєкту. Команда php artisan tackle:init аналізує composer.json, тестовий фреймворк та структуру app/, створюючи шаблон із розділами Conventions, Boundaries та Gotchas:

## Conventions
 
- Мітки часу зберігаються в UTC та приводяться до типу `immutable_datetime`.
- Джоби в чергах мають бути ідемпотентними, оскільки воркери роблять три спроби запуску.
 
## Gotchas
 
- `Order::open()` ігнорує замовлення у статусі `pending_review`.
- З'єднання `reporting` призначене лише для читання; спроби запису призведуть до помилки.

Якщо TACKLE.md відсутній, пакет шукає AGENTS.md або CLAUDE.md. Обсяг інструкцій обмежений 20 000 символами для економії контекстного вікна та бюджету.

# Рецензування Pull Requests

Команда ai:review запускає агента в режимі «тільки для читання» для аналізу diff. Він бачить повний код файлу навколо змінених функцій, що робить його висновки більш обґрунтованими:

php artisan ai:review                     # аналіз staged та unstaged змін
php artisan ai:review --against=main      # у стилі PR
php artisan ai:review --pr=118 --comment  # публікація коментарів у GitHub PR

Результати групуються за файлами та рівнями критичності, завершуючись вердиктом: LGTM, зауваження або Needs changes. Прапорець --fail-on=critical дозволяє використовувати цей вердикт для блокування merge у CI-процесах.

При повторному запуску Tackle не перевіряє все заново. Він використовує приховані маркери, щоб аналізувати лише нові коміти. Якщо ви відповісте на коментар агента в GitHub за допомогою /tackle, команда ai:respond опрацює запит, внесе зміни та відправить новий коміт у гілку PR.

# Самовідновлення черг

Ця функція вимкнена за замовчуванням. Щоб активувати її, встановіть AI_CODE_HEALING_ENABLED=true, запустіть міграції та воркера для черги healer:

php artisan vendor:publish --tag="tackle-migrations"
php artisan migrate
php artisan queue:work --queue=healer

Тепер у разі падіння джоби Tackle перехопить подію JobFailed і запустить агента для виправлення. Він проаналізує виняток, стек викликів та дані з Telescope. Агент запропонує мінімальне виправлення, запустить тести та відкриє PR або (у режимі patch) внесе зміни безпосередньо у вашу гілку та перезапустить початкову джобу.

Щоб агент не чіпав певні джоби, використовуйте атрибут #[Healable(false)]. Також можна налаштувати поріг спроб через AI_CODE_HEALING_THRESHOLD, щоб не реагувати на тимчасові збої мережі.

Усі спроби фіксуються в таблиці tackle_healing_log, де можна перевірити результати:

php artisan tackle:healing-log --type=job
php artisan tackle:healing-log --outcome=patched --limit=50

# Підтримка MCP

Інструменти Tackle можна використовувати і в інших середовищах. tackle:mcp надає доступ до них через протокол MCP. Це дозволяє Claude Code, Cursor або Zed викликати команди ListRoutes, QueryDatabase чи RunLarastan у контексті вашого застосунку:

claude mcp add tackle -- php artisan tackle:mcp

За замовчуванням через MCP доступні лише інструменти аналізу та читання. Усі обмеження безпеки (білі списки, доступ до БД лише на SELECT) залишаються чинними. Команди, що потребують взаємодії з користувачем (AskUser, ConfirmAction), у цьому режимі автоматично відхиляються.

Варто врахувати два обмеження: агент не має доступу до інтернету (працює лише з локальними файлами) і самостійно розраховує бюджет на основі токенів, що може дещо відрізнятися від фінального рахунку провайдера. Tackle розповсюджується під ліцензією MIT, актуальна версія — v1.27.3 на GitHub.