📋 CLAUDE.md: правила, спецификации, обучение

# CLAUDE.md — Laravel Project

> Читается Claude Code автоматически при открытии этой папки.
> Держать **< 150 строк** (длинные файлы игнорируются).

## Проект

**Название:** `phone-rosveb-ru`
**Цель:** API на Laravel 11 + Vue 3/Nuxt, PostgreSQL, Redis, Docker Compose.
**Прод:** `https://phone.rosveb.ru`
**Контейнеры:** `phone-rosveb-ru-backend-1`, `phone-rosveb-ru-db-1`

## Стэк

- PHP 8.3 / Laravel 11
- Vue 3 + Nuxt 3 (SSR)
- PostgreSQL 16, Redis 7
- Docker Compose, Caddy reverse proxy

## Модель

- **Default:** Sonnet 5 (быстро, дешевле).
- **Opus 4.8:** только `/brainstorm`, `/write-plan`, архитектурные решения на 50K+ строк.
- **Haiku 4.5:** rename, format, простой regex.

## Workflow новой фичи

1. `/brainstorm` → spec в `docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md`
2. `/write-plan` → план в `docs/superpowers/plans/YYYY-MM-DD-<feature>-plan.md`
3. `git worktree add E:/Clients/wt/<feature> feat/<feature> main`
4. `cd E:/Clients/wt/<feature> && claude`
5. `/execute-plan` — верификация на каждом шаге
6. `/request-code-review` → PR → squash → `git worktree remove`

## Стандарты кода

- **PHP:** PSR-12 + Pint (`./vendor/bin/pint`). Всегда `declare(strict_types=1)`.
- **Vue/TS:** ESLint flat config + Prettier. Composition API, `<script setup lang="ts">`.
- **SQL:** keywords UPPERCASE, identifiers snake_case.

## Примеры кода (эталоны)

Claude должен следовать паттернам из `examples/`:
- `examples/controller.example.php` — структура Controller
- `examples/service.example.php` — структура Service
- `examples/test.example.php` — структура Pest-теста

## Критические правила

- **БД:** только `mcp__postgres__query` (read-only). Перед миграцией — pg_dump вручную.
- **Git:** запрещены `--force`, `--no-verify`, `reset --hard`.
- **Файлы:** `database/migrations/`, `.env.production` — требуют подтверждения.
- **Тесты:** `/brainstorm` и `/write-plan` обязательны для любой фичи > 5 файлов.

## При буксовании

- Claude дважды дал неправильный ответ → `/clear` + переформулируй prompt
- Claude добавляет лишнее → «Реализуй ТОЛЬКО X. Не трогай Y.»
- Claude фейкает «всё работает» → «Запусти `./vendor/bin/pest` и покажи output»

## Запрещённые паттерны

- `$request->all()` без явного `$fillable` — уязвимость mass assignment
- Eloquent-запросы в Controller (только через Service/Repository)
- `any` в TypeScript без явного обоснования
- jQuery — проект использует Vue 3

# CLAUDE.md — Python ETL / FastAPI Project

## Проект

**Название:** `python-etl`
**Цель:** ETL-пайплайны + FastAPI REST API, PostgreSQL, Docker.
**Контейнер:** `python-etl-app-1`

## Стэк

- Python 3.12, FastAPI, SQLAlchemy 2, Alembic
- PostgreSQL 16, Redis (очереди Celery)
- Docker Compose, Pydantic v2

## Стандарты кода

- **PEP 8** + Ruff (`ruff check --fix && ruff format`)
- **Type hints везде** — проверяется mypy/pyright
- **Docstrings:** Google style (Args / Returns / Raises / Example)
- Max line: 100 символов
- `from __future__ import annotations` в начале файла

## Правила ETL

- Тестовая БД: SQLite in-memory (никакого prod-коннекта в тестах)
- Каждый шаг — атомарный, с логированием start/end/count
- При ошибке — rollback + запись в таблицу `etl_errors`
- Batch-size: не > 10K строк за транзакцию при INSERT

## Critical rules

