Bitrix Dev

---
name: bitrix-dev
description: >
  Разработка и код-ревью на PHP под 1С-Битрикс (сайт/интернет-магазин, «Управление сайтом») с проверкой по
  РЕАЛЬНОМУ коду ядра через инструменты, а не по памяти. Используй всякий раз, когда пишешь/правишь/ревьюишь
  PHP-код под Битрикс: компоненты, шаблоны, инфоблоки, D7 ORM (Bitrix\Main\*), события, агенты, обработчики,
  корзину/каталог/заказы (модули sale/catalog/iblock), REST-интеграции; реализуешь задачу по ЧТЗ; ищешь, как
  устроено ядро или что уже есть в /local. Срабатывай даже без слов «PHP/код/ревью», если речь о реализации в
  Битрикс. Железное правило: НЕ выдумывай API Битрикса и сигнатуры — проверяй по реальному коду ядра (Grep/Serena/
  bitrix-ci в vendor) и справке dev.1c-bitrix.ru, после правки прогоняй PHPStan и PHP-CS-Fixer. Правки — только в
  /local, структуру инфоблоков меняй миграциями. Анализ/архитектура — скилл bitrix-analyst.
---

# Разработка под 1С-Битрикс (PHP) — корректный, производительный и безопасный код по реальному коду

## Читать ПЕРЕД написанием кода (обязательно)
- **`references/quality-standards.md`** — свод качественного Битрикс-кода. Пиши сразу так, **даже если проверки
  выключены** (режим `off`/`warn`): линтер лишь подтверждает, а не заменяет знание. Там же мини-чек-лист самопроверки.
- **`references/php-version-matrix.md`** — что доступно в таргет-версии PHP проекта. **Синтаксис новее таргета не
  предлагать вообще** (8.4 property hooks на 8.3 = белый экран). Плюс оговорка по `strict_types` в компонентах.
- **`references/architecture.md`** — слои, Anti-Corruption Layer над легаси-ядром, DI (ServiceLocator только в
  composition root), паттерны/анти-паттерны, **критерии глубины: когда НЕ усложнять**.
- **`references/custom-framework.md`** — если в `version-stack.toml` есть `[[custom_layers]]` (**свой фреймворк
  подрядчика поверх Битрикс**, нередко 30-40% функционала): искать в ТРЁХ слоях — кастомный слой → ядро → `/local`.
  Документация Битрикс про их код ничего не знает; источник правды — их код.
- **`references/custom-core.md`** — если в проекте **правлено само ядро** (`core_modified = true`): сигнатуры и
  поведение брать по ФАКТИЧЕСКОМУ коду ядра, а не по докам вендора; такие места помечать `[правлено ядро]`.

## По ситуации
- **`references/errors-and-results.md`** — исключения в домене vs `Main\Result` на границе; PSR-3 логирование;
  ловушка `abortResultCache()` при исключении внутри кэша компонента.
- **`references/testability.md`** — как класть код, чтобы он был тестируем; unit без ядра vs интеграционные.
- **`references/legacy-refactoring.md`** — Strangler Fig, характеризационные тесты, резка God-класса, Rector.
- **`references/performance*`** и скилл `bitrix-performance` — если задача про скорость/объёмы.

## Локализация (сначала, если есть)
Если в скилле есть `references/local/` — прочитай ПЕРЕД работой: версии платформы/редакции, раскладка проекта,
конвенции компании. Локальное побеждает generic.

## Опциональность проверок
Проверки настраиваются (`config/checks.toml`, env `BITRIX_AI_CHECKS`): `off` / `warn` (по умолчанию — показать, не
блокировать) / `block`. **Качество кода не зависит от режима** — стандарты соблюдай всегда (см. quality-standards.md).

## Главное правило: спроси инструмент, не угадывай
Нейросеть врёт в деталях Битрикса (два ядра, много legacy, неполная api_d7). Источник истины — реальный код и справка:
- **Перед написанием** — найди, как уже сделано: Grep/ripgrep по `/local` и по ядру, `find_symbol` (Serena) по
  классам D7. Сигнатуры классов ядра — по реальному коду в `vendor/bitrix-toolkit/bitrix-ci` или стабам
  `matiaspub/bxApiDocs`, справка — dev.1c-bitrix.ru. НЕ по памяти.
