Контракты компонентов

Обязательные правила для AI-агентов и разработчиков

Контракты компонентов

Обязательные правила и контракты для AI-агентов и разработчиков, работающих с LIK-Learn

Аудитория: AI Агенты (Claude, ChatGPT, etc.) и разработчики Приоритет: КРИТИЧЕСКИЙ - Читай перед любой реализацией Последнее обновление: 2026-01-31

Назначение

Этот документ определяет строгие контракты, которым ОБЯЗАНЫ следовать AI-агенты и разработчики при работе с LIK-Learn. Нарушение контрактов ведёт к:

Сломанной функциональности
Несогласованной архитектуре
Сложности поддержки
Потраченному времени

Критическое правило: Читай перед реализацией

┌─────────────────────────────────────────────────────────────────────┐
│  ОБЯЗАТЕЛЬНЫЙ WORKFLOW                                              │
│                                                                     │
│  ПЕРЕД реализацией ЧЕГО УГОДНО:                                     │
│                                                                     │
│  1. ПРОЧИТАЙ соответствующую документацию из docs/                 │
│  2. ИЗУЧИ существующий код в site/src/ (если применимо)            │
│  3. СЛЕДУЙ установленным паттернам                                 │
│  4. НЕ ИЗОБРЕТАЙ - используй существующее                          │
│                                                                     │
│  Нарушение = Недействительная реализация                           │
└─────────────────────────────────────────────────────────────────────┘

Карта документации для задач

Задача: Создать новый атом

ОБЯЗАТЕЛЬНО ПРОЧИТАТЬ:

docs/PHILOSOPHY.md - Понять принципы
docs/architecture/ATOMS-DOMAINS.md - Структура доменов
docs/architecture/COMPONENT-CONTRACTS.md - Технические контракты
docs/components/ATOMS.md - Обзор атомов

ОБЯЗАТЕЛЬНО ИЗУЧИТЬ:

site/src/atoms/universal/ - Примеры существующих атомов
site/src/atoms/_core/Component.js - Базовый класс

ОБЯЗАТЕЛЬНО ПРОВЕРИТЬ:

К какому домену? (universal / math / immersive / другой)
Следует ли AtomContract?
Есть ли Hugo shortcode?

Задача: Создать новую механику

ОБЯЗАТЕЛЬНО ПРОЧИТАТЬ:

docs/PHILOSOPHY.md - Понять модульность
docs/architecture/COMPONENT-CONTRACTS.md - MechanicContract
docs/components/MECHANICS.md - Обзор механик

ОБЯЗАТЕЛЬНО ИЗУЧИТЬ:

site/src/mechanics/timer.js - Пример механики
site/src/mechanics/hp-bar.js - Пример механики

ОБЯЗАТЕЛЬНО ПРОВЕРИТЬ:

Оборачивает ли контент?
Модифицирует ли поведение?
Использует ли EventBus?
Есть ли Hugo shortcode с .Inner?

Задача: Создать контент (концепт/трек/путь)

ОБЯЗАТЕЛЬНО ПРОЧИТАТЬ:

docs/content/CONCEPTS.md - Структура контента
docs/CONTENT-GUIDELINES.md - Правила контента
docs/components/ATOMS.md - Доступная интерактивность
docs/components/MECHANICS.md - Доступные механики

ОБЯЗАТЕЛЬНО ПРОВЕРИТЬ:

Концепт: Одна папка в content/concepts/{id}/
Трек: ДВА файла - data/tracks/{id}.yaml + content/tracks/{id}.md
Путь: ДВА файла - data/paths/{id}.yaml + content/paths/{id}.md

РАСПРОСТРАНЁННАЯ ОШИБКА:

Создание только data/tracks/example.yaml
Результат: 404 - Hugo нужен также content/tracks/example.md!

Контракты типов компонентов

Atom Contract

interface AtomContract {
  // ОБЯЗАТЕЛЬНО реализовать
  render(): void;           // Генерировать контент
  getResult(): AtomResult;  // Вернуть результат
  reset(): void;            // Сбросить состояние

  // МОЖНО реализовать
  reveal(): void;           // Показать ответ
  validate(): boolean;      // Проверить состояние

  // НЕЛЬЗЯ реализовать
  wrapContent(): never;     // Атомы не оборачивают
}

Hugo интеграция:

Shortcode БЕЗ .Inner
Самодостаточный <div data-lik-component="atom-name">

Пример:

<!-- layouts/shortcodes/quiz.html -->
<div data-lik-component="quiz-question"
     data-lik-config='{{ $config | jsonify }}'>
</div>

Mechanic Contract

interface MechanicContract {
  // ОБЯЗАТЕЛЬНО реализовать
  wrap(content: HTMLElement): void;   // Обернуть контент
  modifyBehavior(): void;             // Изменить поведение

  // МОЖНО реализовать
  onChildEvent(event: Event): void;   // Реагировать на детей
  getState(): MechanicState;          // Текущее состояние

  // НЕЛЬЗЯ реализовать
  generateContent(): never;           // Механики не создают
}

Hugo интеграция:

Shortcode С .Inner
Оборачивает дочерний контент

Пример:

<!-- layouts/shortcodes/with-timer.html -->
<div data-lik-component="timer"
     data-lik-config='{{ $config | jsonify }}'>
  {{ .Inner }}
</div>

Tool Contract

interface ToolContract {
  // ОБЯЗАТЕЛЬНО реализовать
  render(): void;    // Генерировать UI
  toggle(): void;    // Показать/скрыть