- БД: только через `mcp__postgres__query` (read-only)
- Миграции — через Alembic вручную
- Никаких секретов в коде — только через `os.getenv()` или pydantic Settings
- `except Exception: pass` запрещён — логировать или пробрасывать

## Workflow новой фичи

1. `/brainstorm` → spec в `docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md`
2. `/write-plan` → план в `docs/superpowers/plans/YYYY-MM-DD-<feature>-plan.md`
3. `git worktree add ...`
4. `/execute-plan` — работаем по плану, верификация на каждом шаге

# Спецификация: Рекуррентные подписки через Tinkoff API

**Date:** 2026-05-08
**Status:** Approved
**Author:** (сгенерировано через `/brainstorm`)

## Цель

Добавить в `phone.rosveb.ru` возможность оформлять рекуррентные подписки
через Tinkoff Recurrent API. Пользователь один раз вводит карту →
каждый месяц деньги списываются автоматически.

## Архитектура

POST /api/v1/subscriptions
    → CreateSubscriptionRequest (валидация)
    → SubscriptionController::store
    → SubscriptionService::createRecurrentSubscription
    → TinkoffGateway::initRecurrent (HTTP call)
    → Subscription::create (БД)

## Модель данных

CREATE TABLE subscriptions (
    id               BIGSERIAL PRIMARY KEY,
    user_id          BIGINT NOT NULL REFERENCES users(id),
    recurrent_token  TEXT NOT NULL,
    status           VARCHAR(20) NOT NULL DEFAULT 'active',
    next_billing_at  TIMESTAMP NOT NULL,
    ...
);

## Что НЕ входит в scope

- Email-уведомления — отдельная задача
- Промокоды и скидки — отдельная задача

# Реализация по готовому плану:
Реализуй шаг 2.1 из @docs/superpowers/plans/2026-05-08-payment-plan.md
Соблюдай архитектуру из @docs/superpowers/specs/2026-05-08-payment-design.md

# Ссылка на архитектурное решение:
Напиши тесты согласно @docs/adr/0001-pest-over-phpunit.md

# Несколько файлов сразу:
Реализуй SubscriptionService, следуя
@docs/superpowers/specs/2026-05-08-payment-design.md
и паттернам из @examples/service.example.php

# 0001. Использовать Pest вместо PHPUnit

**Date:** 2026-05-08
**Status:** Accepted
**Deciders:** команда разработки

## Context

В проекте нужна стратегия тестирования PHP-кода.
Альтернативы: оставить PHPUnit, перейти на Pest, использовать оба.

## Decision

**Pest** — как единственный тест-раннер поверх PHPUnit.

Причины:
- Нативная поддержка в Laravel 11
- Fluent синтаксис (`expect($x)->toBe($y)`)
- Тест занимает 30–40% меньше строк
- `describe()` блоки — естественная группировка

## Consequences

- Позитивное: меньше boilerplate, быстрее писать тесты
- Нейтральное: PHPUnit остаётся engine под капотом
- Негативное: разработчики без опыта Pest требуют ~2ч онбординга

## Архитектурные решения (ADR)

- `docs/adr/0001-pest-over-phpunit.md` — тест-раннер: Pest
- `docs/adr/0002-redis-sessions.md` — хранение сессий: Redis
- `docs/adr/0003-repository-pattern.md` — паттерн доступа к данным
- `docs/adr/0004-pinia-over-vuex.md` — стейт-менеджер фронтенда

## Примеры кода (эталоны)

Claude должен следовать паттернам из `examples/`:
- `examples/controller.example.php` — структура Controller
- `examples/service.example.php` — структура Service
- `examples/test.example.php` — структура Pest-теста
- `examples/component.example.vue` — структура Vue SFC
- `examples/composable.example.ts` — структура Composable

<?php

declare(strict_types=1);

namespace App\Services;

use App\Models\Subscription;
use App\Repositories\SubscriptionRepository;
use Illuminate\Support\Facades\Log;

final class SubscriptionService
{
    public function __construct(
        private readonly SubscriptionRepository $repository,
    ) {}

