Как писать spintax-шаблоны с ИИ

Вы платите модели один раз — за шаблон. Дальше движок рендерит сколько угодно вариантов, локально и бесплатно. Эта страница про то, что между этими двумя фактами: что дать модели, о чём её попросить, как проверить результат и какие ошибки в spintax делает любая модель.

Коротко

Дайте модели документацию, дайте готовую статью, попросите один шаблон. Именно в таком порядке. Всё, что ниже, — подробности к этим трём шагам.

Обратите внимание, что именно делает модель: она не пишет, она размечает текст, который вы уже одобрили. Попросите то и другое сразу — получите шаблон, собранный из предложений, которые никто никогда не читал как предложения. Сначала напишите статью, в одной чистой версии, которую вы опубликовали бы как есть. Потом отдавайте.

Что дать модели

Сайт публикует свою документацию в машиночитаемом виде, так что объяснять spintax не нужно ничему. Выберите поверхность под свой инструмент.

Рядом с authoring-скиллом лежат ещё два. spintax-syntax — про сами конструкции и ловушку в каждой. spintax-engines — про то, как поставить и вызвать движок из JavaScript, PHP или Python. Для написания шаблонов нужен первый.

Промпт

Вот промпт, которым пользуемся мы. Он предполагает, что модель умеет открывать ссылки; если ваша не умеет — вставьте llms-full.txt перед ним и удалите две строки про ссылку.

Ты превращаешь готовую статью в ОДИН spintax-шаблон.

Сначала прочитай синтаксис и правила написания:
https://spintax.net/llms-full.txt
Если не можешь открыть ссылку, скажи об этом, и я вставлю файл текстом.

Приоритеты, в этом порядке:
1. Каждый отрендеренный вариант грамматически правильный.
2. Каждый отрендеренный вариант читается как написанный человеком.
3. Разнообразие — в последнюю очередь. Различие, которого читатель
   не заметит, не стоит ветвления.

Жёсткие правила:
- Никогда не ставь границу ветки внутри связанной грамматики:
  подлежащее и сказуемое, предлог и его дополнение, существительное
  и согласованное с ним прилагательное.
- Не повторяй фиксированный текст в обеих ветках. Ветви минимальный
  кусок, который различается.
- Используй %VAR% для всего, что меняется от сайта к сайту
  и от продукта к продукту.
- Используй #def, а не #set, когда две ссылки на одно значение
  должны совпадать.
- Используй только тот синтаксис, что описан в правилах выше.
  Не тащи конструкции из ICU, Handlebars или Jinja.
- Не выдумывай факты. Если в слот нужен факт, которого я тебе
  не давал, сделай переменную.

Верни:
1. Шаблон одним блоком кода.
2. Переменные, которые ты завёл, с примером значения для каждой.
3. То, что не удалось выразить в spintax, и почему.

Вот статья:
[вставьте сюда свою статью]

Две вещи в нём сделаны намеренно.

Он ссылается на правила, а не пересказывает их. Синтаксиса в промпте нет, и быть не должно. Документация в одном запросе и всегда актуальна; копия, вставленная в промпт полгода назад, — нет.

Приоритеты идут раньше правил. Предоставленная сама себе, модель оптимизирует видимое разнообразие — потому что шаблон выглядит именно как инструмент для этого. Грамматику и читаемость нужно поставить выше явно, иначе получите по четыре варианта в каждом слоте и кашу на выходе.

Три способа это запустить

Окно чата

Работает с любой моделью с большим контекстом. Вставляете llms-full.txt, вставляете промпт, вставляете статью. Ядро документации — около 100 КБ: для нынешних моделей комфортно, но не бесплатно. Если сессия длинная, authoring-скилл стоит долю от этого объёма и покрывает тот же метод.

Валидации здесь не будет. Модели нечем запустить шаблон, поэтому относитесь к результату как к черновику и несите его в песочницу.

Агент, который умеет читать документацию

В Claude Code, Cursor или любом агенте с доступом в сеть покажите ему скилл и дайте подтягивать страницы по мере надобности:

Загрузи https://spintax.net/.well-known/agent-skills/spintax-authoring/SKILL.md
и следуй ему. Подтягивай гайды по ссылкам оттуда, когда нужны детали.

Все ссылки внутри скилла уже ведут на .md-зеркала, так что агенту не придётся парсить веб-страницу, чтобы прочитать нашу документацию.

MCP-сервер

Вот эта настройка стоит пяти лишних минут. https://spintax.net/mcp — живой MCP-сервер, без авторизации, три инструмента:

• validate_spintax — диагностика с severity, стабильным кодом и строкой с колонкой (нумерация с 1). Нет ошибок — шаблон можно рендерить.
• render_spintax — до 20 вариантов, с seed для воспроизводимости и картой переменных для контекста.
• analyze_spintax — что шаблон требует и что содержит: используемые переменные, определения #set и #def, includes, счётчики конструкций.

В Claude Code — одна строка:

claude mcp add --transport http spintax https://spintax.net/mcp

В клиенте, который принимает конфиг-файл:

{
  "mcpServers": {
    "spintax": { "type": "http", "url": "https://spintax.net/mcp" }
  }
}

После этого допишите в конец промпта:

У тебя подключён MCP-сервер spintax.net. Прежде чем что-то мне показать:
вызови validate_spintax и почини все диагностики с severity "error",
затем вызови render_spintax с count 5 и прочитай варианты сам.
Если вариант читается криво — правь шаблон и повтори.

Разница здесь не косметическая. Без инструментов первый шаблон, который вы видите, — это первая догадка модели, и ревью уходит на поиск незакрытых скобок. С инструментами незакрытые скобки модель уже нашла, а ревью уходит на то, хороший ли получился текст.

Ограничения, чтобы вы их закладывали заранее: 8 КБ шаблона на вызов, 20 вариантов на рендер, #include на сервере отключён. Большие документы собирайте из секций и валидируйте по частям. Полное описание сервера — в его server card.

Петля, которая ловит проблемы

Каким бы инструментом вы ни пользовались, проверка одна и та же — три шага, и пропускают обычно третий.

1. Валидация. Структурные ошибки ищутся дёшево, и движок находит их за вас: песочница подчёркивает их прямо при вводе, validate_spintax возвращает их данными.
2. Двадцать вариантов, а не один. У шаблона с шестью ветками сотни исходов. Один рендер не говорит почти ничего — и обычно это тот самый рендер, из-за которого вы одобрили сломанный шаблон.
3. Прочитать их. Именно прочитать все двадцать. Проверьте каждое условие в обоих состояниях, каждую форму плюрала — включая числа, попадающие в редкую корзину (в русском: 1, 2, 5, 11, 21), и самый короткий с самым длинным исходом перестановки, где вылезают артефакты разделителей и пробелов.

Когда что-то читается криво, правьте шаблон, а не вариант, и рендерите двадцать заново. Модель может крутить эту петлю сама, если у неё есть MCP-инструменты — ради этого их и подключают.

Что модели делают не так

Это не случайные ошибки. Они повторяются от модели к модели, потому что растут из того, чему модель научилась в другом месте. Знание этого списка превращает расплывчатое «шаблон какой-то не такой» в двухминутную проверку.

Обратите внимание: почти ни одна из них не падает с ошибкой. Движок намеренно снисходителен — незнакомая конструкция теряет скобки и оседает в тексте обычной прозой. Шаблон проходит валидацию и рендерит криво. Ровно поэтому петля заканчивается чтением вариантов, а не зелёной галочкой.

1. Режет ветку по связанной грамматике

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

{Наша платформа|Наши инструменты} {создана|созданы} для небольших команд.
→ четыре комбинации, две из них грамматически неверные

{Наша платформа создана|Наши инструменты созданы} для небольших команд.
→ две комбинации, обе правильные

Подробно: грамматически безопасная синонимизация.

2. Хватается за #set, когда ссылки должны совпадать

Значение #set — это макрос: оно перекатывается при каждой ссылке. Модели выбирают его по умолчанию, потому что он читается как присваивание в языке программирования.

#set %tool% = {Slack|Jira|Linear}
Подключите %tool% в один клик. %tool% синхронизируется в обе стороны.
→ «Подключите Slack в один клик. Linear синхронизируется в обе стороны.»

#def %tool% = {Slack|Jira|Linear}
Подключите %tool% в один клик. %tool% синхронизируется в обе стороны.
→ «Подключите Jira в один клик. Jira синхронизируется в обе стороны.»

Подробно: переменные и переиспользование между сайтами.

3. Пишет плюралы синтаксисом чужой библиотеки

Модели видели несравнимо больше ICU MessageFormat, чем spintax, и это заметно. Ещё они по умолчанию берут две формы, а это неверно для русского, украинского, белорусского и сербского.

