mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-11-13 17:08:20 +00:00
77 lines
5.1 KiB
Markdown
77 lines
5.1 KiB
Markdown
# 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), тесты 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 .` (код).
|
||
- Линтинг: `pnpm --dir web lint` (ESLint). Полный прогон дизайн-проверок:
|
||
`pnpm --dir web lint:all` (ESLint + stylelint + токен-аудит). Каждый шаг
|
||
выполняется, даже если предыдущий упал. `app_v1.css` и legacy-ветка исключены
|
||
из новых правил; их долг чинится только по заведённым задачам, а новые
|
||
изменения не должны добавлять новые предупреждения без записи в baseline.
|
||
|
||
## Правила кода
|
||
|
||
Синтаксические ограничения описывать не нужно — они проверяются линтером (весь
|
||
список правил и токены-префиксы в `web/eslint-plugins/README.md`, прогон:
|
||
`pnpm --dir web lint` / `pnpm --dir web lint:all`). Здесь — только то, что
|
||
линтер не умеет.
|
||
|
||
### Svelte 5
|
||
|
||
Типизация пропсов через локальный `interface Props` закреплена правилом
|
||
`conventions/interface-props`; руками его нигде дублировать не надо.
|
||
|
||
### Сначала искать
|
||
|
||
Новая константа или тип не заводится, пока не произведён поиск существующего
|
||
определения (по ключу в соседних модулях и по всему `web/src/`). Это правило в
|
||
первую очередь для ИИ-агентов: дублирующее определение ухудшает правки в
|
||
нескольких местах и запутывает. (Синтаксис самих определений — под линтером:
|
||
строка `conventions/no-string-union-alias` и т.д.)
|
||
|
||
### Дизайн
|
||
|
||
Описание нового визуального языка — в `docs/plan-redesign.md`. Общие правила,
|
||
которые линтер не проверяет:
|
||
|
||
- Новый дизайн живёт в `web/src/app.css` (корневые маршруты), старый — в
|
||
`web/src/app_v1.css` (маршруты `/v1/*`).
|
||
- Все повторяющиеся визуальные элементы — отдельные компоненты в
|
||
`web/src/lib/components/`, даже «просто div с двумя стилями».
|
||
- Дизайн-токены (цвета, размеры, длительности, z-index) — только из
|
||
CSS-переменных; детали ограничений — в `web/eslint-plugins/README.md`.
|
||
|
||
## Документация
|
||
|
||
- Здесь держать только обязательные инварианты, команды и ссылки на подробные
|
||
документы; не превращать `AGENTS.md` в полный справочник.
|
||
- Индекс активных документов: `docs/README.md`; подробный workflow:
|
||
`docs/agent-workflow.md`; текущий план качества:
|
||
`docs/plan-codebase-quality.md`.
|
||
- Новые подробные правила, процедуры и таблицы хранить в `docs/`, а детали
|
||
конкретных lint-правил — в `web/eslint-plugins/README.md`.
|
||
- Завершённые или устаревшие документы переносить в `docs/archive/`, указывать
|
||
дату архивирования и срок удаления; архив — только справка, не источник
|
||
требований.
|
||
|
||
## Изоляция веток old ↔ new
|
||
|
||
Старый (`v1/`) и новый UI изолированы: `isolation/no-mixed-imports` резолвит
|
||
каждый импорт до файла и запрещает смешивание.
|
||
|
||
- Trunk-based: коммиты делает разработчик после ревью, самому не коммитить.
|
||
Изменения делать небольшими (< ~500 строк), атомарными.
|