Разработка административных панелей без боли: наш опыт с .cursor/rules

Мы не делаем вид, что пишем всё вручную — в работе активно используем ИИ-инструменты вроде Cursor. Это удобный способ автоматизировать рутину, ускорить типовые задачи и держать код в рамках заданных стандартов. Главное — задать эти стандарты правильно.

Параллельно мы развиваем свой open source фреймворк Admiral для сборки административных панелей. Там уже есть готовые компоненты, структура, документация — можно быстро собрать админку без лишней возни с базовыми вещами.

В какой-то момент мы решили объединить Cursor и Admiral. Добавили в проект директорию .cursor/rules, где описали правила для генерации CRUD-страниц, использования компонентов и хуков. Теперь не нужно каждый раз проверять структуру, валидность пропсов или соответствие внутренним стандартам — всё уже описано, и Cursor сам подсказывает, если что-то не так.

По сути, мы сформировали набор инструкций для ИИ, который помогает генерировать и поддерживать код в нужном состоянии. Это упростило процесс, уменьшило количество ошибок и позволило разработчикам сфокусироваться на нетривиальных задачах.

В этой статье покажем, как устроена интеграция, что именно автоматизируется и чем это может быть полезно в ваших проектах.

Что такое .cursor/rules?

.cursor/rules – это специальная директория, которая содержит правила для разработки в формате Markdown. Они интегрируются с IDE Cursor и помогают разработчикам следовать установленным стандартам при написании кода. Более подробную информацию можно найти в официальной документации. 

Основные правила

В текущей реализации Admiral включает три основных правила:

1. crud-page.mdc – правила создания CRUD-страниц со всей сопутствующей логикой.

2. admiral-components.mdc – документация по компонентам.

3. admiral-hooks.mdc – документация по хукам.

Правила admiral-components.mdc и admiral-hooks.mdc: документация по компонентам и хукам.

Данные правила автоматически включаются в контекст каждого запроса, чтобы AI-агенту было понятно как правильно использовать компоненты и хуки библиотеки, тем самым помогаем ему избежать ошибок, к примеру использования несуществующих пропсов или использования компонента не по назначению. 

Правило crud-page.mdc: стандартизация CRUD-разработки

Создание CRUD-страниц – основной функционал административной панели. Здесь правило crud-page.mdc отвечает за:

• Единообразие структуры всех CRUD-страниц;

• Стандартизацию именования переменных и функций;

• Четкую организацию файлов и папок;

• Использование только разрешенных компонентов из библиотеки @devfamily/admiral. 

Здесь от разработчика требуется только одно – продумать именование полей для форм, таблиц, фильтров и некоторых других базовых элементов.

Всё остальное за вас сгенерирует Cursor. Таким образом, это правило позволяет сэкономить львиную долю времени и сосредоточиться на действительно важных деталях проекта.

Как работает правило crud-page.mdc глазами AI-агента

Правило crud-page.mdc предоставляет AI-агенту Cursor полный набор инструкций для создания CRUD-страниц и всей сопутствующей логики. Рассмотрим, как устроен процесс и какие требования должны быть выполнены для использовании AI в разработку с Admiral.  

1. Основные принципы:

• AI получает четкие указания о том, что все CRUD-страницы должны следовать единой структуре

• Определены правила именования файлов, переменных и функций

• Указано, что страница должна находиться в папке, названной согласно первому пункту из списка, предоставленного пользователем

•  Определен список разрешенных компонентов для форм из библиотеки @devfamily/admiral

2. Структура CRUD-страницы

AI получает пошаговые инструкции по созданию файла:

• Как организовать импорты (React, хуки, компоненты);

• Как структурировать основную конфигурацию через createCRUD;

• Какие секции являются обязательными (path, resource, index, filter, form);

• Какие секции опциональны (actions, create, update, filter, topContent, bottomContent).

3. Структура файлов:

AI получает четкое представление о том, как должны быть организованы файлы:

admin/ ├── src/ │ └── crud/ │ └─── [resource]/ │ ├──── index.tsx # файл с конфигурацией CRUD-страницы │ ├──── types.ts # Типизация │ └────components/ # На случай необходимости использования кастомных компонентов └── config/ └─── menu.tsx # Файл, описывающий как должно выглядеть меню навигации   └── pages/ Роутинг └─── [resource]/ ├──── index.tsx # Страница с таблицей ├──── create.tsx # Страница с формой создания └──── [id].tsx # Страница с формой редактирования

4. Процесс создания:

AI знает, что для создания CRUD-страницы нужно:

• Создать соответствующие файлы в правильных директориях;