Поддерживаем {count, plural, one {# язык} other {# языков}}.
→ «Поддерживаем count, plural, one # язык other # языков.»

Поддерживаем %n% {plural %n%: язык|языка|языков}.
→ «Поддерживаем 21 язык.» / «Поддерживаем 5 языков.»

Две половины этой ошибки ведут себя очень по-разному, и это стоит знать. Заимствованный ICU — тихий вариант: диагностики нет вообще, потому что группа в скобках без разделителя | легальна, движок снимает скобки и печатает то, что внутри. Неверное число форм — громкий вариант: русскому нужны три формы, и если модель дала две, validate_spintax вернёт ошибку plural.arity, а в выводе конструкция останется неразвёрнутой. Привычка одна, а ловится только половина.

Подробно: согласование с числом.

4. Выдумывает условие

Привычки Handlebars и Jinja дают блоки {if …}, которые движок печатает как обычный текст.

Доставляем по всему миру. {if %HasCrypto%}Принимаем и криптовалюту.{/if}
→ «Доставляем по всему миру. If 1Принимаем и криптовалюту. /if»

Доставляем по всему миру. {?HasCrypto?Принимаем и криптовалюту.}
→ «Доставляем по всему миру. Принимаем и криптовалюту.»

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

Условие управляется значением. Когда выбор действительно произвольный, правильно {a|b}, а не условие.

Подробно: условный spintax.

5. Путает квадратные скобки с выбором

[a|b|c] перемешивает и склеивает все три элемента, разделяя их пробелом, если не настроено иначе. Он не выбирает один. Модель, которая имела в виду «выбери одно» и написала квадратные скобки, выдаёт предложение с тремя прилагательными там, где нужно было одно.

Попробуйте наш [быстрый|простой|доступный] инструмент.
→ «Попробуйте наш быстрый простой доступный инструмент.»

Попробуйте наш {быстрый|простой|доступный} инструмент.
→ «Попробуйте наш простой инструмент.»

Попробуйте наш [<minsize=2;maxsize=3;sep=", ";lastsep=" и ">быстрый|простой|доступный] инструмент.
→ «Попробуйте наш простой, доступный и быстрый инструмент.»
→ «Попробуйте наш простой и быстрый инструмент.»

Подробно: перестановки на практике.

6. Спинит каждое словосочетание

Без явных приоритетов модель считает целью плотность вариаций и ставит ветку в каждую фразу. Текст перестаёт звучать хоть как-нибудь.

{Наша|Эта} {платформа|система} {помогает|позволяет} {командам|группам}
выпускать {релизы|обновления} {быстрее|оперативнее|скорее}.

Значимые варианты — те, которые читатель заметит. Две ветки на своих местах в абзаце лучше двенадцати внутри одного предложения. Ради этого в промпте и стоит блок приоритетов.

7. Повторяет фиксированную часть в обеих ветках

Дублированный текст — приглашение к расхождению: следующая правка поменяет одну ветку и забудет вторую.

{Spintax (spin syntax) — это|Spintax, он же «spin syntax», — это} шаблонный язык.
→ «Spintax» и «это» продублированы в обеих ветках

Spintax {(spin syntax)|, он же «spin syntax»,} — это шаблонный язык.
→ фиксированные слова в одном экземпляре, ветвится только различие

Подробно: обратный порядок написания.

8. Кладёт внешние значения в контекст как есть

Значения переменных по умолчанию разметкоспособны: движок заново разбирает значение, в котором есть {, [ или %. Название товара из базы, строка от пользователя, заголовок со случайной скобкой — и шаблон отрендерит то, чего вы не писали. Недоверенные значения прогоняйте через neutralize() до того, как они попадут в контекст.

Подробно: переменные и переиспользование между сайтами.

9. Пишет один гигантский шаблон

Попросите целый лендинг — получите один неревьюабельный блок. Дальше экрана шаблон надо резать: item рендерит одну единицу, section собирает items, оркестратор собирает секции. Каждый кусок остаётся проверяемым отдельно, а лимит MCP-сервера в 8 КБ перестаёт быть лимитом.

Подробно: композиция шаблонов.

Перед тем как отгружать шаблон

• Двадцать вариантов отрендерены и правда прочитаны.
• Каждое условие увидено в обоих состояниях.
• Каждая форма плюрала увидена, включая редкую корзину.
• Нигде нет #set там, где две ссылки должны совпадать.
• У каждой переменной из шаблона есть значение на момент рендера.
• Недоверенные значения нейтрализованы.
• Самый короткий и самый длинный исход перестановки одинаково корректны по пунктуации.

Сколько это стоит

Один шаблон — это один разговор с моделью, а весь последующий рендер бесплатный: движок работает локально, детерминированно, без API-вызова на каждый вариант. В этом весь экономический смысл такого процесса, и он разобран по моделям, с актуальными ценами, в статье сколько на самом деле стоит контент с ИИ.

Дальше — рендер

Полученный шаблон без изменений работает на любом движке семейства: @spintax/core в JavaScript, spintax/core в PHP, spintax-core в Python и WordPress-плагин. Один синтаксис, один результат, один общий корпус тестов. Выбрать движок — в обзоре четырёх движков.