Boost의 커스텀 에이전트 만들기

왜 커스텀 에이전트가 필요한가

Laravel Boost는 Claude Code, Cursor, Codex, GitHub Copilot(VS Code) 등 주요 AI 코딩 도구를 기본으로 서포트하고 있습니다. 그러나 사내 도구, 신흥 AI 에이전트, 독자 워크플로우에 대응하려면, Boost의 확장 기능을 사용해 커스텀 에이전트를 구현해야 합니다. 커스텀 에이전트가 도움이 되는 장면:

Boost가 미대응인 IDE나 AI 도구를 사용하고 있음
사내 개발 워크플로우나 독자 CI/CD 파이프라인에 Boost를 통합하고 싶음
에이전트 고유의 설정 파일 형식이나 설치 절차가 있음

Boost의 확장 아키텍처

Agent 기저 클래스

모든 에이전트는 Laravel\Boost\Install\Agents\Agent를 상속합니다. 이 추상 클래스가 제공하는 기능:

에이전트의 검출(시스템 전체·프로젝트 단위)
MCP 서버의 설치(파일 기반·셸 커맨드 기반)
가이드라인 변환 훅(transformGuidelines)

구현이 필수인 추상 메서드는 2개입니다.

메서드	설명
`name()`	에이전트의 내부 식별자(예: `claude_code`)
`displayName()`	설치 시에 표시되는 이름(예: `Claude Code`)
`systemDetectionConfig(Platform $platform)`	시스템 전체에의 설치 검출 설정
`projectDetectionConfig()`	프로젝트 단위의 설치 검출 설정

3개의 컨트랙트

Boost의 기능을 선택적으로 활성화하기 위해, 이하의 컨트랙트를 필요한 만큼 구현합니다.

컨트랙트	역할
`SupportsGuidelines`	AI 가이드라인 파일의 쓰기 경로와 변환 처리
`SupportsMcp`	MCP 서버 설정의 설치
`SupportsSkills`	Agent Skills의 설치 경로

3개의 컨트랙트는 모두 임의입니다. 가이드라인만 서포트하고 MCP는 불필요, 라는 구현도 가능합니다.

SupportsGuidelines 컨트랙트

interface SupportsGuidelines
{
    // AIガイドラインを書き出すファイルパス
    public function guidelinesPath(): string;

    // ガイドラインファイルにフロントマターが必要か
    public function frontmatter(): bool;

    // 生成されたガイドラインのMarkdownを後処理する
    public function transformGuidelines(string $markdown): string;
}

guidelinesPath()는 생성한 가이드라인을 쓸 파일 경로를 반환합니다. Claude Code라면 CLAUDE.md, Cursor라면 .cursor/rules/laravel-boost.mdc처럼, 에이전트가 로드하는 형식에 맞춥니다. transformGuidelines()는 생성 후의 Markdown을 가공하는 훅입니다. 에이전트 고유의 헤더를 추가하거나, 특수한 포맷으로 변환할 수 있습니다. Agent 기저 클래스에 구현된 기본은 그대로 문자열을 반환합니다.

SupportsMcp 컨트랙트

interface SupportsMcp
{
    // MCPコマンドに絶対パスを使うか
    public function useAbsolutePathForMcp(): bool;

    // PHP実行ファイルのパスを返す
    public function getPhpPath(bool $forceAbsolutePath = false): string;

    // artisanのパスを返す
    public function getArtisanPath(bool $forceAbsolutePath = false): string;

    // MCPサーバー設定をインストールする
    public function installMcp(string $key, string $command, array $args = [], array $env = []): bool;

    // HTTP経由のMCPサーバー設定をインストールする
    public function installHttpMcp(string $key, string $url): bool;
}

Agent 기저 클래스가 installMcp()와 installHttpMcp()의 기본 구현을 가지고 있으므로, 많은 경우에는 mcpInstallationStrategy()와 mcpConfigPath()를 오버라이드하는 것만으로 충분합니다. 설치 전략은 2종류가 있습니다.

`McpInstallationStrategy`	동작
`FILE`	JSON/TOML 파일에 설정을 쓴다(기본)
`SHELL`	셸 커맨드를 실행하여 MCP를 등록한다
`NONE`	MCP 설치를 스킵한다

SupportsSkills 컨트랙트

interface SupportsSkills
{
    // Agent Skillsを書き出すディレクトリパス
    public function skillsPath(): string;
}

에이전트가 로드하는 스킬 디렉토리의 경로를 반환합니다. Claude Code라면 .claude/skills, Cursor라면 .cursor/skills처럼 에이전트의 사양에 맞춥니다.

커스텀 에이전트의 작성

실제로 독자 에이전트 클래스를 구현합니다. 여기서는 독자의 CI/CD 워크플로우에 짜넣어진 가상 에이전트 “MyAgent”를 예로 합니다.

