mirror of
https://github.com/gromlab-ru/slm-design.git
synced 2026-08-22 07:30:16 +03:00
feat: add example
This commit is contained in:
351
.opencode/skills/template-generation/SKILL.md
Normal file
351
.opencode/skills/template-generation/SKILL.md
Normal file
@@ -0,0 +1,351 @@
|
||||
---
|
||||
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."
|
||||
---
|
||||
|
||||
<!-- 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 -->
|
||||
Reference in New Issue
Block a user