# Vibe++: краткое описание языка

**Vibe++** - это структурированный формат описания проекта для LLM и AI-агентов.  
Он нужен не для написания кода напрямую, а для точной постановки задачи: что строить, для кого, на каком стеке, с какими ограничениями, в каком стиле и с какими правилами оформления.

## Зачем нужен Vibe++

Обычный prompt часто смешивает всё сразу: цель, ограничения, пожелания, стиль, архитектуру и требования к документации.  
Vibe++ раскладывает это по понятным блокам, чтобы модель:

- лучше понимала контекст
- различала обязательные и желательные требования
- стабильнее генерировала код
- меньше додумывала за автора

## Основные принципы

1. **Читаемость для человека и LLM**  
   Формат должен быть простым, понятным и предсказуемым.

2. **Структурированность**  
   Каждая часть описания проекта помещается в свой семантический блок.

3. **Опциональность блоков**  
   Почти все секции можно опускать. Vibe++ не должен превращаться в бюрократию.

4. **Приоритет правил**  
   Жёсткие требования должны быть явно отделены от рекомендаций и пожеланий.

5. **Практичность**  
   Файл должен помогать генерировать проект, а не просто красиво выглядеть.

## Формат

Обычно Vibe++ записывается в YAML-подобном виде.

Пример начала файла:

```yaml
vibepp: "0.1"

project:
  name: "My Project"
  type: "web-app"
  summary: "Краткое описание"
```

## Базовые блоки

### `project`
Идентификация проекта.

Содержит:
- название
- тип проекта
- краткое описание

### `purpose`
Назначение проекта.

Содержит:
- цель
- проблему
- ожидаемый результат

### `audience`
Для кого создаётся проект.

Содержит:
- пользователей
- целевую аудиторию
- при необходимости персонажей

### `context`
Контекст проекта.

Содержит:
- предметную область
- бизнес-контекст
- допущения

### `style`
Желаемый стиль решения.

Может описывать:
- общий vibe продукта
- стиль интерфейса
- стиль текста
- стиль кода

### `technology`
Технологический стек.

Может включать:
- frontend
- backend
- database
- infrastructure
- tooling
- технические ограничения

### `architecture`
Архитектурный подход.

Может включать:
- общий подход
- паттерны
- границы ответственности
- ключевые решения

### `project_structure`
Желаемая структура проекта.

Может включать:
- стиль организации
- модули
- директории
- назначение папок

### `features`
Функциональные границы.

Содержит:
- core
- secondary
- out_of_scope

### `quality`
Требования к качеству.

Содержит:
- приоритеты
- ограничения
- нефункциональные требования

### `documentation`
Правила документирования.

Может включать:
- обязательные файлы
- правила комментариев
- требования к API docs
- требования к архитектурной документации
- changelog

### `instructions`
Прямые инструкции модели.

Обычно делятся на:
- implementation
- naming
- testing
- delivery

### `rules`
Приоритетные правила.

Содержит три уровня:
- `hard` - обязательно
- `firm` - желательно, отклоняться только при причине
- `soft` - ориентир или предпочтение

### `accept`
Критерии приёмки результата.

Это список признаков, по которым можно понять, что задача выполнена правильно.

## Правила интерпретации

Если блок отсутствует, он считается **неопределённым**, а не запрещённым.

При конфликте секций приоритет такой:

1. `rules.hard`
2. `rules.firm`
3. `rules.soft`
4. `instructions`
5. `architecture`
6. `technology`
7. `style`
8. `notes`

Если стиль конфликтует с жёсткими требованиями, побеждают жёсткие требования.

## Правила по комментариям и документации

Vibe++ рекомендует:

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

Комментарии должны объяснять **почему**, а не пересказывать **что делает строка**.

## Минимальное ядро Vibe++

Для большинства задач достаточно таких секций:

- `project`
- `purpose`
- `style`
- `technology`
- `architecture`
- `documentation`
- `rules`

## Короткий пример

```yaml
vibepp: "0.1"

project:
  name: "FocusBoard"
  type: "web-app"
  summary: "Простой kanban для личных задач"

purpose:
  goal: "Сделать минималистичный task manager"
  problem: "Задачи разбросаны по разным местам"

style:
  product_vibe:
    - "minimal"
    - "clean"
    - "fast"

technology:
  frontend:
    - "Next.js"
    - "TypeScript"

architecture:
  approach: "modular monolith"

documentation:
  required_files:
    - "README.md"

rules:
  hard:
    - "код должен быть читаемым"
    - "README обязателен"
```

## Итог

**Vibe++** - это формат, который превращает расплывчатый prompt в понятную структуру проекта.  
Он помогает лучше передавать контекст, ограничения, стиль, архитектуру и требования к результату.  
Главная цель Vibe++ - сделать общение человека и AI при разработке более точным, стабильным и воспроизводимым.