에이전트 클래스를 작성한다

app/Boost/MyAgent.php를 작성합니다.

<?php

declare(strict_types=1);

namespace App\Boost;

use Laravel\Boost\Contracts\SupportsGuidelines;
use Laravel\Boost\Contracts\SupportsMcp;
use Laravel\Boost\Contracts\SupportsSkills;
use Laravel\Boost\Install\Agents\Agent;
use Laravel\Boost\Install\Enums\McpInstallationStrategy;
use Laravel\Boost\Install\Enums\Platform;

class MyAgent extends Agent implements SupportsGuidelines, SupportsMcp, SupportsSkills
{
    public function name(): string
    {
        return 'my_agent';
    }

    public function displayName(): string
    {
        return 'MyAgent';
    }

    public function systemDetectionConfig(Platform $platform): array
    {
        return match ($platform) {
            Platform::Darwin, Platform::Linux => [
                'command' => 'command -v myagent',
            ],
            Platform::Windows => [
                'command' => 'cmd /c where myagent 2>nul',
            ],
        };
    }

    public function projectDetectionConfig(): array
    {
        return [
            'files' => ['.myagent.json'],
        ];
    }

    // --- SupportsGuidelines ---

    public function guidelinesPath(): string
    {
        return 'MYAGENT.md';
    }

    // frontmatter() は Agent 基底クラスのデフォルト (false) を使用
    // transformGuidelines() も基底クラスのデフォルト（そのまま返す）を使用

    // --- SupportsMcp ---

    // useAbsolutePathForMcp(), getPhpPath(), getArtisanPath(),
    // installMcp(), installHttpMcp() はすべて Agent 基底クラスが実装済み

    public function mcpInstallationStrategy(): McpInstallationStrategy
    {
        return McpInstallationStrategy::FILE;
    }

    public function mcpConfigPath(): string
    {
        return '.myagent.json';
    }

    // --- SupportsSkills ---

    public function skillsPath(): string
    {
        return '.myagent/skills';
    }
}

systemDetectionConfig()와 projectDetectionConfig()는 Boost가 에이전트를 시스템·프로젝트에서 자동 검출하기 위해 사용합니다. boost:install 실행 시에 대상 에이전트를 자동적으로 후보로서 표시합니다.

에이전트를 등록한다

App\Providers\AppServiceProvider의 boot 메서드에 커스텀 에이전트를 등록합니다.

<?php

namespace App\Providers;

use App\Boost\MyAgent;
use Illuminate\Support\ServiceProvider;
use Laravel\Boost\Boost;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Boost::registerAgent('my_agent', MyAgent::class);
    }
}

등록 후, php artisan boost:install을 실행하면 MyAgent가 선택지에 표시됩니다.

동작을 확인한다

php artisan boost:install

설치 대상의 에이전트를 선택하는 화면에서 MyAgent가 표시됩니다. 선택하면 MYAGENT.md, .myagent.json, .myagent/skills/가 생성됩니다.

가이드라인의 커스터마이즈

guidelinesPath의 설정

에이전트에 따라 가이드라인 파일의 로드 장소는 다릅니다.

// 単一ファイルとして出力する場合
public function guidelinesPath(): string
{
    return 'MYAGENT.md';
}

설정 파일에서 덮어쓸 수 있게 하면 유연성이 높아집니다.

public function guidelinesPath(): string
{
    return config('boost.agents.my_agent.guidelines_path', 'MYAGENT.md');
}

프런트매터가 필요한 에이전트

