Эта страница берёт пакет, который вы пишете в Markdown, и показывает XML, который вместо него читает ваш агент. По дороге вы узнаете, зачем VibeVM превращает каждый текст в XML и почему автору это ничего не стоит. Узнаете, как назвать правило так, чтобы машина могла на него указать. И научитесь делить длинный текст на короткий заголовочный файл и длинное тело — так программисты на C и C++ делят библиотеку. Вы соберёте один маленький пакет руками, посмотрите, как он компилируется, и докажете, что две формы — одно и то же. Заложите около получаса; агент не понадобится.
| Что | Зачем | Где взять |
| `vibe` | создаёт проект, конвертирует текст и компилирует его | [Установить vibe](../start/install-vibe.xml) |
| текстовый редактор | три коротких файла вы пишете руками | любой |
| около получаса | весь путь, без агента |
В проекте, который об этом просит, каждый текст, принесённый пакетом, ложится на диск как XML, в какой бы форме его ни написал автор. Эти тексты — [спецификации](../glossary/index.xml#specification): правила, которые пакет задаёт агентам, работающим под ним; а причина конверсии — читатель. Модель, которая читает `<TESTS-FIRST fact="true" status="spec/done">`, знает, где правило начинается, где кончается, как называется и в каком оно состоянии, не угадывая по вёрстке. Проза заставляет модель выводить все четыре ответа самой.
Измерения согласны с интуицией. В эталонном исследовании Юань Суй с коллегами дали GPT-3.5 и GPT-4 одни и те же таблицы, записанные шестью способами: от простого текста с разделителями до CSV, JSON, XML, HTML и Markdown ([WSDM 2024](https://arxiv.org/abs/2305.13062)). На семи видах вопросов разметка, называющая свои части, обошла тот же текст в прозе. Лучше всех оказался HTML — на 6,76 процента по цифре самой статьи. В одной задаче, где нужно сказать, где начинаются и кончаются части таблицы, XML набрал 96,00 процента против 93,00 у простого текста и 92,33 у Markdown. Исследование про таблицы, и ровно до этого места страница его и доводит.
Совет производителя говорит то же с другой стороны. Руководство Anthropic по промптам для Claude — рекомендация, а не исследование — советует оборачивать каждый вид содержимого в свой XML-тег, чтобы модель разбирала длинный промпт без двусмысленности ([руководство](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices)). Олег Чирухин, автор VibeVM, обнаружил это на собственной практике раньше, чем об этом сказала хоть одна опубликованная работа. Цель `xml` — форма, в которой живут проекты этого руководства, и та, которую спецификация называет будущей основной.
Имена значат не меньше скобок. Раздел становится элементом, названным по себе самому, `<tests-first title="Tests before fixes">`. Правило становится элементом, названным по своему идентификатору, с одним опознавательным атрибутом, `fact="true"`, так что читатель, ничего не знающий о вашем словаре, находит каждое правило одной проверкой. Первый читатель этого диалекта — агент, а тегу, который говорит, что в нём лежит, легенда не нужна.
Одно предостережение для тех, кто обучает модели. Свидетельства выше — про текст, который модель читает. Для текста, который модель пишет, всё наоборот: принуждение ответа к JSON, XML или YAML может стоить качества рассуждений ([Тэм с коллегами, EMNLP 2024](https://arxiv.org/abs/2408.02442)). VibeVM задаёт форму тому, что агент читает, и никогда — тому, что он отвечает, так что этот результат его не касается.
Под капотом две формы — одна сущность. Каждый документ, Markdown или XML, разбирается в одно дерево: заголовок, статус и разделы, вложенные по глубине заголовков. Внутри разделов лежат абзацы, списки, таблицы, блоки кода и цитаты, и некоторые из них несут [факт](../glossary/index.xml#fact) — одно именованное правило со статусом. vibe никогда не переписывает текст Markdown в текст XML. Он разбирает в дерево и печатает из него, в любую сторону.
Авторы компиляторов называют такое дерево *промежуточным представлением*, IR: единственная форма, в которую разбирает каждый фронтенд и из которой печатает каждый бэкенд. Компилятору для трёх языков и четырёх процессоров нужны три фронтенда и четыре бэкенда, а не двенадцать переводчиков, и правило, один раз сформулированное о дереве, действует для всех языков. У VibeVM та же форма: два фронтенда и два бэкенда, Markdown и XML с каждой стороны.
Дерево нужно ему по тем же двум причинам. Без него каждой паре форм понадобился бы свой конвертер, а конвертеры расходятся. Обзор кода в 2026 году нашёл внутри vibe четыре читателя Markdown, каждый со своим чуть иным диалектом: болезнь, от которой одно общее дерево и должно лечить. И каждый инструмент, читающий спецификацию, читает XML через то же дерево: проверка фактов, компилятор, который собирает список чтения агента, маршрутизатор, который разрешает адрес. Поэтому документ в XML и его двойник в Markdown дают каждому инструменту один и тот же ответ.
У дерева есть будущее за пределами конверсии. Компилятор называет его уровни — от текста одного документа до всего достижимого замыкания проекта, — и плагин компилятора может их читать и переписывать. Агент с длинным горизонтом когда-нибудь сможет планировать поверх этого замыкания: не стена текста, а граф именованных единиц с адресами. Это направление, а не возможность, которую можно запустить сегодня. И сам VibeVM — не агент. Он никогда не читает ваши правила, чтобы по ним действовать; он готовит текст, дерево и адреса для того агента, которого запускаете вы.
Вывод для вас прост. Пишите спецификации своих пакетов в Markdown — в форме, с которой уже справляются ваш редактор и ваши рецензенты. Каждое свойство формы XML придёт само: именованные элементы, факты, которые проверяет машина, адрес у каждого правила. Шаги ниже делают ровно это и в конце это доказывают.
1. Создайте проект в пустой папке, как на странице [Создать первый проект](../start/first-project.xml). Имя станет именем папки:
2. Откройте `review-lab/vibe.toml`, [манифест](../glossary/index.xml#manifest) проекта, и добавьте одну строку под `[project]`:
3. Дальше работайте внутри папки: `cd review-lab`.
Эта строка решает, в какой форме ляжет каждый текст, который приносит пакет. С `xml` vibe конвертирует то, что автор написал в Markdown, пока копирует пакет в проект, а XML копирует как есть. Ваши собственные файлы не конвертируются никогда. Без этой строки каждый файл сохраняет форму, в которой его написал автор.
1. Добавьте в проект пакет. Это `flow`, пакет рабочих правил для агента, и он просит формат `normal`, смысл которого объясняет шаг 4:
2. Откройте манифест, который написала заготовка:
3. Измените две строки: дайте пакету `description` и поставьте `link = "static"`. Конец файла станет таким:
[Тип связи](../glossary/index.xml#link-type) (*link type*) говорит, как текст пакета доходит до агента. При `static` vibe компилирует текст в тот единственный файл, который агент читает первым, целиком, в начале каждой сессии. При `dynamic`, выборе заготовки, он перечисляет файл, чтобы агент открыл его сам. Эта страница берёт `static`, чтобы вы увидели компилятор за работой.
Пакету нужны два документа. Первый — заметка, которую агент читает в начале сессии, [стартовый фрагмент](../glossary/index.xml#boot-snippet) (*boot snippet*) пакета. Второй — контракт: сами правила, каждое со своим адресом.
1. Замените заметку заготовки, `vibevm/vibepacks/org.acme/review/v0.1.0/vibevm/vibespecs/boot/10-flow-review.md`, на эту:
Строка, начинающаяся с `#use`, — директива: инструкция компилятору, а не проза. Она втягивает контракт перед заметкой, так что агент встречает правила раньше заметки, которая на них ссылается. Файлы этой страницы написаны по-английски, как и вывод команд, чтобы примеры совпадали с тем, что вы увидите у себя.
2. Создайте `vibevm/vibespecs/contract/REVIEW.md` в том же пакете:
Прочитайте файл так, как читает машина. Заголовок несёт [якорь](../glossary/index.xml#anchor) в фигурных скобках, `{#one-idea}`: имя, которым пользуется ссылка, часть адреса после `#`. Абзац, который открывается `@fact:ONE-IDEA`, — факт, одно заякоренное правило со статусом. `@status:spec/done` в его конце говорит, что правило решено и ещё не построено. Элемент `<status>` под заголовком — тот же маркер для всего документа. Якоря заголовков и идентификаторы фактов делят одно пространство имён, поэтому ни один не повторяется в документе дважды.
Регистр идентификатора — сигнал. Идентификаторы в верхнем регистре помечают правила с обязывающей силой; в нижнем — заголовки, вводные и заметки. Адрес первого правила — `spec://org.acme/review/contract/REVIEW#ONE-IDEA`. Он складывается из [координаты](../glossary/index.xml#coordinate) пакета, пути документа под `vibevm/vibespecs/` без расширения и якоря. Адрес не меняется, когда файл меняет форму.
3. Проверьте разметку пакета:
Проверка читает каждый документ под `vibevm/vibespecs/` пакета. Маркер на абзаце без якоря и идентификатор, определённый дважды, — ошибки, которые называют строку.
4. Установите пакет в его собственный проект:
Установка копирует пакет в `vibevm/vibedeps/`, конвертируя оба документа в XML. Она же компилирует [стартовую полосу](../glossary/index.xml#boot-lane) (*boot lane*) — упорядоченный список файлов, которые агент читает в начале сессии. Последние две строки диффа — это она: в `INDEX.md` появилась строка с именем скомпилированного файла, а `STATIC.xml` возник.
5. Откройте контракт таким, каким его прочитает агент:
Каждая часть названа по себе самой. Раздел `{#one-idea}` стал элементом `<one-idea>` с заголовком в атрибуте. Факт стал `<ONE-IDEA fact="true" status="spec/done">`. Префикс `@fact:` и суффикс `@status:` из текста исчезли: они были написанием, а дерево хранит только смысл. Строчная разметка Markdown — обратные кавычки, ссылки — едет внутри текста без изменений.
Контракт, который говорит всё, обходится дорого. Каждое слово стартовой полосы читает каждый агент в начале каждой сессии. Поэтому текст, который должен быть перед глазами всегда, хочет быть коротким, а рассуждение за ним хочет лежать там, куда агент дотянется, когда спросит. C решил задачу такой формы в 1970-е двумя файлами, и C++ сохранил это решение. Заголовочный файл, `.h`, в нескольких строках объявляет, что предлагает библиотека; единица трансляции, `.c` или `.cpp`, несёт реализацию. Все, кто пользуется библиотекой, включают заголовок, и никто не вставляет реализацию в собственный код.
VibeVM заимствует это разделение для текста. Пакет в формате `normal` держит под `vibevm/vibespecs/` две папки. `contract/` — заголовок: маленький, дешёвый в загрузке, поверхность, которую видят другие пакеты и агенты. `source/` — реализация: тяжёлое тело, которое втягивается только тогда, когда кто-то попросит. Компилятор C видит всю программу и сам сводит объявления с определениями; у vibe такого взгляда на ваш текст нет, поэтому контракт сам называет свою реализацию директивой `#source`. У формата по умолчанию, `simple`, ничего этого нет: такой пакет несут целиком и читают потому, что он есть.
Спецификации называют этот механизм наследованием, как в C++: один документ строится на другом, не копируя его текст. Втягивают две директивы, и с одной вы уже знакомы. `#use` называет документ или раздел, который нужно прочитать раньше текста, который им пользуется; компилятор копирует его вперёд, и копия приводит с собой всё, что втягивает сам скопированный документ. `#source` называет реализацию контракта, и компилятор компилирует её вслед за контрактом. В скомпилированном файле обеих директив уже нет — они израсходованы. Третья, `#embed`, вклеивает ровно один адресованный узел на то место, где стоит: макрос, а не include.
1. Создайте в пакете `vibevm/vibespecs/source/details.md`, реализацию контракта:
Каждый якорь здесь отличается от якорей контракта: `one-idea-why` рядом с `one-idea`; особые случаи ниже объясняют почему. Последний раздел — список, в котором каждый пункт — факт.
2. В `contract/REVIEW.md` добавьте одну строку после первого абзаца:
Адрес называет целый документ, без якоря, так что компилятор берёт его от заголовка и ниже.
3. Установите снова:
Ни один пакет не добавлен, поэтому полоса — единственная строка диффа: скомпилированный файл вырос на реализацию.
4. Спросите vibe, что агент читает первым:
Один пакет, связанный как `static`, и `x` говорит, что его текст скомпилирован в `STATIC.xml`.
5. Откройте скомпилированный файл:
Читайте сверху. Сначала комментарии: правила, по которым агент трактует метки в этом файле, затем таблица всех переименованных якорей. XML запрещает два дефиса подряд внутри комментария, поэтому `--` в метке там записано как `-%2D`; элементы ниже несут настоящие `--`. Затем один документ XML: сначала контракт, за ним реализация, вкомпилированная одним вложенным разделом. Последней идёт заметка из фрагмента — простой `<section>`, потому что у её заголовка не было якоря. Строк `#source` и `#use` больше нет.
Каждый якорь теперь несёт префикс `org-acme--review--` — метку своего происхождения. Два пакета, у которых раздел назван `root`, не столкнутся в одном файле, а таблица наверху говорит, чем стало каждое короткое имя. Ссылайтесь на исходный документ и никогда на этот файл: это кэш, который меняется всякий раз, когда меняется пакет.
6. Откройте запись, которую vibe хранит рядом со своей копией пакета:
`spec_format` называет цель, `converter_recipe` — версию конвертера. Каждая строка говорит, был файл скопирован (`copied`) или сконвертирован (`converted`), и несёт хэш того, что легло на диск. Держите этот файл в уме: шаг 5 прочитает его снова.
Конструкции, которыми пользовалась эта страница, бок о бок, из её собственных файлов:
| Markdown | XML |
| `# Review rules {#root}` | `<title id="root">Review rules</title>` |
| `<status stage="spec" state="done"/>` | тот же элемент, без изменений |
| `## One idea per change {#one-idea}` и текст под ним | `<one-idea title="One idea per change">…</one-idea>` |
| абзац | `<p>…</p>` |
| `@fact:ONE-IDEA … @status:spec/done` | `<p><ONE-IDEA fact="true" status="spec/done">…</ONE-IDEA></p>` |
| `- @fact:CHECK-SCOPE … @status:spec/done`, список фактов | `<facts ordered="false"><CHECK-SCOPE fact="true" status="spec/done">…</CHECK-SCOPE></facts>` |
| `#source spec://…`, директива | `<p>#source spec://…</p>`, простой абзац |
| `# Review flow`, заголовок без якоря | `<title>Review flow</title>` |
| обратные кавычки, выделение, ссылки, адреса `spec://` | те же символы внутри текста |
Диалект закрыт и мал нарочно. Он выражает ровно то, что выражает Markdown, поэтому конверсия в любую сторону не теряет смысла, а элемент вне диалекта — громкая ошибка, а не молчаливый пропуск. У двух якорей нет собственного элемента: у того, что начинается с цифры, и у того, что совпадает со словом самого диалекта, таким как `title` или `list`. Для них встают общие `<section id="…">` и `<fact id="…">`, и каждый читатель принимает оба написания. Единственное исключение из правила эквивалентности — словарь пакетов документации, к которым принадлежит и это руководство: у их выполняемых примеров и живых цитат нет формы в Markdown, и в Markdown они проецируются только в одну сторону.
Вы написали Markdown и отгрузили XML. Последний шаг показывает, что XML, который вы написали бы руками, — тот же файл, байт в байт.
1. Спросите конвертер, что потеряет конверсия:
Конвертер разбирает каждый файл в дерево, печатает XML, читает его обратно и снова печатает Markdown, а затем сравнивает. Вердикт `ir-stable-loss` значит, что дерево уцелело, а байты нет, и дифф показывает, что изменилось. Здесь это одна пустая строка в конце каждого файла, которую добавляет принтер Markdown. Без `--force` команда отказывает файлу из-за такой потери. В изменении смысла она отказывает всегда, потому что это был бы дефект конвертера, а не вашего файла.
2. Сконвертируйте три документа. Команда пишет каждый `.xml` рядом с его `.md` и удаляет `.md` тем же действием. Дерево никогда не держит документ в обеих формах:
3. В манифесте пакета направьте `source` на новый файл, `vibevm/vibespecs/boot/10-flow-review.xml`.
4. Установите снова:
5. Откройте запись ещё раз:
Сравните её с записью шага 4. Каждый из трёх документов теперь `copied`, и хэш каждого — тот же, что был у него как у `converted`. То, что конвертер написал из вашего Markdown, — это то, что из него написала установка, байт в байт. Скомпилированный файл тоже не изменился:
Те же байты, те же строки. Вот что значит на практике одна модель под капотом. Форма, в которой вы пишете, — ваш выбор; текст, который доходит до агента, один и тот же. Проект с `spec_format = "markdown"` проходит ту же дорогу в обратную сторону. Markdown, который он пишет из вашего XML, — ваш исходный файл плюс та самая пустая строка.
Ваш пакет живёт под `vibevm/vibepacks/org.acme/review/v0.1.0/`: манифест, README и три документа XML, которые правите вы. Копия vibe живёт под `vibevm/vibedeps/org.acme.review/0.1.0/` вместе с записью `.vibe-slot.toml` и переписывается при каждой установке. В `vibevm/vibespecs/boot/` лежат скомпилированный `STATIC.xml` и `INDEX.md`, чья строка `static` называет скомпилированный файл, а рядом — два ваших стартовых файла, которых ни одна установка не трогает. `vibe.lock`, [лок-файл](../glossary/index.xml#lock-file) проекта, закрепляет за пакетом его версию и хэш.
При `spec_format = "xml"` раздел источника не должен повторять якорь контракта, а заголовок заметки не несёт якоря. Компилятор сливает разделы с общим якорем, и результат слияния сегодня не компилируется в `STATIC.xml`. Установка останавливается с `fact id … is defined twice`; копия пакета уже на диске, а лок-файл не записан. Два документа, чьи заголовки оба `{#root}`, сталкиваются так же. При `spec_format` по умолчанию тот же пакет компилируется.
Точка внутри якоря — путь, а не символ. К `{#verification.timeout}` нельзя обратиться, тогда как `#verification.timeout` доходит до раздела `timeout`, вложенного в раздел `verification`. Якорь — это буква, за которой идут буквы, цифры, `_` и `-`.
`vibe init package` пишет `link = "dynamic"`, какой бы `--link` вы ни передали. Задайте связь в манифесте, как делает шаг 2.
При `link = "dynamic"` скомпилированного файла нет. `INDEX.md` называет саму заметку, и агент, который её откроет, встретит строку `#use` и должен будет сам по ней пойти.
`vibe explain` отвечает только за пакет, который несёт [карту прослеживаемости](../glossary/index.xml#traceability-map) (*traceability map*). Про этот он так и говорит и останавливается.
`vibe facts check` ловит опечатку в состоянии в форме элемента, `state="finished"`, и называет значение. В короткой форме `@status:spec/finished` вовсе не читается как маркер, и файл проходит как чистый. Состояния — `plan`, `work`, `done`, `hold` и `void`; стадии — `idea`, `spec`, `impl`, `test`, `doc`, `freeze` и `unknown`.