🦸 obra / Superpowers

Традиционный подход — написать правила в CLAUDE.md и надеяться что Claude их соблюдёт. Проблема: Claude читает правила, но в сложных задачах может "забыть" применить их, особенно в середине длинной цепочки действий.

Superpowers решает это иначе: вместо пассивных правил — активные протоколы. Скилл не просто описывает правила, он создаёт обязательную последовательность действий которую Claude должен пройти перед, во время и после задачи.

npm install -g superpowers-dev

# Или добавить скилл вручную в настройки Claude Code:
# Settings → Skills → Add Skill → вставить URL репозитория

Скилл вызывается через инструмент Skill в начале сессии:

// Перед реализацией фичи:
Skill: brainstorming
args: "новая система подписок для SaaS"

// Перед написанием кода:
Skill: writing-plans

// При написании кода с тестами:
Skill: test-driven-development

Самый частый источник плохих результатов с AI: разработчик не до конца продумал что хочет построить, а Claude строит не то. Скилл brainstorming решает это через Socratic questioning — один вопрос за раз.

Как работает скилл:

1. Claude задаёт уточняющие вопросы по одному — не все сразу
2. Каждый ответ определяет следующий вопрос
3. Диалог продолжается пока дизайн решения полностью не согласован
4. Claude формулирует итоговый spec и просит подтверждения
5. Только после явного user approval переходит к writing-plans

Результат сессии brainstorming автоматически записывается в файл:

docs/superpowers/specs/YYYY-MM-DD-feature-name.md

Этот файл становится основой для плана. Он хранится в проекте и может быть прочитан в будущих сессиях для восстановления контекста.

После согласования дизайна скилл writing-plans создаёт детальный план выполнения. Ключевое ограничение: каждый шаг = 2–5 минут работы. Шаги не должны быть абстрактными.

## Фаза 1: База данных

### Шаг 1.1: Миграция subscriptions (3 мин)
Файл: database/migrations/2026_05_10_170000_create_subscriptions_table.php
Создать таблицу: id, user_id, plan, status, stripe_id, trial_ends_at, ends_at, timestamps

Верификация:
- [ ] php artisan migrate --pretend | grep subscriptions
- [ ] Нет конфликтов с существующими таблицами

### Шаг 1.2: Модель Subscription (2 мин)
Файл: app/Models/Subscription.php
Добавить: $fillable, $casts, belongsTo(User)

Верификация:
- [ ] php artisan tinker --execute="Subscription::query()->toSql()"

## Фаза 2: Сервисный слой

### Шаг 2.1: SubscriptionService (5 мин)
...

Требования к хорошему плану:

• Точные file paths — не "создай сервис", а "создай app/Services/SubscriptionService.php"
• Чекбоксы [ ] → [x] при выполнении — визуальный прогресс
• Конкретная верификация — исполняемая команда, не "проверь что работает"
• Зависимости явные — "только после завершения шага 2.1"

Скилл test-driven-development делает TDD не опциональным, а обязательным. Claude не может написать реализацию без красного теста.

Что скилл предотвращает:

• Написание "тестов" которые проверяют тривиальные вещи задним числом
• Пропуск красной фазы ("тест явно упадёт, зачем проверять")
• Преждевременную оптимизацию вместо прохождения теста
• Рефакторинг без защитной сетки тестов

# RED: Написать тест который падает
test('subscription can be created for user', function () {
    $user = User::factory()->create();
    $service = app(SubscriptionService::class);

    $subscription = $service->subscribe($user, 'pro');

    expect($subscription)->toBeInstanceOf(Subscription::class)
        ->and($subscription->plan)->toBe('pro')
        ->and($subscription->user_id)->toBe($user->id);
});
# Запустить: КРАСНЫЙ (SubscriptionService не существует)

# GREEN: Создать минимальную реализацию
# Запустить: ЗЕЛЁНЫЙ

# REFACTOR: Улучшить не нарушая тест

Один из главных антипаттернов AI-разработки: Claude объявляет "готово" без реальной проверки. Скилл verification-before-completion создаёт жёсткий барьер.

Что требует скилл перед завершением:

• Тесты: реальный вывод npm test или php artisan test — не "тесты должны пройти"
• Типы: вывод tsc --noEmit или phpstan analyse
• Lint: вывод eslint / pint
• Build: вывод npm run build если применимо

Если проверка показывает ошибки — Claude обязан их исправить перед объявлением завершения. Нельзя объявить "в целом работает, но есть несколько ошибок".

// Обязательный вывод перед "задача готова":

$ php artisan test --filter=Subscription
PASS  Tests\Feature\SubscriptionTest
✓ subscription can be created (45ms)
✓ subscription can be cancelled (32ms)
✓ active subscription status is correct (18ms)

Tests: 3 passed
Duration: 95ms

// Только после этого вывода — "задача завершена"

Для сложных фич скилл subagent-driven-development запускает двухэтапную независимую проверку через отдельные sub-агенты. Это решает проблему "конфирмационного байеса" — когда агент, написавший код, видит его как правильный.

Первый sub-агент: проверка соответствия spec

• Получает spec (из docs/superpowers/specs/) и реализацию
• Отвечает на вопрос: "соответствует ли реализация spec?"
• Не смотрит на качество кода — только на соответствие требованиям
• Создаёт список расхождений

Второй sub-агент: проверка качества кода

• Получает реализацию и примеры паттернов проекта
• Отвечает на вопрос: "соответствует ли код конвенциям проекта?"
• Не смотрит на spec — только на качество и стиль
• Создаёт список нарушений паттернов

Два независимых взгляда с разными фокусами дают значительно более полную картину чем одна общая проверка.