Дмитрий
58 lines
4.9 KiB
Markdown
58 lines
4.9 KiB
Markdown
# ADR-013: A1 backend-tooling — наполнение раздела карты A1
|
||
|
||
**Status:** Accepted
|
||
**Date:** 2026-05-20
|
||
**Контекст:** эпик A1 backend-tooling, spec `docs/superpowers/specs/2026-05-20-a1-backend-tooling-design.md`.
|
||
|
||
## Context
|
||
|
||
Раздел карты A1 «Программирование — backend» был тонким — 3 узла: Boost #10
|
||
(Laravel-контекст), Pint #11 (стиль), Larastan #12 (типы). Backend-смежное уехало
|
||
в другие разделы (Pest→A5, squawk/pg_partman→A9, deptrac→A6, openapi→A3, Sentry/Redis→A7).
|
||
Дефициты чистого A1: авто-рефакторинг, метрики сложности/архитектуры, кодифицированные
|
||
backend-конвенции Лидерры, коррелированная runtime-телеметрия. На Anthropic-marketplace
|
||
чистого backend-кодинга нет (knowledge-work + meta); A1 закрывается GitHub PHP-экосистемой
|
||
плюс одним self-authored скилом.
|
||
|
||
## Decision
|
||
|
||
1. **Rector (#64)** — `rector/rector` + `driftingly/rector-laravel` (Composer dev-dep).
|
||
Авто-рефакторинг + version-aware апгрейды. Конфиг `app/rector.php` — консервативный
|
||
старт (`deadCode` + `codeQuality`, БЕЗ type-declaration наборов и LaravelSetProvider).
|
||
- **Постура: manual/CI** (`composer rector` / `composer rector:fix`), **НЕ** блокирующий
|
||
lefthook. Spike dry-run = **16 файлов** (>5 порога → код-мутирующий инструмент не гейтит
|
||
коммит; прецедент promptfoo ML1). LaravelSetProvider — для разовых апгрейдов вручную.
|
||
2. **PHP Insights (#65)** — `nunomaduro/phpinsights` (Composer dev-dep). Метрики
|
||
complexity / architecture / maintainability. Конфиг `app/phpinsights.php`.
|
||
- **Постура: on-demand/CI** (`composer insights` с порогами `--min-*`), **НЕ** блокирующий
|
||
lefthook (BT9 — избегаем четверного гейта Pint/Larastan/deptrac/Rector). Style-ось
|
||
выключена (владелец стиля — Pint); акцент Complexity + Architecture.
|
||
3. **laravel-backend-patterns (#66)** — self-authored project-скил (`.claude/skills/`).
|
||
Кодификация backend-конвенций Лидерры (слоистость / RLS-aware / bcmath-деньги /
|
||
идемпотентность / partition-aware). Активен.
|
||
4. **NightOwl (#67)** — self-hosted runtime-телеметрия. **DEFERRED** (pending Б-1 / Linux).
|
||
Блокер: native-Windows без `pcntl`/`posix` (агент не запускается); OSS-версия без MCP
|
||
(MCP только managed); hosted = риск 152-ФЗ. Spike + условия активации:
|
||
`docs/backend/nightowl-spike.md`. Прецедент: Sentry #34 / Figma #44 / Jupyter #50.
|
||
|
||
## Boundaries (конфликт-аудит)
|
||
|
||
- **BT1** Rector ↔ Pint: трансформация vs форматирование — разные операции.
|
||
- **BT2** Rector ↔ Larastan: Rector чинит, Larastan находит — комплементарны.
|
||
- **BT3** Rector ↔ deptrac: трансформация кода vs граф слоёв — ортогональны.
|
||
- **BT4** PHP Insights ↔ Pint/Larastan: style/code оси выключены; уникум = complexity + architecture.
|
||
- **BT5** backend-patterns ↔ architecture-patterns #38: project-specific vs generic.
|
||
- **BT6** backend-patterns ↔ billing-audit #62: генерация (как писать) vs аудит (проверка денег) — ссылка.
|
||
- **BT7** NightOwl ↔ Sentry #34: коррелированный трейс vs ошибки/трейсбэки.
|
||
- **BT8** NightOwl ↔ Pail / Boost: сквозной трейс vs tail / снапшот по требованию.
|
||
- **BT9** PHP Insights blocking? — нет (избегаем четверного гейта); on-demand/CI.
|
||
|
||
## Consequences
|
||
|
||
- A1 непуст: 3 → 6 узлов активных (Boost/Pint/Larastan + Rector/PHP Insights/backend-patterns) + 1 DEFERRED (NightOwl).
|
||
- Новая off-phase подкатегория `backend-tooling` (16-я).
|
||
- Rector и PHP Insights **не гейтят коммит** (manual/CI) — осознанно, чтобы не дублировать
|
||
существующие блокирующие гейты (Pint/Larastan/deptrac) и не авто-мутировать код на коммите.
|
||
- Rector оставляет разовый задел чистки (16 файлов) — применяется вручную через `composer rector:fix` с ревью + полным прогоном тестов, не в этом эпике.
|
||
- NightOwl — capability-readiness: задокументирован, активация при появлении Linux/боевого сервера (Б-1).
|