laravel:using-examples-in-prompts

プロンプトで例を使う

説明するよりも、例を示すほうが意図が伝わります。AI には、求める内容を言葉で伝えるだけでなく、実際に見せましょう。

既存のコードを参照する

抽象的な例

「決済サービスのようなサービスを作成してください」

具体的な例

「app/Services/PaymentService.php のパターンに沿って、OrderService を作成してください：

class PaymentService
{
    public function __construct(
        private PaymentGateway $gateway,
        private PaymentRepository $repository
    ) {}
    
    public function charge(Order $order): Payment
    {
        // Implementation
    }
}

コンストラクターインジェクションを使い、ドメインオブジェクトを返し、各メソッドの役割を絞ってください。」

効果： 参考にすべき構造、命名、パターンを示します。

望ましいスタイルを示す

曖昧な例

「一貫した命名を使ってください」

具体的な例

「app/Models/Product.php の命名規則に従ってください：

// Relationships: camelCase, descriptive
public function orderItems(): HasMany
public function primaryCategory(): BelongsTo

// Scopes: scope prefix, descriptive
public function scopeActive(Builder $query): void
public function scopePublishedAfter(Builder $query, Carbon $date): void

// Accessors: get prefix, Attribute suffix
public function getFormattedPriceAttribute(): string

新しい Subscription モデルにも同じパターンを適用してください。」

効果： 規則が実際にどう使われているかを、具体例で示します。

入出力の例

不明瞭な例

「商品データを変換してください」

明確な例

「API 用に商品データを変換してください：

入力（データベースから）：

[
    'id' => 1,
    'name' => 'Widget',
    'price_cents' => 2999,
    'created_at' => '2024-01-15 10:30:00',
    'category' => ['id' => 5, 'name' => 'Tools']
]

期待される出力：

{
    "id": 1,
    "name": "Widget",
    "price": "29.99",
    "category": "Tools",
    "created_at": "2024-01-15T10:30:00Z"
}

この変換には ProductResource を使ってください。」

効果： 正確な入力と期待される出力形式を示します。

具体例と抽象例

抽象的な例

「エラーを適切に処理してください」

具体的な例

「app/Services/PaymentService.php と同じ方法でエラーを処理してください：

try {
    $charge = $this->gateway->charge($amount);
} catch (PaymentGatewayException $e) {
    Log::error('Payment failed', [
        'order_id' => $order->id,
        'amount' => $amount,
        'error' => $e->getMessage(),
    ]);
    
    throw new PaymentFailedException(
        'Unable to process payment: ' . $e->getMessage(),
        previous: $e
    );
}

具体的な例外を使い、コンテキストをログに記録し、元の例外を保持してください。」

効果： 再現すべきエラー処理パターンを正確に示します。

抽象的な例

「テストを追加してください」

具体的な例

「tests/Feature/ProductTest.php のパターンに沿ってテストを追加してください：

test('user can create product with valid data', function () {
    $user = User::factory()->create();
    $category = Category::factory()->create();
    
    $response = $this->actingAs($user)
        ->postJson('/api/products', [
            'name' => 'New Product',
            'price' => 29.99,
            'category_id' => $category->id,
        ]);
    
    $response->assertCreated()
        ->assertJsonStructure(['data' => ['id', 'name', 'price']]);
    
    $this->assertDatabaseHas('products', [
        'name' => 'New Product',
    ]);
});

ファクトリーを使い、正常なケースとバリデーションエラーをテストし、データベースの状態を確認してください。」

効果： テストの構成、アサーション、参考にすべきパターンを示します。

例をドキュメント化する

新しいパターンを確立するときは、ドキュメントにまとめましょう：

「外部 API 連携向けの新しいサービスパターンを作成してください。テンプレートはこちらです：

// app/Services/External/BaseApiClient.php
abstract class BaseApiClient
{
    protected string $baseUrl;
    protected int $timeout = 30;
    protected int $retries = 3;
    
    abstract protected function authenticate(): array;
    
    protected function request(string $method, string $endpoint, array $data = []): array
    {
        // Retry logic, error handling, logging
    }
}

// app/Services/External/StripeClient.php
class StripeClient extends BaseApiClient
{
    protected string $baseUrl = 'https://api.stripe.com/v1';
    
    protected function authenticate(): array
    {
        return ['Authorization' => 'Bearer ' . config('services.stripe.secret')];
    }
    
    public function createCharge(int $amount): array
    {
        return $this->request('POST', '/charges', ['amount' => $amount]);
    }
}

すべての外部 API クライアントにこのパターンを使ってください。docs/patterns/external-apis.md に記載してください。」

効果： 将来も参照できる、再利用可能なパターンをドキュメントとともに作成します。

クイックリファレンス

例を活用しましょう：

• 既存のコードを示す - プロジェクト内の実際のファイルを参照する
• スタイルを実演する - 命名、構造、パターンが実際にどう使われているかを示す
• 入出力を提示する - 具体的なデータで変換内容を明確にする
• 実際のコードを使う - 一般的な例ではなく、コードベースのスニペットを使う
• パターンをドキュメント化する - 優れた例を再利用可能なテンプレートにする

例 ＞ 説明。言葉で伝えるだけでなく、見せましょう。