easy-png-tools2/AGENTS.md

# AGENTS.md

Инструкции для агентов (и IDE-ассистентов) по работе с этим репозиторием.

## Стек

- **SvelteKit** (`web/`) — основное приложение, Svelte 5 (runes).
- Менеджер пакетов: **pnpm**. Запускать команды из `web/`, либо через обёртки в
  корне: `pnpm build`, `pnpm dev` (это `pnpm --dir web ...`). Не использовать
  npm.
- Сборка: `pnpm --dir web build`, проверка типов: `pnpm --dir web check`, тесты:
  `pnpm --dir web test` (Vitest), тесты с coverage-гейтом:
  `pnpm --dir web test:coverage`, тесты lint-правил:
  `pnpm --dir web test:rules`, e2e: `pnpm --dir web test:e2e` (Playwright,
  `web/e2e/`, свой webServer на `pnpm build` + `scripts/serve-static.mjs`, порт
  4173).
- Форматирование: `pnpm format` в корне (оба прогона) или
  `pnpm --dir web format` (только код web/). Проверка: `pnpm check:docs`
  (docs) + `pnpm --dir web exec prettier --check .` (код).
- Полный быстрый gate: `pnpm verify`; подробная матрица команд и CI —
  `docs/quality-gates.md`.
- После пуша результат CI проверяется явно: смотреть статусы отдельных job, а не
  общий conclusion прогона. У `e2e` стоит `continue-on-error`, поэтому прогон с
  упавшим e2e помечается как `success`. `Quality` workflow запускается на каждом
  пуше в `main` и на `pull_request`, поэтому browser matrix проверяется сама;
  ручной запуск нужен только для старого коммита.
- Линтинг: `pnpm --dir web lint` (ESLint). Полный прогон дизайн-проверок:
  `pnpm --dir web lint:all` (ESLint + stylelint + токен-аудит). Каждый шаг
  выполняется, даже если предыдущий упал. Новые изменения не должны добавлять
  предупреждения без записи в baseline.

## Правила кода

Синтаксические ограничения описывать не нужно — они проверяются линтером (весь
список правил и токены-префиксы в `web/eslint-plugins/README.md`, прогон:
`pnpm --dir web lint` / `pnpm --dir web lint:all`). Здесь — только то, что
линтер не умеет.

### Svelte 5

Типизация пропсов через локальный `interface Props` закреплена правилом
`conventions/interface-props`; руками его нигде дублировать не надо.

### E2E

- Сначала используй `role`, `aria-*`, label и стабильный `href`; `data-testid`
  разрешён только для source/result/verdict/empty-state.
- `test.fixme` допускается только для зарегистрированной задачи в backlog или
  checklist; после исправления тест и ссылку обновляют вместе.
- Полные переводы проверяются в unit-тестах; e2e проверяет поведение.
- Playwright-прогоны запускаются только по явной команде пользователя, по одному
  прогону, без циклов повторов и без фонового запуска: локально matrix идёт с
  `workers: 1`. Отзывчивость компьютера пользователя важнее скорости проверки —
  подробности в `docs/agent-workflow.md`.

### Сначала искать

Новая константа или тип не заводится, пока не произведён поиск существующего
определения (по ключу в соседних модулях и по всему `web/src/`). Это правило в
первую очередь для ИИ-агентов: дублирующее определение ухудшает правки в
нескольких местах и запутывает. (Синтаксис самих определений — под линтером:
строка `conventions/no-string-union-alias` и т.д.)

### Границы изменений

- Production — только текущие маршруты и `web/src/lib/components/**`. Старый
  UI (`/v1/**`) удалён и не возвращается: без redirects и совместимого режима;
  исторические упоминания живят только в `docs/archive/`. Будущий API-контракт
  `POST /v1/process` из `docs/plan-platform.md` не связан с удалённым UI-v1.
- `core/` и `theme/` — общие модули: их изменение проверяется unit-тестами и
  smoke-сценариями production-потребителей.

### i18n

- Новый пользовательский текст — только через словари и `t()`. Исключения:
  бренд, форматы и имена файлов, технические значения, registry source strings и
  `/kit`. Проверяется warn-правилом `i18n/no-hardcoded-user-text`, детали и
  список исключений — в `web/eslint-plugins/README.md`.
- Новые ключи добавляются во **все** локали сразу: паритет ключей и
  плейсхолдеров проверяет `i18n/dict-consistency`.

### Комментарии

- Комментарий объясняет «почему», а не пересказывает код.
- `TODO`/`FIXME` — только зарегистрированные задачи: ссылка на `docs/backlog.md`
  или issue и критерий закрытия. В коде незарегистрированных пометок не
  оставляем.

### Новые lint-правила

Новое правило сначала появляется в report-only/warn-only режиме, получает
fixtures и тесты (`test:rules`), и только после очистки baseline может стать
blocking. Учитывай: `lint:all` гоняет ESLint с `--max-warnings=0`, поэтому
warn-правило обязано приземлиться без срабатываний на текущем коде.


### Дизайн

Источник правды по визуальному языку — сам код: `web/src/app.css` (дизайн-токены
и глобальные стили), `web/src/lib/components/**` (компоненты и локальные стили)
и витрина `/kit`. Приёмка — `docs/checklist-manual-testing.md`, ограничения
линтера — `web/eslint-plugins/README.md`. Общие правила, которые линтер не
проверяет:

- Новый дизайн живёт в `web/src/app.css` и применяется ко всем
  production-маршрутам.
- Все повторяющиеся визуальные элементы — отдельные компоненты в
  `web/src/lib/components/`, даже «просто div с двумя стилями».
- Дизайн-токены (цвета, размеры, длительности, z-index) — только из
  CSS-переменных; детали ограничений — в `web/eslint-plugins/README.md`.
- Новый токен появляется вместе с потребителем: `pnpm --dir web lint:tokens`
  сообщает о неиспользуемых токенах, и это не блокирует CI только потому, что
  проверка оставлена предупреждением.

## Документация

- Здесь держать только обязательные инварианты, команды и ссылки на подробные
  документы; не превращать `AGENTS.md` в полный справочник.
- Индекс активных документов: `docs/README.md`; подробный workflow:
  `docs/agent-workflow.md`; quality gates: `docs/quality-gates.md`; тестовая
  архитектура: `docs/testing-strategy.md`.
- Новые подробные правила, процедуры и таблицы хранить в `docs/`, а детали
  конкретных lint-правил — в `web/eslint-plugins/README.md`.
- Завершённые или устаревшие документы переносить в `docs/archive/`, указывать
  дату архивирования и срок удаления; архив — только справка, не источник
  требований.

- Trunk-based: коммиты делает разработчик после ревью, самому не коммитить.
  Изменения делать небольшими (< ~500 строк), атомарными.