mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 07:30:16 +03:00
354 lines
21 KiB
Markdown
354 lines
21 KiB
Markdown
---
|
||
name: template-generation
|
||
description: "Используй при создании, изменении или проверке повторяемой файловой структуры и шаблонов генерации. Триггеры: .templates, @gromlab/create, Template File Generator, scaffold, шаблон, генератор, создать компонент, модуль, layout, screen, widget, business, store, hook, service, page-entry, boilerplate, index.ts, типы, стили, тесты, повторить структуру без copy-paste, настроить генерацию файлов. НЕ используй для одноразовой точечной правки, code style, SLM-архитектуры без генерации файлов, Next.js routing, REST-клиентов или SVG sprites."
|
||
metadata:
|
||
internal: true
|
||
---
|
||
|
||
<!-- Generated from src/SKILL.md. Do not edit manually. -->
|
||
|
||
# Template Generation
|
||
|
||
## Генерация Файлов
|
||
|
||
Шаблоны генерации - способ создавать повторяемые структуры проекта через генератор, а не вручную.
|
||
|
||
Шаблон фиксирует проектное соглашение один раз: структуру папок, имена файлов, экспорты, типы, стили, тесты, базовую реализацию и правила именования. После этого страницы, модули, компоненты и другие повторяемые сущности создаются одинаково, без копипасты и случайных отличий.
|
||
|
||
### Рабочий Алгоритм
|
||
|
||
1. Определи, создаётся ли повторяемая структура или одноразовая правка.
|
||
2. Если задача затрагивает размещение кода, сначала определи архитектурное место через профильный skill. Для SLM Design используй `slm-design`.
|
||
3. Найди область шаблонов: корень проекта, приложение, пакет или самостоятельный участок монорепозитория.
|
||
4. Проверь наличие `.templates/`, локального README, npm scripts, scaffold-скриптов и документации проекта.
|
||
5. Если подходящий шаблон есть, запусти генератор из каталога области шаблонов.
|
||
6. Если шаблона нет, но структура повторяемая, создай шаблон в `.templates/` выбранной области и затем сгенерируй через него нужные файлы.
|
||
7. Если структура одноразовая или шаблон усложнит задачу, создай файлы вручную и не добавляй новый шаблон.
|
||
8. После генерации проверь структуру, имена, экспорты, публичный API и соответствие архитектуре проекта.
|
||
9. Если существующий шаблон устарел, исправь шаблон и затем регенерируй или точечно приведи результат к актуальному соглашению.
|
||
|
||
Не ограничивайся выполнением команды. Выбери правильный путь: использовать существующий шаблон, создать новый, обновить устаревший или отказаться от шаблона.
|
||
|
||
### Жёсткие Правила
|
||
|
||
- Не создавай повторяемую структуру вручную, пока не проверил наличие подходящего шаблона или генератора.
|
||
- Не копируй существующий модуль как способ генерации новой сущности.
|
||
- Не создавай новый шаблон в корне репозитория, если соглашение относится только к конкретному приложению или пакету.
|
||
- Если в `.templates/` есть `README.md`, прочитай его перед выбором шаблона.
|
||
- Для `@gromlab/create` запускай команду из каталога, где лежит нужная `.templates/`.
|
||
- Не передавай в `@gromlab/create` путь к шаблонам через flags. Позиционный `[путь]` является путём вывода.
|
||
- Не выдумывай внешний источник шаблонов. Используй локальные инструкции проекта или явное указание пользователя.
|
||
- Не меняй существующий генератор, CLI или набор шаблонов без задачи на изменение генерации.
|
||
- Не закрепляй в шаблоне нарушение архитектуры, импортов, публичного API или code style проекта.
|
||
|
||
### Локальные Материалы Skill
|
||
|
||
Каноны ниже достаточны для выбора шаблона, области и команды генерации. Для редких сценариев открывай только нужный локальный файл:
|
||
|
||
- [Настройка шаблонов](./reference/canons/setup.md) - установка и проверка набора шаблонов.
|
||
- [Next.js App Router + SLM](./reference/examples/nextjs-app-router-slm/README.md) - рабочий набор `.templates/`.
|
||
|
||
### Разделы Спецификации
|
||
|
||
- [Выбор Шаблона](#выбор-шаблона) - когда использовать существующий шаблон, когда создавать новый и когда отказаться от шаблона.
|
||
- [Область Шаблонов](#область-шаблонов) - где лежит `.templates/` в обычном проекте и монорепозитории.
|
||
- [Использование](#использование-шаблонов) - генерация через CLI, VS Code расширение и проектные генераторы.
|
||
- [Создание Шаблонов](#создание-шаблонов) - структура `.templates/`, переменные, модификаторы и требования к шаблону.
|
||
- [Настройка](./reference/canons/setup.md) - первичная установка или проверка набора шаблонов.
|
||
- [Примеры Next.js App Router + SLM](./reference/examples/nextjs-app-router-slm/README.md) - рабочий набор `.templates/` для Next.js App Router и SLM Design.
|
||
|
||
### Проблема
|
||
|
||
Каждый новый модуль, компонент, store или scaffold требует однотипной структуры файлов и boilerplate-кода. Ручное создание приводит к расхождениям, забытым `index.ts`, неверным именам, устаревшим копиям и ошибкам переименования после copy-paste.
|
||
|
||
### Решение
|
||
|
||
Повторяемые структуры создаются через `.templates/` и проектный генератор. Генератор принимает имя сущности, подставляет его в переменные шаблона и создаёт готовую структуру в нужной области проекта.
|
||
|
||
### Принципы
|
||
|
||
- Сначала проверь существующий шаблон или генератор проекта.
|
||
- Если шаблон есть, используй генератор вместо ручного создания файлов.
|
||
- Если шаблона нет, но структура повторяемая, сначала создай шаблон, затем сгенерируй через него нужные файлы.
|
||
- Ручное создание допустимо для уникального одноразового кода, точечных правок и случаев, где шаблон усложняет задачу больше, чем помогает.
|
||
- В монорепозитории выбирай `.templates/` внутри правильной области: приложения, пакета или самостоятельного участка репозитория.
|
||
- Локальные инструкции проекта и README внутри `.templates/` имеют приоритет над общими примерами.
|
||
|
||
## Выбор Шаблона
|
||
|
||
### Главное Правило
|
||
|
||
Когда нужно создать повторяемую структуру файлов, сначала проверь наличие шаблона или генератора.
|
||
|
||
Если подходящий шаблон есть, используй его.
|
||
|
||
Если шаблона нет, но сущность повторяемая и может понадобиться снова, сначала создай шаблон, затем создай файлы проекта через него.
|
||
|
||
### Повторяемые Структуры
|
||
|
||
К повторяемым структурам относятся:
|
||
|
||
- страницы;
|
||
- модули;
|
||
- компоненты;
|
||
- layout;
|
||
- screen;
|
||
- widget;
|
||
- business-домен;
|
||
- store;
|
||
- state manager;
|
||
- hook;
|
||
- service;
|
||
- scaffold из нескольких связанных файлов или папок.
|
||
|
||
Не создавай такие структуры вручную по умолчанию. Сначала проверь, можно ли создать их через шаблон или генератор проекта.
|
||
|
||
### Что Оформлять В Шаблон
|
||
|
||
Оформляй структуру в шаблон, если выполняется хотя бы одно условие:
|
||
|
||
- структура состоит из нескольких связанных файлов или папок;
|
||
- имена файлов, папок, типов, компонентов или экспортов выводятся из одного имени сущности;
|
||
- есть повторяемые экспорты, типы, стили, тесты или другой boilerplate;
|
||
- такая сущность может понадобиться в проекте повторно;
|
||
- ручное создание легко приведёт к расхождениям между похожими сущностями;
|
||
- структура отражает архитектурное или командное соглашение проекта.
|
||
|
||
### Когда Писать Вручную
|
||
|
||
Создавай без шаблона, если:
|
||
|
||
- код уникален для конкретной задачи;
|
||
- меняется существующий файл, а не создаётся повторяемая структура;
|
||
- структура не будет переиспользоваться;
|
||
- это небольшое точечное изменение;
|
||
- шаблон усложнит работу больше, чем поможет;
|
||
- человек явно попросил не использовать шаблоны.
|
||
|
||
Если есть сомнение, считай scaffold, boilerplate и группы связанных файлов кандидатами на шаблон.
|
||
|
||
### Анти-Паттерны
|
||
|
||
- Копировать существующий модуль и переименовывать его вручную.
|
||
- Создавать компонент, модуль или store руками при наличии подходящего шаблона.
|
||
- Добавлять новый тип повторяемой структуры без шаблона, если он отражает командное соглашение.
|
||
- Создавать шаблон в глобальной области, если структура нужна только конкретному приложению или пакету.
|
||
|
||
## Область Шаблонов
|
||
|
||
### Определение
|
||
|
||
Каталог, внутри которого лежит `.templates/`, является областью шаблонов.
|
||
|
||
Для `apps/web/.templates/` область шаблонов - `apps/web`. Для `packages/ui/.templates/` область шаблонов - `packages/ui`.
|
||
|
||
### Размещение
|
||
|
||
`.templates/` не обязана лежать в корне git-репозитория. В монорепозитории у каждого приложения или пакета могут быть свои шаблоны:
|
||
|
||
```text
|
||
apps/web/.templates/
|
||
apps/admin/.templates/
|
||
packages/ui/.templates/
|
||
```
|
||
|
||
Шаблоны размещаются в той области, где действует соответствующее проектное соглашение.
|
||
|
||
### Выбор Области
|
||
|
||
Перед генерацией определи правильную область шаблонов:
|
||
|
||
1. Найди ближайшую или явно подходящую `.templates/`.
|
||
2. Проверь README внутри `.templates/`, если он есть.
|
||
3. Убедись, что выбранный шаблон относится к нужному приложению, пакету или модулю.
|
||
4. Создавай новый шаблон в той `.templates/`, которая принадлежит этой области.
|
||
5. Запускай CLI из каталога области шаблонов.
|
||
|
||
Не считай корень репозитория единственным местом для `.templates/`.
|
||
|
||
### Локальный README
|
||
|
||
Если в найденной `.templates/` есть `README.md`, прочитай его перед выбором шаблона.
|
||
|
||
README может описывать доступные шаблоны, назначение, область применения, параметры и примеры команд. Локальный README имеет приоритет над общими примерами этого reference.
|
||
|
||
### Монорепозиторий
|
||
|
||
В монорепозитории выбирай `.templates/` по месту создаваемой сущности:
|
||
|
||
- код приложения `apps/web` генерируется из `apps/web/.templates/`;
|
||
- код админки `apps/admin` генерируется из `apps/admin/.templates/`;
|
||
- общий UI-пакет генерируется из `packages/ui/.templates/` или локальных шаблонов конкретного пакета;
|
||
- общий infra/shared-пакет использует шаблоны своей области.
|
||
|
||
Если шаблон нужен только одному приложению, не выноси его в корень репозитория без причины.
|
||
|
||
## Использование Шаблонов
|
||
|
||
### Приоритет Инструментов
|
||
|
||
Используй генератор проекта, если он явно задан локальной документацией или scripts.
|
||
|
||
Если проект использует `.templates/` без другого генератора, основной способ для AI-агента - CLI `@gromlab/create` через `npx`.
|
||
|
||
Для разработчика-человека удобный способ - VS Code расширение `Template File Generator | gromlab`.
|
||
|
||
### CLI
|
||
|
||
```bash
|
||
npx @gromlab/create <шаблон> <имя> [путь]
|
||
```
|
||
|
||
CLI ищет `.templates/` только в текущей рабочей директории.
|
||
|
||
Позиционный `[путь]` - папка вывода относительно текущей рабочей директории, а не путь к шаблонам.
|
||
|
||
В монорепозитории запускай CLI из каталога области шаблонов.
|
||
|
||
Глобальная установка не нужна. Используй CLI через `npx`.
|
||
|
||
Не используй `--templates`, `--templatesPath`, `--templates-path`, `--out` или `--output`: эти опции не поддерживаются CLI.
|
||
|
||
### Примеры CLI
|
||
|
||
```bash
|
||
npx @gromlab/create component header-nav src/compositions/layouts/default-layout/ui
|
||
npx @gromlab/create module hero-section src/compositions/screens/home/parts
|
||
npx @gromlab/create widget header src/compositions/widgets
|
||
npx @gromlab/create layout default-layout src/compositions/layouts
|
||
npx @gromlab/create business auth src/business
|
||
npx @gromlab/create store auth src/business/auth/stores
|
||
```
|
||
|
||
Пример для монорепозитория с шаблонами в `apps/web/.templates/`:
|
||
|
||
```bash
|
||
# рабочая директория: apps/web
|
||
npx @gromlab/create module button src/ui
|
||
```
|
||
|
||
### VS Code
|
||
|
||
`Template File Generator | gromlab` позволяет создавать файлы и папки из `.templates/` через интерфейс редактора:
|
||
|
||
1. Открыть контекстное меню на целевой папке.
|
||
2. Выбрать `Generate from template`.
|
||
3. Выбрать шаблон.
|
||
4. Ввести имя сущности.
|
||
|
||
Расширение устанавливается на машину разработчика, а не в проект.
|
||
|
||
### После Генерации
|
||
|
||
После генерации проверь:
|
||
|
||
- файлы созданы в правильной области проекта;
|
||
- имена файлов, типов, компонентов и экспортов соответствуют шаблону;
|
||
- публичные API не открывают лишние внутренние детали;
|
||
- результат не нарушает архитектуру проекта;
|
||
- если шаблон устарел, обнови шаблон, а не исправляй каждый новый scaffold вручную.
|
||
|
||
## Создание Шаблонов
|
||
|
||
<!-- @formatter:off -->
|
||
|
||
### Структура
|
||
|
||
Шаблоны лежат в `.templates/` внутри нужной области шаблонов. Каждый подкаталог внутри `.templates/` - отдельный шаблон.
|
||
|
||
```text
|
||
.templates/
|
||
├── component/
|
||
├── module/
|
||
├── screen/
|
||
├── layout/
|
||
├── widget/
|
||
├── business/
|
||
├── business-with-deps/
|
||
├── business-composition/
|
||
├── page-entry/
|
||
├── store/
|
||
└── hook/
|
||
```
|
||
|
||
### Содержимое Шаблона
|
||
|
||
Шаблон должен описывать проектное соглашение, а не только создавать пустые файлы.
|
||
|
||
Фиксируй в шаблоне:
|
||
|
||
- структуру папок;
|
||
- имена файлов;
|
||
- публичные и локальные экспорты;
|
||
- типы;
|
||
- стили;
|
||
- тесты, если они приняты в проекте;
|
||
- базовый boilerplate;
|
||
- правила именования.
|
||
|
||
После создания шаблона используй его для генерации нужной структуры.
|
||
|
||
### Переменные
|
||
|
||
Используй переменные для частей, которые меняются между сгенерированными сущностями.
|
||
|
||
Переменные можно применять в именах файлов, именах папок и содержимом файлов:
|
||
|
||
```text
|
||
{{name}}
|
||
{{name.pascalCase}}
|
||
{{name.camelCase}}
|
||
{{name.kebabCase}}
|
||
{{name.snakeCase}}
|
||
{{name.screamingSnakeCase}}
|
||
```
|
||
|
||
`name` - дефолтная переменная, которую генератор получает вторым позиционным аргументом.
|
||
|
||
### Пример
|
||
|
||
```text
|
||
.templates/component/
|
||
└── {{name.kebabCase}}/
|
||
├── styles/
|
||
│ └── {{name.kebabCase}}.module.css
|
||
├── types/
|
||
│ └── {{name.kebabCase}}-props.type.ts
|
||
├── {{name.kebabCase}}.tsx
|
||
└── index.ts
|
||
```
|
||
|
||
```ts
|
||
// .templates/component/{{name.kebabCase}}/{{name.kebabCase}}.tsx
|
||
export const {{name.pascalCase}} = () => {
|
||
return null
|
||
}
|
||
```
|
||
|
||
```ts
|
||
// .templates/component/{{name.kebabCase}}/index.ts
|
||
export { {{name.pascalCase}} } from './{{name.kebabCase}}'
|
||
```
|
||
|
||
### README Для Шаблонов
|
||
|
||
Если набор шаблонов неочевиден, добавь `.templates/README.md`.
|
||
|
||
Опиши в README:
|
||
|
||
- список шаблонов;
|
||
- назначение каждого шаблона;
|
||
- область применения;
|
||
- обязательные параметры;
|
||
- примеры команд;
|
||
- отличия похожих шаблонов.
|
||
|
||
### Запреты
|
||
|
||
- Не создавай шаблон, который закрепляет нарушение архитектуры проекта.
|
||
- Не добавляй в шаблон продуктовые детали, если шаблон должен быть общим для приложения или пакета.
|
||
- Не используй copy-paste существующего модуля вместо шаблона для повторяемой структуры.
|
||
- Не придумывай внешний источник шаблонов без инструкции проекта или явного указания человека.
|
||
|
||
<!-- @formatter:on -->
|