mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-11-13 17:08:20 +00:00
90 lines
6.3 KiB
Markdown
90 lines
6.3 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 .` (код).
|
||
- Полный быстрый 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` и т.д.)
|
||
|
||
### Дизайн
|
||
|
||
Описание нового визуального языка — в `docs/plan-redesign.md`. Общие правила,
|
||
которые линтер не проверяет:
|
||
|
||
- Новый дизайн живёт в `web/src/app.css` и применяется ко всем
|
||
production-маршрутам.
|
||
- Все повторяющиеся визуальные элементы — отдельные компоненты в
|
||
`web/src/lib/components/`, даже «просто div с двумя стилями».
|
||
- Дизайн-токены (цвета, размеры, длительности, z-index) — только из
|
||
CSS-переменных; детали ограничений — в `web/eslint-plugins/README.md`.
|
||
|
||
## Документация
|
||
|
||
- Здесь держать только обязательные инварианты, команды и ссылки на подробные
|
||
документы; не превращать `AGENTS.md` в полный справочник.
|
||
- Индекс активных документов: `docs/README.md`; подробный workflow:
|
||
`docs/agent-workflow.md`; quality gates: `docs/quality-gates.md`; текущий
|
||
план: `docs/plan-codebase-quality.md`.
|
||
- Новые подробные правила, процедуры и таблицы хранить в `docs/`, а детали
|
||
конкретных lint-правил — в `web/eslint-plugins/README.md`.
|
||
- Завершённые или устаревшие документы переносить в `docs/archive/`, указывать
|
||
дату архивирования и срок удаления; архив — только справка, не источник
|
||
требований.
|
||
|
||
- Trunk-based: коммиты делает разработчик после ревью, самому не коммитить.
|
||
Изменения делать небольшими (< ~500 строк), атомарными.
|