easy-png-tools2/AGENTS.md

AGENTS.md

Краткий обязательный контракт. Правило: у каждой темы ровно один источник истины; здесь только то, что агент обязан знать до чтения остального, и то, что линтер не проверяет. Подробности — по ссылкам ниже.

Стек и команды

• SvelteKit (web/) — основное приложение, Svelte 5 (runes).
• pnpm обязателен, npm не использовать. Команды — из корня (pnpm build, pnpm dev, pnpm verify) или из web/ с префиксом pnpm --dir web.

Что	Команда
Полный быстрый gate	pnpm verify
Типы	pnpm --dir web check
Юнит-тесты	pnpm --dir web test
Тесты lint-правил	pnpm --dir web test:rules
Линтинг	pnpm --dir web lint:all
Только токены	pnpm --dir web lint:tokens
E2E	pnpm --dir web test:e2e
Форматирование	pnpm format (код + docs)
Проверка форматирования	pnpm check:docs + pnpm --dir web format:check

Что читать под задачу

Читать только нужную строку, а не все документы подряд.

Задача	Документ
Слои, поток данных, новый инструмент/поле	docs/architecture.md
Какие проверки запускать, пороги, CI	docs/quality-gates.md
Правка самих гейтов: «почему так, а не иначе»	docs/decisions.md
Порядок работы, нагрузка на машину	docs/agent-workflow.md
Locator-ы, fixtures, browser matrix	docs/testing-strategy.md
Детали lint-правил и токенов	web/eslint-plugins/README.md
Задачи и идеи	docs/backlog.md
Актуальный список инструментов	docs/tools-map.md
Правка полей и раскладки по волнам	docs/plan-fields-audit-fixes.md
Ручная приёмка UI	docs/checklist-manual-testing.md
Направления развития, фазы 1–11	docs/roadmap.md
SEO/GEO-план (адреса, noindex, sitemap)	docs/plan-seo.md
API/PWA/шрифты	docs/plan-platform.md
Сырые UX-находки по инструментам (вход аудита)	docs/tools-audit.md
Архивирование и удаление старых документов	docs/archive/README.md
Индекс остальных документов	docs/README.md

Инварианты, которые линтер не проверяет

• Сначала искать. Новая константа, тип или утилита не заводится, пока не найдено существующее определение — по ключу в соседних модулях и по всему web/src/.
• Комментарий объясняет «почему», а не пересказывает код. TODO/FIXME — только для зарегистрированной задачи: ссылка на docs/backlog.md и критерий закрытия.
• Один шаг — одна проблема, примерно до 500 строк; не смешивать lint, i18n, UI и рефакторинг.
• Не коммитить. Коммит и пуш делает разработчик после ревью. И не напоминать про них: пользователь сам решает, когда коммитить и деплоить, — в отчёте о шаге этого не предлагать.
• Не запускать тяжёлое без спроса. Playwright — только по явной команде пользователя, один прогон, без циклов повторов и фонового запуска.
• Не писать изменяемые числа (количество инструментов, тестов, локалей, проценты покрытия): вместо числа — ссылка на источник или команда. Число допустимо, только если его проверяет конфиг или тест. Обоснование и границы автоматизации — docs/decisions.md, раздел 3.
• Результат CI смотреть по отдельным job: у e2e стоит continue-on-error, поэтому общий conclusion может быть зелёным при красном e2e (docs/decisions.md, раздел 10).

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

• Production-UI — web/src/routes/** и web/src/lib/components/**.
• web/src/lib/core/** и web/src/lib/theme.svelte.ts — общие модули: их правка проверяется unit-тестами и smoke-сценариями production-потребителей.
• Направление зависимостей, точки расширения и рецепт правки (инструмент, вид поля, маршрут, токен) — docs/architecture.md, разделы 1–2, 7, 8.

Что проверяется линтером

pnpm --dir web lint:all — ESLint с --max-warnings=0 (warn-only правила тоже блокируют gate), Stylelint и token audit. Синтаксические ограничения здесь не дублируются: полный список правил и префиксы токенов — web/eslint-plugins/README.md; новое правило сначала появляется в warn-only режиме с fixtures и тестами (test:rules).

• E2E линтером не покрыт: порядок locator-ов, допустимые data-testid, test.fixme — docs/testing-strategy.md.

Дизайн

Источник правды по визуальному языку — код: web/src/app.css (дизайн-токены и глобальные стили), web/src/lib/components/** и витрина /kit. Новый дизайн живёт в app.css и применяется ко всем production-маршрутам; повторяющийся визуальный элемент — отдельный компонент, даже «просто div с двумя стилями»; дизайн-токены — только из CSS-переменных, новый токен появляется вместе с потребителем (pnpm --dir web lint:tokens сообщает о неиспользуемых). Приёмка — docs/checklist-manual-testing.md.

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

• Новый документ создаётся, только если темы нет в существующем; иначе обновляется источник истины. У документа есть статус (draft, active, completed, archived).
• Не дублировать длинные объяснения в нескольких файлах: короткая формулировка и ссылка на канонический документ.
• Отмеченная [x] задача — короткая запись: что решили и почему, без дат, пересказа сделанного и списка файлов — это видно из коммита. Длинный текст оправдан только там, где решение не восстановить из кода (отклонение от прошлого плана, причина нестандартного решения).
• Backlog живёт открытыми задачами: выполненные удаляются, а критичные для проекта факты переносятся в тематический документ. Завершённые планы и исследования — в docs/archive/, удаляются через 30 дней; процедура в docs/archive/README.md.