🧠 Cole Medin

Medin выделяет три принципиально разных уровня использования AI для разработки. Каждый следующий уровень требует больше подготовки, но даёт значительно лучшие результаты.

Ключевое понимание: AI не "умнее" от лучшего промпта — он лучше работает когда видит достаточный и релевантный контекст. Context Engineering — это дисциплина управления этим контекстом.

Перед тем как попросить Claude реализовать новую фичу — создай INITIAL.md по строгому шаблону. Это не просто описание задачи, это полный контекст для AI-агента.

# Feature: [Название фичи]

## FEATURE
[Чёткое описание что нужно построить. Без воды, конкретно.]

Пример: Система подписок с тарифами Basic/Pro/Enterprise.
Пользователь выбирает тариф → оплата через Stripe → активация.

## EXAMPLES
[Похожий код в codebase который Claude должен имитировать]

Посмотри как реализованы похожие фичи:
./app/Http/Controllers/PaymentController.php  ← паттерн контроллера
./app/Services/UserService.php                ← паттерн сервиса
./tests/Feature/PaymentTest.php               ← паттерн тестов

## DOCUMENTATION
[Ссылки на документацию библиотек которые будем использовать]
- Laravel Cashier (Stripe): https://laravel.com/docs/cashier
- Stripe Webhooks: https://stripe.com/docs/webhooks

## OTHER
[Дополнительный контекст, ограничения, уже принятые решения]
- Не трогать: app/Http/Middleware/Authenticate.php
- Использовать существующую таблицу users, не создавать новую
- Webhook endpoint должен быть /stripe/webhook (уже задан в Stripe Dashboard)
- Тесты писать на Pest, не PHPUnit

Почему это работает: Claude получает не просто требования, а точки навигации по проекту. Он смотрит на похожие файлы → понимает архитектурные паттерны → воспроизводит их в новом коде.

Создай в корне проекта папку examples/ с эталонными файлами. Это не рабочий код — это образцы паттернов и конвенций, которые Claude должен воспроизводить.

examples/
  controller.example.php    ← эталон: структура контроллера, Dependency Injection
  service.example.php       ← эталон: бизнес-логика, Repository pattern
  test.example.php          ← эталон: Pest-тест, Feature vs Unit
  request.example.php       ← эталон: Form Request с валидацией
  component.example.vue     ← эталон: Vue SFC, Composition API, TypeScript
  composable.example.ts     ← эталон: useX composable, реактивность
  api-route.example.ts      ← эталон: Nuxt API route

Каждый файл — минимальный рабочий пример с комментариями:

<?php
// EXAMPLE: Паттерн сервиса в этом проекте
// Все сервисы: readonly class, DI через конструктор
// Нет прямого обращения к Model в Controller — всегда через Service

declare(strict_types=1);

namespace App\Services;

use App\Models\User;
use App\Repositories\UserRepository;

final readonly class ExampleService
{
    public function __construct(
        private UserRepository $users,
    ) {}

    public function findActive(): Collection
    {
        return $this->users->findWhere(['active' => true]);
    }
}

Когда пишешь INITIAL.md, ссылайся на нужные файлы из examples/. Claude прочитает их и автоматически применит те же паттерны к новому коду.

PRP — двухэтапный процесс который превращает расплывчатое описание фичи в детальный blueprint, а затем выполняет его по шагам с верификацией.

Смысл двухэтапности: на этапе генерации Claude "думает" об архитектуре свежим взглядом. На этапе выполнения он следует плану, не отвлекаясь на архитектурные решения. Разделение thinking и doing значительно повышает качество.

# PRP: Subscription System

## Architecture
- SubscriptionController (thin, delegates to SubscriptionService)
- SubscriptionService (business logic, Stripe integration)
- SubscriptionRepository (DB operations)
- StripeWebhookHandler (separate class, handles webhook events)

## Implementation Steps

### Step 1: Database Migration (5 min)
File: database/migrations/2026_05_10_create_subscriptions.php
Tables: subscriptions (user_id, plan, status, stripe_id, ends_at)
Validation: php artisan migrate --pretend

### Step 2: SubscriptionService (15 min)
File: app/Services/SubscriptionService.php
Reference: examples/service.example.php for DI pattern
Validation: php artisan test --filter=SubscriptionServiceTest

Ключевое отличие Context Engineering от обычного подхода: каждый шаг плана содержит чёткую, исполняемую проверку. Claude не переходит к шагу N+1 пока не прошёл верификацию шага N.

Пример шагов с validation gates:

## Step 2: Создать SubscriptionService
Файл: app/Services/SubscriptionService.php

Реализовать:
- subscribe(User $user, string $plan): Subscription
- cancel(Subscription $sub): void
- isActive(User $user): bool

Validation (выполнить перед переходом к Step 3):
  php artisan test --filter=SubscriptionServiceTest
Expected: 5 tests pass, 0 failures, 0 errors

## Step 3: Создать SubscriptionController
Только после прохождения Step 2 validation.

Файл: app/Http/Controllers/SubscriptionController.php
Reference: examples/controller.example.php

Validation:
  php artisan test --filter=SubscriptionControllerTest
  php artisan route:list | grep subscription

Типичные validation gates:

• Тесты: php artisan test --filter=X — конкретные тесты зеленые
• Типы: ./vendor/bin/phpstan analyse или tsc --noEmit
• Lint: ./vendor/bin/pint --test или eslint src/
• Роуты: php artisan route:list | grep feature — endpoint существует
• Миграция: php artisan migrate --pretend — нет конфликтов

1. Создать INITIAL.md по шаблону (Feature + Examples + Docs + Other)
2. Убедиться что в examples/ есть нужные эталонные файлы
3. Запустить /generate-prp INITIAL.md — получить blueprint
4. Просмотреть PRP, скорректировать архитектуру если нужно
5. Запустить /execute-prp prp.md — выполнение по шагам
6. Claude проходит validation gate каждого шага перед продолжением
7. Финальный code review — убедиться что конвенции соблюдены