Cursor의 .cursor/rules/*.mdc처럼 프런트매터가 필요한 포맷에는 frontmatter()에서 true를 반환합니다.

public function frontmatter(): bool
{
    return true;
}

가이드라인의 후처리

transformGuidelines()를 사용하여 생성 후의 Markdown을 가공할 수 있습니다.

public function transformGuidelines(string $markdown): string
{
    // エージェント独自のヘッダーを追加する
    $header = "<!-- Generated by Laravel Boost for MyAgent -->\n\n";

    return $header . $markdown;
}

커스텀 AI 가이드라인의 추가

프로젝트 고유의 룰을 Boost의 가이드라인에 추가하려면, .ai/guidelines/ 디렉토리에 Blade 파일을 배치합니다.

.ai/
└── guidelines/
    ├── my-domain-rules.blade.php
    └── coding-standards.blade.php

파일 예:

## プロジェクト固有のルール

このプロジェクトでは以下の規約に従うこと:

- モデルは必ず `App\Models\` 名前空間に配置する
- すべてのAPIエンドポイントは `App\Http\Controllers\Api\` 以下に作成する
- DBトランザクションは `DB::transaction()` を使いサービスクラス内に閉じ込める

@verbatim
<code-snippet name="サービスクラスのトランザクション例" lang="php">
DB::transaction(function () use ($data) {
    $order = Order::create($data);
    $order->items()->createMany($data['items']);
    event(new OrderCreated($order));
});
</code-snippet>
@endverbatim

boost:install을 실행하면, 이 가이드라인이 Boost 내장의 가이드라인과 자동적으로 결합되어 출력됩니다.

내장 가이드라인의 오버라이드

Boost의 내장 가이드라인과 같은 경로에 커스텀 파일을 두면, 그쪽이 우선됩니다.

# Boostの "Inertia React v2 Form Guidance" をオーバーライドする
.ai/guidelines/inertia-react/2/forms.blade.php

커스텀 스킬의 추가

SKILL.md의 작성

.ai/skills/{스킬명}/SKILL.md에 스킬을 정의합니다.

.ai/
└── skills/
    └── creating-invoices/
        └── SKILL.md

SKILL.md는 YAML 프런트매터와 Markdown 지시로 구성합니다.

---
name: creating-invoices
description: 請求書（Invoice）の作成・更新・送信に関する処理を実装する際に使うスキル。
---

# 請求書作成スキル

## このスキルを使う場面

請求書モデルの作成、請求書のPDF生成、メール送信を実装するときに使います。

## ファイル構造

- `app/Models/Invoice.php` — 請求書モデル
- `app/Services/InvoiceService.php` — ビジネスロジック
- `app/Jobs/SendInvoiceEmail.php` — メール送信ジョブ

## 実装パターン

### 請求書の作成

```php
// $items はコントローラーや他のサービスから渡された配列
$invoice = InvoiceService::create([
    'user_id' => $user->id,
    'items' => $items,
    'due_date' => now()->addDays(30),
]);

請求書のPDF生成

PDFは barryvdh/laravel-dompdf を使って生成する:

use Barryvdh\DomPDF\Facade\Pdf;
use Illuminate\Support\Facades\Storage;

$pdf = Pdf::loadView('invoices.pdf', ['invoice' => $invoice]);
Storage::put("invoices/{$invoice->id}.pdf", $pdf->output());

스킬은 “필요할 때만 로드하는” 설계입니다. 항상 필요한 정보는 가이드라인에, 태스크 고유의 상세한 패턴은 스킬로 나눔으로써, AI의 컨텍스트 사용량을 최적화할 수 있습니다.

내장 스킬의 오버라이드

Boost의 내장 스킬과 같은 이름으로 커스텀 스킬을 만들면 덮어써집니다.

# livewire-development スキルをカスタマイズする
.ai/skills/livewire-development/SKILL.md

서드파티 패키지에의 Boost 대응 추가

자체 패키지에 Boost 서포트를 추가하려면, 패키지의 resources/boost/ 디렉토리에 설정 파일을 배치합니다.

가이드라인의 추가

resources/
└── boost/
    └── guidelines/
        └── core.blade.php

## MyPackage

このパッケージは [機能の概要] を提供します。

### 基本的な使い方

@verbatim
<code-snippet name="MyPackageの初期化" lang="php">
$result = MyPackage::create([
    'option' => 'value',
]);
</code-snippet>
@endverbatim

스킬의 추가

resources/
└── boost/
    └── skills/
        └── mypackage-development/
            └── SKILL.md

---
name: mypackage-development
description: MyPackageの機能を実装するスキル。
---

# MyPackage Development

## このスキルを使う場面
MyPackageを使った機能実装時に使います。

## 主な機能

- 機能1: ...
- 機能2: ...

패키지 사용자가 php artisan boost:install을 실행하면, 이 가이드라인과 스킬이 자동적으로 검출되어 설치 대상으로서 표시됩니다.

실전 예: 독자 CI/CD 에이전트용 커스텀 에이전트

사내의 CI/CD 파이프라인에 짜넣어진 가상 에이전트 “PipelineAgent”의 완전한 구현 예입니다. 이 에이전트는 가이드라인만 서포트하며, MCP와 스킬은 서포트하지 않습니다.

<?php

declare(strict_types=1);

namespace App\Boost;

use Laravel\Boost\Contracts\SupportsGuidelines;
use Laravel\Boost\Install\Agents\Agent;
use Laravel\Boost\Install\Enums\Platform;

class PipelineAgent extends Agent implements SupportsGuidelines
{
    public function name(): string
    {
        return 'pipeline_agent';
    }

    public function displayName(): string
    {
        return 'Pipeline Agent (CI/CD)';
    }

    public function systemDetectionConfig(Platform $platform): array
    {
        // CI環境変数で存在を検出する
        return [
            'command' => match ($platform) {
                Platform::Windows => 'cmd /c echo %CI_AGENT_VERSION% 2>nul',
                default => 'echo $CI_AGENT_VERSION',
            },
        ];
    }

    public function projectDetectionConfig(): array
    {
        // プロジェクトルートの設定ファイルで検出する
        return [
            'files' => ['.pipeline-agent.yml'],
        ];
    }

    public function guidelinesPath(): string
    {
        // CI/CDエージェントが読み込む規約のパス
        return '.pipeline/CODING_GUIDELINES.md';
    }

    public function frontmatter(): bool
    {
        return false;
    }

    public function transformGuidelines(string $markdown): string
    {
        // パイプライン用のメタデータヘッダーを追加する
        $timestamp = now()->toIso8601String();

        return "<!-- Generated by Laravel Boost at {$timestamp} -->\n\n{$markdown}";
    }
}

AppServiceProvider에 등록합니다:

use App\Boost\PipelineAgent;
use Laravel\Boost\Boost;

public function boot(): void
{
    Boost::registerAgent('pipeline_agent', PipelineAgent::class);
}

CI 환경에서는 이하의 커맨드로 가이드라인만을 생성할 수 있습니다:

php artisan boost:install --agent=pipeline_agent

참고 링크

ClaudeCode.php — 공식 구현 예

Boost에 동봉되어 있는 ClaudeCode 에이전트의 완전한 구현을 소스 코드로 확인할 수 있습니다.

Agent Skills

SKILL.md의 포맷 사양과 베스트 프랙티스를 참조할 수 있습니다.

Laravel Boost Custom Agent for GitHub Copilot CLI

Copilot CLI와 Testbench 양대응의 공개 패키지 구현 예

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

PhpStorm의 GitHub Copilot 플러그인용 공개 패키지 구현 예

AI 개발

디자인 패턴

패키지 개발

애플리케이션 구조

Laravel 13 신기능

Eloquent 심화

유효성 검증 확장

인증 확장

보안

테스트

Boost의 커스텀 에이전트 만들기

왜 커스텀 에이전트가 필요한가

Boost의 확장 아키텍처

Agent 기저 클래스

3개의 컨트랙트

SupportsGuidelines 컨트랙트

SupportsMcp 컨트랙트

SupportsSkills 컨트랙트

커스텀 에이전트의 작성

가이드라인의 커스터마이즈

guidelinesPath의 설정

프런트매터가 필요한 에이전트

가이드라인의 후처리

커스텀 AI 가이드라인의 추가

내장 가이드라인의 오버라이드

커스텀 스킬의 추가

SKILL.md의 작성

請求書のPDF生成

내장 스킬의 오버라이드

서드파티 패키지에의 Boost 대응 추가

가이드라인의 추가

스킬의 추가

실전 예: 독자 CI/CD 에이전트용 커스텀 에이전트

참고 링크

ClaudeCode.php — 공식 구현 예

Agent Skills

Laravel Boost Custom Agent for GitHub Copilot CLI

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

​왜 커스텀 에이전트가 필요한가

​Boost의 확장 아키텍처

​Agent 기저 클래스

​3개의 컨트랙트

​SupportsGuidelines 컨트랙트

​SupportsMcp 컨트랙트

​SupportsSkills 컨트랙트

​커스텀 에이전트의 작성

​가이드라인의 커스터마이즈

​guidelinesPath의 설정

​프런트매터가 필요한 에이전트

​가이드라인의 후처리

​커스텀 AI 가이드라인의 추가

​내장 가이드라인의 오버라이드

​커스텀 스킬의 추가

​SKILL.md의 작성

​請求書のPDF生成

​내장 스킬의 오버라이드

​서드파티 패키지에의 Boost 대응 추가

​가이드라인의 추가

​스킬의 추가

​실전 예: 독자 CI/CD 에이전트용 커스텀 에이전트

​참고 링크

ClaudeCode.php — 공식 구현 예

Agent Skills

Laravel Boost Custom Agent for GitHub Copilot CLI

Laravel Boost Custom Agent for PhpStorm with GitHub Copilot

왜 커스텀 에이전트가 필요한가

Boost의 확장 아키텍처

Agent 기저 클래스

3개의 컨트랙트

SupportsGuidelines 컨트랙트

SupportsMcp 컨트랙트

SupportsSkills 컨트랙트

커스텀 에이전트의 작성

가이드라인의 커스터마이즈

guidelinesPath의 설정

프런트매터가 필요한 에이전트

가이드라인의 후처리

커스텀 AI 가이드라인의 추가

내장 가이드라인의 오버라이드

커스텀 스킬의 추가

SKILL.md의 작성

請求書のPDF生成

내장 스킬의 오버라이드

서드파티 패키지에의 Boost 대응 추가

가이드라인의 추가

스킬의 추가

실전 예: 독자 CI/CD 에이전트용 커스텀 에이전트

참고 링크