mirror of
https://github.com/Ku6epXBOCTuK/easy-png-tools.git
synced 2026-11-13 17:08:20 +00:00
103 lines
7.8 KiB
Markdown
103 lines
7.8 KiB
Markdown
# 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` |
|
||
| 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` |
|
||
| Ручная приёмка UI | `docs/checklist-manual-testing.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/**`. Старый UI
|
||
(`/v1/**`) удалён и не возвращается.
|
||
- `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`).
|
||
- Не дублировать длинные объяснения в нескольких файлах: короткая формулировка и
|
||
ссылка на канонический документ.
|
||
- **Backlog живёт открытыми задачами:** выполненные удаляются, а критичные для
|
||
проекта факты переносятся в тематический документ. Завершённые планы и
|
||
исследования — в `docs/archive/`, удаляются через 30 дней; процедура в
|
||
`docs/archive/README.md`.
|