Почему TeqFW использует только ES-модули?

Ни у кого не получится показать другому то, что тот не хочет или не может увидеть. Объяснять и показывать нужно только тем, кто а) может понять, б) хочет понять. В этой публикации я демонстрирую пару своих документов для LLM, которые предписывают «силиконовым«, какими правилами им следует руководствоваться при создании кода для моей платформы. «Силиконовым» можно впаривать любую дичь — они всеядные (могут понять) и покладистые (согласны понять). За это мы их и любим!

Кому интересно, что за инструкции — прошу под кат. Кто хочет сразу получить ответ на вопрос в заголовке — могут задать его (и множество других) соответствующему преднастроенному GPT-чату. Кто не хочет ни того, ни другого — в вашей ленте есть ещё куча других, более интересных публикаций.

Введение

Я пришёл к выводу, что инструкции для LLM нужно делить на две части:

• промпт: короткий документ (до 500 токенов), используется в качестве стартера для начала диалога;

• эмбеддинг: более обширный документ (до 4К токенов), который подшивается в базу знаний соответствующего LLM-агента.

Промпт

По сути, этот документ — свод правил, которые должны быть понятны разработчику сеньорского уровня. Нужно помнить, что из любого правила всегда бывают исключения, но правила существуют именно для того, чтобы ими руководствоваться в большинстве случаев. Категоричность тона промпта компенсируется повышенным раздолбайством аудитории (LLM), являющимся следствием её вероятностной природы.

# **Правила генерации ES-модулей в TeqFW**  LLM **должна строго следовать этим правилам** при генерации кода. **Отклонения недопустимы**.  ## **1. Только ES-модули (ESM)**  - **Единственный допустимый формат — ES-модули**. - Запрещены: CommonJS (`require()`, `module.exports`), UMD, AMD, IIFE и другие форматы. - **Нельзя использовать `require()`, `module.exports`, `export =`, `__dirname`, `import()` внутри   условий (`if`, `try`, `switch`)**. - Взаимодействие с модулями других форматов возможно **только в runtime-режиме**.  ## **2. Изоляция модулей**  - Модуль выполняется **автономно**, доступ к содержимому только через `export`. - **Не использовать глобальные объекты** (`globalThis`, `window`, `document`).  ## **3. Жёсткий контроль API**  - Экспортируемые сущности **неизменяемы** (использовать `Object.freeze()`, `const`). - **Запрещено изменять API после загрузки**.  ## **4. Явные зависимости**  - Все зависимости **передаются явно** через аргументы функций или классов. - Запрещены **статические и динамические импорты** (`import()`).  ## **5. Запрещены побочные эффекты при импорте**  - Импорт **не должен вызывать выполнение кода** (логирование, таймеры, сетевые запросы, изменение глобальных объектов   или хранилищ).  ## **6. Отсутствие внутреннего состояния**  - **Запрещены изменяемые глобальные переменные**. - Состояние должно передаваться в функции или классы извне.  ---  **LLM должна соблюдать эти правила и разъяснять несоответствия.**

Эмбеддинг

Это документ уровня мидла — в нём более подробно и более доступно, с примерами, объясняются те же самые концепции, что и в предыдущем документе. При прочтении держите в уме, что это документ для LLM, а не для людей (можете испытать дискомфорт при прочтении).