  // МОЖНО реализовать
  save(): void;      // Сохранить данные
  load(): void;      // Загрузить данные

  // НЕЛЬЗЯ реализовать
  affectLearning(): never;  // Инструменты не тестируют
}

Hugo интеграция:

Обычно авто-включается в layout
Не shortcode

Container Contract

interface ContainerContract {
  // ОБЯЗАТЕЛЬНО реализовать
  layout(children: HTMLElement[]): void;  // Расположить детей

  // МОЖНО реализовать
  resize(): void;    // Адаптировать размер

  // НЕЛЬЗЯ реализовать
  modifyChildBehavior(): never;  // Контейнеры только располагают
  generateContent(): never;       // Контейнеры не создают
}

Hugo интеграция:

Shortcode С .Inner
Чистая разметка, без логики

Запрещённые паттерны

1. Создание файлов без чтения документации

ПЛОХО:
1. Вижу задачу "создать атом"
2. Сразу пишу код
3. Понимаю что не совпадает с паттерном
4. Переписываю всё

ХОРОШО:
1. Вижу задачу "создать атом"
2. Читаю ATOMS-DOMAINS.md
3. Изучаю site/src/atoms/universal/quiz-question.js
4. Следую установленному паттерну
5. Пишу код один раз

2. Изменение архитектуры без понимания

ПЛОХО:
- "Этот компонент слишком большой, разобьём"
- Разбиваю без понимания контрактов
- Ломаю композицию
- Система падает

ХОРОШО:
- "Этот компонент сложный"
- Читаю COMPONENT-CONTRACTS.md
- Понимаю публичный API vs внутренний
- Разбиваю внутреннее, сохраняю API
- Система работает

3. Изобретение новых паттернов когда есть существующий

ПЛОХО:
- Нужно ограничить время на quiz
- Создаю новый quiz-with-timer компонент
- Дублирую код
- Сложно поддерживать

ХОРОШО:
- Нужно ограничить время на quiz
- Читаю MECHANICS.md
- Использую существующую механику timer
- Композирую: <with-timer><quiz></quiz></with-timer>
- Переиспользую код

4. Неполное создание трека/пути

ПЛОХО:
- Создаю data/tracks/example.yaml
- Забываю content/tracks/example.md
- Hugo не генерирует страницу
- 404 ошибка

ХОРОШО:
- Читаю CONCEPTS.md "Трек требует 2 файла"
- Создаю ОБА файла
- Тестирую в Hugo
- Работает корректно

5. Неправильное использование CSS

ПЛОХО:
.my-component {
  background: #0000ff;  /* Хардкод синий */
}

ХОРОШО:
.my-component {
  background: var(--lik-primary);  /* CSS переменная */
}

Чеклист перед реализацией

Перед написанием ЛЮБОГО кода:

[ ] Прочитал соответствующую документацию
[ ] Изучил существующие примеры
[ ] Понимаю контракт компонента
[ ] Знаю к какому домену это относится
[ ] Проверил паттерн Hugo интеграции
[ ] Изучил дизайн-систему для стилей
[ ] Понимаю поток событий
[ ] Знаю что тестировать после реализации

Чеклист после реализации

После написания кода:

[ ] Код следует правильному контракту
[ ] Hugo shortcode создан (если нужен)
[ ] CSS использует переменные, не хардкод
[ ] События используют EventBus
[ ] Валидация входов реализована
[ ] Обработка ошибок добавлена
[ ] Комментарии для сложной логики
[ ] Протестировано в браузере
[ ] Протестирована клавиатурная навигация
[ ] Нет console.log (кроме debug)
[ ] SYNC-STATUS.md обновлён (если компонент)
[ ] Документация обновлена (если новая фича)

Деревья решений

“Это должен быть атом или механика?”

Генерирует ли свой контент?
├─ ДА → Связано ли с обучением/тестированием?
│        ├─ ДА → Атом
│        └─ НЕТ → Инструмент
└─ НЕТ → Оборачивает ли другой контент?
         ├─ ДА → Модифицирует ли поведение?
         │        ├─ ДА → Механика
         │        └─ НЕТ → Контейнер
         └─ НЕТ → Неправильная классификация, пересмотри требования

“К какому домену этот атом?”

Используется ли в 80%+ концептов?
├─ ДА → universal/
└─ НЕТ → Какая тема?
         ├─ Математика/Наука → math/
         ├─ Интерактивные истории → immersive/
         ├─ Программирование → code/ (создай если нужно)
         └─ Другое → Создай новый домен

Метрики успеха

Реализация успешна когда:

Работает - Функциональность корректна
Вписывается - Следует контрактам и паттернам
Протестирована - Ручные и автоматические тесты проходят
Задокументирована - Документация обновлена
Поддерживаемая - Код понятен, комментарии добавлены
Доступная - Работает с клавиатурой и скринридером
Производительная - Нет блокирующих операций
Композируемая - Работает с другими компонентами

Связанные документы

Философия почему так делаем
Планка строгости требования к достоверности материала
Каталог атомов что есть и когда НЕ брать
Структура контента концепты, треки, пути

Архитектура и реестры живут в репозитории: docs/ARCHITECTURE.md, docs/ATOMS.md, docs/MECHANICS.md.

Помни: Это контракты, не предложения. Следование им обеспечивает консистентный, поддерживаемый и композируемый код.

Нарушения: Ведут к переработке, техническому долгу и сломанной функциональности.

Успех: Приходит через понимание перед реализацией.