    /**
     * @throws \App\Exceptions\PaymentException
     */
    public function createRecurrentSubscription(
        int $userId,
        int $planId,
        string $token,
    ): Subscription {
        // Логика — только здесь, не в Controller
        return $this->repository->create([
            'user_id'         => $userId,
            'plan_id'         => $planId,
            'recurrent_token' => encrypt($token),
            'status'          => 'active',
        ]);
    }
}

docs/
├── adr/                              # Архитектурные решения
│   ├── 0001-pest-over-phpunit.md
│   ├── 0002-redis-sessions.md
│   └── README.md                     # Индекс всех ADR
│
├── superpowers/
│   ├── specs/                        # После /brainstorm
│   │   ├── 2026-05-08-payment-subscriptions-design.md
│   │   └── 2026-05-10-notifications-design.md
│   └── plans/                        # После /write-plan
│       ├── 2026-05-08-payment-subscriptions-plan.md
│       └── 2026-05-10-notifications-plan.md
│
└── api/                              # OpenAPI / документация эндпоинтов

examples/                             # Эталонные файлы кода
├── controller.example.php
├── service.example.php
└── test.example.php

## Критические правила

### Git-безопасность
- Запрещены `--force`, `--no-verify`, `reset --hard` без явного подтверждения
- Коммит — только по явной просьбе. Формат: `feat:` / `fix:` / `refactor:`
- Перед миграцией БД — pg_dump вручную + подтверждение

### Работа с БД
- Только read-only через `mcp__postgres__query`
- Запись — только через миграции с явным подтверждением
- Batch INSERT: не более 10K строк за транзакцию

### Качество кода
- После PHP-изменений: `./vendor/bin/pint` обязательно
- После TS/Vue: `pnpm lint:fix` обязательно
- Запрещён `any` в TypeScript без комментария-обоснования

### Размер задач
- `/brainstorm` обязателен для фич > 5 файлов
- `/write-plan` обязателен для задач > 3 часов

### При буксовании
- Дважды ошибся → предложи `/clear` + переформулировать
- «Всё работает» недопустимо — показать реальный вывод команды

# CLAUDE.md — [Название проекта]

## Проект

**Название:** `my-project`
**Цель:** [Одно предложение]
**Прод:** `https://example.ru`
**Контейнеры:** `my-project-backend-1`, `my-project-db-1`

## Стэк

- [Язык] [Версия] / [Фреймворк] [Версия]
- [БД] [Версия], [Кэш] [Версия]
- Docker Compose, Caddy reverse proxy

## Стандарты кода

- [Стандарт]: команда проверки `[команда]`
- [Дополнительные соглашения]

## Критические правила

- БД: только read-only через MCP
- Git: запрещены `--force`, `--no-verify`, `reset --hard`
- Перед миграцией — backup вручную

## При буксовании

- Дважды ошиблись → `/clear` + переформулировать
- «Всё работает» — недопустимо, показать вывод команды

## Запрещённые паттерны

- [Антипаттерн 1 для вашего стека]
- [Антипаттерн 2 для вашего стека]

# CLAUDE.md — Nuxt/Vue Frontend

## Проект

**Название:** `nuxt-frontend`
**Цель:** SSR фронтенд на Nuxt 3, без собственного бэкенда.
**API:** потребляет Laravel API (`/api/v1/*`)

## Стэк

- Nuxt 3 (SSR), Vue 3 (Composition API), TypeScript
- Pinia, TailwindCSS, VeeValidate
- Vitest + Testing Library, Playwright (e2e)

## Стандарты

- ESLint flat config + Prettier (`pnpm lint:fix`)
- TypeScript `strict: true`
- Никакого Options API — только Composition API + `<script setup>`
- CSS: только Tailwind (никаких кастомных классов)

## Critical rules

- SSR: все composables должны работать server-side
- `useRuntimeConfig()` для env-переменных
- Никакого `localStorage/window` без `import.meta.client` guard
- Playwright — только для e2e тестов, не смешивать с chrome-devtools MCP