- **После правки** — прогони **PHPStan** (`analyse --error-format=json`) и **PHP-CS-Fixer** (детерминированно —
  через `PostToolUse`-хук). До 3 циклов автоисправления.
- Нет поведения ни в коде, ни в справке — так и скажи. Механизм без сверки помечай **[проверить]**, не «верно».

## Два ядра — различай явно
- **Старое ядро (процедурное):** `$APPLICATION`, `$USER`, `$DB`; `CIBlockElement::GetList`, `CModule`, `CFile`,
  `CCatalogProduct`. Живёт и активно используется. Справка: dev.1c-bitrix.ru/api_help/
- **D7 (ООП):** `Bitrix\Main\*`, ORM (`Bitrix\Main\ORM\Query`, `EntityObject`), `EventManager`, `Application`,
  сервис-локатор, `Bitrix\Main\Data\Cache`/`TaggedCache`. **Новый код — на D7**, интеропись со старым. Справка:
  dev.1c-bitrix.ru/api_d7/ (неполна → смотри исходники ядра / курс «Разработчик Bitrix Framework»).

## Гейт: правки только в /local, ядро read-only
- **Не трогай `/bitrix/modules`** — при обновлении продукта перезаписывается, правки теряются и ломают систему.
- Кастомизация типового компонента — **копированием в `/local/components`**, не правкой ядра. Приоритет поиска у
  системы: `/local/*` → `/bitrix/*` (components, templates, modules, php_interface, activities).
- **Структуру инфоблоков/HL-блоков/свойств/прав** меняй миграциями (`sprint.migration`: `php migrate.php add/up`),
  не руками в БД/админке без версионирования.
- События/обработчики регистрируй в `/local/php_interface/init.php` (`AddEventHandler`/`EventManager::addEventHandler`).

## Reuse-first, производительность (prod-ready)
- Прежде чем писать своё — ищи готовое в ядре (модули main/iblock/sale/catalog) и marketplace.
- **Кэширование:** компоненты кэшируй (`$arParams['CACHE_TIME']`, `$this->StartResultCache()`); произвольные данные —
  `Bitrix\Main\Data\Cache` / `TaggedCache` (сброс по тегам инфоблока). Не делай тяжёлых запросов без кэша.
- **Запросы:** ORM D7 или `CIBlockElement::GetList` с явным `select`/`filter`; НЕ выбирай лишние поля; НЕ делай
  запрос в цикле (аналог 1С-грабли) — собирай `filter` по массиву ID.

## Безопасность (чек-лист ревью — Битрикс-специфика)
- **SQL-инъекции:** только ORM или `$DB->ForSql()`/подготовленные фильтры; никакой конкатенации ввода в запрос.
- **XSS:** вывод экранируй `htmlspecialcharsbx()` (не голый echo пользовательских данных).
- **Path traversal:** проверяй/нормализуй пути в файловых операциях (`CFile`, работа с `upload/`).
- **Права:** проверяй `$USER->CanDoOperation()` / права доступа перед действием; не доверяй `$_REQUEST`.
- **CSRF:** формы — с `bitrix_sessid()`/`check_bitrix_sessid()`.

## Стандарт кода
PSR-12 (у Битрикс нет своего codesniffer-ruleset). Прогон: `php-cs-fixer fix` (форматтер) + `phpcs --standard=PSR12`
(доп. проверки). Держи единый `.editorconfig`/ruleset с PhpStorm, чтобы не «воевать» стилем с IDE-ассистентом.

## Инструменты (каналы)
- **Хуки** (`.claude/settings.json`): после правки `*.php` → `php-cs-fixer fix` + `phpstan analyse --error-format=json`.
- **LSP**: `php-lsp` (Intelephense) для навигации; нужен `composer dump-autoload -o` и стабы ядра в includePaths.
- **MCP**: Serena (find_symbol/find_references по коду), `bitrix24/mcp-rest-doc` (справка REST), JetBrains MCP
  (диагностики/рефакторинги PhpStorm на рабочей станции).

## Что НЕ делает AI без человека
Правки структуры БД вне миграций; изменения в ядре `/bitrix`; деструктивные операции с данными магазина; передачу
персональных данных клиентов в модель. Любую правку человек принимает после проверки (в т.ч. в PhpStorm).