• Настроить маршрутизацию в pages;

• Добавить пункт меню, если это необходимо;

• Следовать типизации из библиотеки @devfamily/admiral;

• Проверить новосозданный код на наличие ошибок Typescript и линтеров, а затем исправить их.

5. Рекомендации по разработке:

AI получает конкретные указания по:

• Настройке таблиц (указание ширины колонок, рендеринг сложных типов данных);

• Организации фильтров (группировка, использование allowClear в селектах);

• Структуре форм (обязательные поля, использование columnSpan и декомпозиция компонентов полей форм);

• Действия таблицы (использование TopToolbar для кастомизации действий, добавление иконок).

6. Типизация:

 AI имеет доступ к информации о том, где найти полную типизацию:

• Путь к типизации: node_modules/@devfamily/admiral/lib/admiral/crud
     

Для доступа к типизации из node_modules, должна быть установлена зависимость @devfamily/admiral. 

7. Процесс взаимодействия с пользователем:  

AI знает, что должен:

• Запросить у пользователя список из 7 пунктов, если он не предоставлен изначально;

• Создать все необходимые файлы и структуру на основе этого списка.

8. Примеры кода:

AI имеет доступ к реальному примеру CRUD-страницы, который включает:

• Импорты компонентов;

• Настройку форм;

• Настройку фильтров;

• Конфигурацию таблицы;

• Настройку действий;

• Примеры использования различных компонентов.

Как AI использует правило crud-page.mdc в Admiral

Когда пользователь запрашивает создание новой CRUD-страницы, AI:

1. Проверяет наличие всех необходимых данных от пользователя.

2. Создает правильную структуру файлов и папок.

3. Генерирует код, следуя всем указанным правилам и стандартам.

4. Использует только разрешенные компоненты из @devfamily/admiral.

5. Создает все необходимые связи между файлами.

6. Добавляет необходимые пункты меню.

7. Находит и исправляет ошибки типизации и линтеров, в случае их наличия.

Это позволяет AI создавать качественные, стандартизированные CRUD-страницы, которые легко поддерживать и расширять в будущем. А вы, как разработчики, получаете следующие преимущества:

• Быстрое создание новых страниц через структурированный процесс;

• Единый стиль кодирования;

• Автоматическая проверка типов, linter-ошибок и их исправление;

• Частичная документация по проекту встроена прямо в IDE.

Как использовать правило

Если вам нужно создать CRUD-страницы, упомяните @crud-page правило в чате, и он самостоятельно запросит список от пользователя. Затем AI-агент задаст вам необходимые вопросы по списку. Вы также можете сразу предоставить на них ответы в следующем формате:

1. Базовое наименование. Это имя будет использовано в PascalCase для названия компонента, в kebab-case – для пути и папок в каталоге pages.

2. Ресурс. Используется для отправки запросов на сервер.

3. Список необходимых столбцов для таблицы. Необходимо передать список наименований «name», «age», «address», «phone».

4. Список обязательных полей для формы создания.

5. Список обязательных полей для формы редактирования. Если они совпадают с пунктом 4, оставьте поле пустым или укажите это.

6. Список названий полей, для которых необходимы фильтры.

7. Список названий полей, для которых необходимы быстрые фильтры (если они идентичны пункту 6, оставьте пустым или укажите так).

AI-agent будет запрашивать у вас разрешение на создание новых файлов и директорий, если такое разрешение не предоставлено заранее.

Правила admiral-components.mdc и admiral-hooks.mdc являются контекстом для любых AI-запросов в директории проекта. То есть они будут автоматически добавляться перед каждым запросом, чтобы AI-агент подробнее понимал, как правильно использовать компоненты и хуки пакета @devfamily/admiral.

Реальный пример создания CRUD-страницы с помощью rules.

Сначала вызываем правило в чате.

AI-агент не находит пользовательский список и запрашивает его, а мы в ответ присылаем все необходимые данные.

Далее AI-агент создает все необходимые файлы и проверяет заново созданный код на наличие ошибок типизации и линтеров, находит их и исправляет.

На выходе мы получаем все необходимые файлы без единой ошибки и можем дальше описывать инструкции для агента, чтобы и дальше редактировать новые файлы – с помощью Cursor либо вручную.

Заключение

Сейчас мы тестируем .cursor/rules на реальных проектах и по необходимости будем улучшать их. Команда Admiral планирует также добавлять новые инструкции, чтобы  покрыть как можно больше других аспектов разработки админ-панелей. Верим, что скоро процесс станет еще более эффективным и стандартизированным.