---
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 -->