## Детализация правил генерации ES-модулей в TeqFW  ### 1. **Только ES-модули (ESM)**  TeqFW использует исключительно **ES-модули (ESM)** для генерации кода. Это означает, что **любые другие форматы, такие как CommonJS, UMD, AMD, IIFE, не поддерживаются**.  #### 🔹 **Почему это важно?**  - **ESM** является стандартом для модульности в JavaScript и гарантирует предсказуемость и совместимость. - **Использование `require()`**, **`module.exports`**, и **`export =`** из CommonJS **не допускается**. Модули на основе   этих подходов не могут быть использованы в TeqFW.  #### 🔹 **Пример плохой практики**:  ```js // Плохая практика - CommonJS const fs = require('fs'); module.exports = function readFile() {     fs.readFileSync('file.txt'); }; ```  #### 🔹 **Как работать с модулями других форматов?**  - Взаимодействие с модулями других форматов, например, **CommonJS**, возможно только в **runtime-режиме**, при этом   изоляция и совместимость с ESM сохраняются. Например, для таких адаптеров должны использоваться **фабричные функции   или мосты**.  ### 2. **Изоляция модулей**  В TeqFW **каждый модуль изолирован**, и его код не может влиять на глобальную область. Доступ к коду модуля осуществляется только через экспортированные сущности.  #### 🔹 **Почему это важно?**  - Изоляция модулей обеспечивает **безопасность** и **детерминированность**. Модули не могут случайно изменить глобальные   объекты (`globalThis`, `window`, `document`), что защищает от неожиданных побочных эффектов.  #### 🔹 **Пример хорошей практики**:  ```js // Правильная практика: модуль работает с экспортированными сущностями export const myFunction = () => {}; ```  ### 3. **Жёсткий контроль API**  Все экспортируемые сущности должны быть **неизменяемыми** (используйте `Object.freeze()` или `const`). После загрузки модуля API не должно изменяться.  #### 🔹 **Почему это важно?**  - **Жёсткий контроль API** предотвращает нежелательные изменения, обеспечивая стабильность взаимодействий с внешним   кодом.  #### 🔹 **Пример хорошей практики**:  ```js const API = Object.freeze({     process: () => console.log('Processing...') }); export default API; ```  ### 4. **Явные зависимости**  Все зависимости должны передаваться **явно** (например, через аргументы конструктора или фабричной функции). Запрещены * *статические и динамические импорты** внутри модуля.  #### 🔹 **Почему это важно?**  - Явное передача зависимостей помогает контролировать, какие библиотеки или функции используются внутри модуля, а также   избегать неявных связей и сложных для отладки ошибок.  #### 🔹 **Пример хорошей практики**:  ```js export default function createService({logger, fs}) {     return {         log: logger.log,         readFile: fs.readFileSync     }; } ```  #### 🔹 **Запрещённые практики**:  ```js // Плохая практика: использование динамического импорта без явного контроля export default async function loadLibrary() {     const lib = await import('./some-lib.js');     return lib.process(); } ```  ### 5. **Запрещены побочные эффекты при импорте**  При импорте модулей не должно происходить **выполнения побочных эффектов**, таких как логирование, запуск таймеров, сетевые запросы или изменения глобальных объектов.  #### 🔹 **Почему это важно?**  - Это позволяет избежать нежелательных изменений в среде выполнения при простом импорте модуля, что улучшает   предсказуемость кода и безопасность.  #### 🔹 **Пример плохой практики**:  ```js // Плохая практика - запуск таймеров при импорте import './someModule.js'; // запускает setTimeout ```  #### 🔹 **Пример хорошей практики**:  ```js // Правильная практика: побочные эффекты должны происходить только при явном вызове import {startTimer} from './timer.js';  startTimer(); ```  ### 6. **Отсутствие внутреннего состояния**  Модули не должны хранить **изменяемое внутреннее состояние**. Все данные должны передаваться в функции или классы извне.  #### 🔹 **Почему это важно?**  - Это упрощает тестирование и позволяет избежать неожиданных побочных эффектов, связанных с изменениями состояния внутри   модуля.  #### 🔹 **Пример плохой практики**:  ```js // Плохая практика: использование глобальных переменных внутри модуля let counter = 0; counter++; ```  #### 🔹 **Пример хорошей практики**:  ```js // Правильная практика: состояние передаётся извне export default function increment(counter) {     return counter + 1; } ```  ---  **LLM должна строго следовать этим правилам и разъяснять несоответствия**, если пользователь запрашивает несовместимый с ESM код. В таких случаях модель обязана предложить корректное решение, соответствующее принципам TeqFW.

Заключение

В комментариях к своей предыдущей статье я сформулировал вот такую мысль (спасибо коллеге @Per_Ardua за правильный вопрос):

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

Эти инструкции и эта публикация родились из попытки разобраться, а с какой, собственно, средой исполнения я имею дело, и что в этой среде для меня является принципиально важным?

Я ответил сам себе на эти вопросы и оформил их в виде инструкций для LLM. Но публикую я свои ответы не для того, чтобы вы их критиковали или оспаривали. Вы, конечно, можете делать и то, и другое, но… основное назначение этих документов — быть предупреждением:

Не надо пытаться пробовать Tequila Framework, если вы не согласны с изложенным здесь — вам она точно не понравится.

Если же кто-то решится попробовать — лучше обратитесь напрямую ко мне (контакты найдёте хоть на том же Хабре). Я помогу вам стартануть с проектом, чтобы вы избежали головной боли. Хотя… кто пил текилу, тот знает — если как следует принять, то головной боли на следующее утро не избежать.

Всем добра и вайб-кодинга!! 🧂🥃🍋‍🟩