Создать первый проект

Что понадобится

03Выберите для проекта короткий путь. Windows отказывается работать с путями длиннее 260 символов, а самый глубокий установленный файл лежит примерно на 140 символов ниже папки проекта. Держите путь к самому проекту короче 120 символов: C:\dev\hello-vibevm подойдёт, а папка на восьмом уровне вложенности может и не подойти.

04Первой установке нужна сеть. После неё каждый установленный пакет остаётся в машинном хранилище (store), и второй проект берёт его оттуда.

Шаг 1: создать проект

Создай проект VibeVM с именем hello-vibevm в текущей папке, пропиши в его манифесте spec_format = "xml", сделай его git-репозиторием с веткой main, установи в него org.vibevm.world/redbook из реестра по умолчанию, закоммить результат и покажи дерево того, что агент читает в начале сессии.

06Проект в VibeVM означает папку с манифестом внутри, и всё, что делает vibe, он делает с проектом. Отдайте запрос выше агенту или пройдите шаги сами; обе дороги приводят к одной и той же папке.

071. Создайте проект. Имя станет именем папки:

vibe init hello-vibevm

Initializing project `hello-vibevm` in `hello-vibevm`
  ✓ created  vibevm/vibespecs/boot/00-core.md
  ✓ created  vibevm/vibespecs/boot/90-user.md
  ✓ created  vibe.toml
  ✓ created  vibe.lock
  ✓ created  .vibe/.gitignore
  ✓ created  .gitignore
  ✓ created  vibevm/vibespecs/boot/INDEX.md
  ✓ created  CLAUDE.md
  ✓ created  AGENTS.md
  ✓ created  GEMINI.md

Done. Project `hello-vibevm`: 10 files created, 0 kept.

Next:
  • edit vibevm/vibespecs/boot/00-core.md and vibevm/vibespecs/common as your project takes shape
  • install packages with `vibe install <kind>:<name>` (e.g. flow:wal)

092. Откройте hello-vibevm/vibe.toml, манифест проекта. Добавьте в раздел [project] одну строку:

[project]
spec_format = "xml"
name = "hello-vibevm"

113. Сделайте папку git-репозиторием с веткой main:

git init -b main hello-vibevm

13Строка из пункта 2 решает, в каком виде установленные правила лягут на диск. Автор пакета может писать на XML или на Markdown. С spec_format = "xml" vibe переводит каждый Markdown-документ пакета в XML, пока копирует пакет. Установленный текст получается одного вида. Файлы, которые вы пишете сами, никогда не переводятся: на этой странице они остаются в Markdown.

Шаг 2: установить redbook

16redbook — сборник рабочих практик для команды из людей и агентов, взятых из книги об AI-native разработке. Каждая практика оформлена отдельным пакетом со своими правилами. Над одной задачей работают два процесса, человеческий и агентский. Их единственная общая память лежит в файлах. Каждое решение записывается вместе с причиной, и каждый коммит несёт одну мысль. redbook называет 21 практику, две из них приводят ещё 5, и одна установка даёт проекту 27 пакетов.

171. Установите его. vibe находит пакет в реестре по умолчанию, скачивает 27 пакетов и копирует их в проект; на это уходит около минуты. Уберите --assume-yes, если хотите сначала увидеть план и ответить на вопрос самому. Ответ по умолчанию отрицательный:

vibe install org.vibevm.world/redbook --path hello-vibevm --assume-yes --quiet

vibe install: 27 packages materialised

192. Проверьте проект:

vibe check --path hello-vibevm

vibe check: clean — every check passed against `<TMP>/work/hello-vibevm`

213. Закоммитьте всё, включая установленные пакеты. Папка vibevm/vibedeps/ хранит копию пакетов, которую ведёт vibe, и её коммитят, чтобы свежий клон проекта читался ещё до того, как кто-то запустит vibe:

git -C hello-vibevm add -A
git -C hello-vibevm commit -m "chore: create the project and install the redbook"

Шаг 3: посмотреть, что пришло

24Запустите vibe tree в папке проекта. В терминале он открывает интерактивное дерево из 27 пакетов: стрелки перемещают по нему, Space сворачивает ветку, Enter открывает карточку пакета, Esc выходит. В скрипте или с --plain то же дерево печатается текстом:

vibe tree --plain --path hello-vibevm

project: <TMP>/work/hello-vibevm
STATIC.xml: 37217 bytes, 300 lines, 4 contribution(s)
packages: 27   roots: 1
columns: load  T=transitive  C=condition  S=in STATIC.xml

org.vibevm.world/redbook                                        dynamic  .  .  .
├─ org.vibevm.world/addressable-specs [public-chain]            dynamic  .  .  .
├─ org.vibevm.world/campaign-plans [public-chain]               dynamic  .  .  .
├─ org.vibevm.world/comparative-research [public-chain]         dynamic  .  .  .
├─ org.vibevm.world/conflict-protocol [public-chain]            dynamic  .  .  .
├─ org.vibevm.world/decision-records [public-chain]             dynamic  .  .  .
├─ org.vibevm.world/dev-runtime-docs [public-chain]             dynamic  .  .  .
├─ org.vibevm.world/discovery-prompt [public-chain]             dynamic  .  .  .
├─ org.vibevm.world/git-practices [public-chain]                dynamic  .  .  .
│  ├─ org.vibevm.world/git-atomic-commits [public-chain]        static   .  .  x
│  ├─ org.vibevm.world/git-attribution-policy [public-chain]    static   .  .  x
│  ├─ org.vibevm.world/git-autonomy [public-chain]              static   .  .  x
│  └─ org.vibevm.world/git-conventional-commits [public-chain]  static   .  .  x
├─ org.vibevm.world/health-audit [public-chain]                 dynamic  .  .  .
├─ org.vibevm.world/licensing [public-chain]                    dynamic  .  .  .
├─ org.vibevm.world/managed-blocks [public-chain]               dynamic  .  .  .
├─ org.vibevm.world/manual-tests [public-chain]                 dynamic  .  .  .
├─ org.vibevm.world/operating-modes [public-chain]              dynamic  .  .  .
├─ org.vibevm.world/qualified-naming [public-chain]             dynamic  .  .  .
├─ org.vibevm.world/secrets-hygiene [public-chain]              dynamic  .  .  .
├─ org.vibevm.world/source-mirrors [public-chain]               dynamic  .  .  .
├─ org.vibevm.world/spec-genres [public-chain]                  dynamic  .  .  .
├─ org.vibevm.world/sync-from-code [public-chain]               dynamic  .  .  .
├─ org.vibevm.world/tool-design-lessons [public-chain]          dynamic  .  .  .
├─ org.vibevm.world/two-process-model [public-chain]            dynamic  .  .  .
└─ org.vibevm.world/wal-specspaces [public-chain]               dynamic  .  .  .
   └─ org.vibevm.world/wal [public-chain]                       dynamic  .  .  .

26Каждая строка описывает один пакет и говорит, как его правила попадают к агенту. Четыре git-практики помечены static: агент читает их первыми и целиком в начале каждой сессии, потому что они управляют каждым коммитом. Остальные помечены dynamic: агент читает их следом, по файлу на пакет, в заданном порядке. Этот список чтения и называется стартовой полосой (boot lane). В этом проекте в ней около 30 файлов и 190 килобайт, и агент прочитает их все, прежде чем скажет первое слово.

28Теперь откройте папку и посмотрите на то же самое в виде файлов:

291. Откройте hello-vibevm/vibevm/vibedeps/. Там 27 папок, по одной на пакет, и каждая названа группой, именем и версией пакета: org.vibevm.world.two-process-model/1.0.0/. Внутри лежит пакет в том виде, в каком его опубликовал автор, и каждый документ в нём записан на XML.

302. Откройте в той же папке .vibe-slot.toml. Это запись vibe об этой копии. В ней названы формат и рецепт конвертера и лежат два хеша: того, что опубликовал автор, и того, что легло сюда. Дальше перечислен каждый файл со своим хешем и одним словом, copied или converted. Например, README.md пакета приходит как README.xml.

313. Откройте hello-vibevm/vibevm/vibespecs/boot/. STATIC.xml собирает четыре git-практики в один файл, а INDEX.md перечисляет остальную полосу по порядку. Оба файла сгенерированы. Два других файла там, 00-core.md и 90-user.md, ваши: их правите вы, и никакая установка их не трогает.

344. Откройте hello-vibevm/CLAUDE.md. Его последние строки занимает блок, который написал vibe: он отправляет агента к двум сгенерированным файлам. AGENTS.md и GEMINI.md заканчиваются тем же блоком, потому что разные агенты ищут файлы с разными именами.

Шаг 4: открыть агента в проекте

36Запускайте агента внутри папки проекта, а не выше: агент читает файл инструкций той папки, в которой его запустили.

38Прежде чем просить о работе, задайте агенту один вопрос: «Каким правилам следует этот проект? Назови практики и где ты их прочитал». Первый ответ займёт несколько минут, потому что агент прочитывает всю полосу, прежде чем что-то сказать. Он должен перечислить практики redbook, отличить четыре статических git-правила от остальных и сказать, где прочитал каждое. Хороший ответ добавит, что эти правила важнее его собственных привычек: например, в его коммитах не будет строки, которая приписывает авторство агенту.

39Если он не называет ни одной практики, значит, его запустили не в той папке. Закройте его, выполните cd hello-vibevm и запустите снова.

40Агент может заметить и то, что некоторые практики рассчитаны на проект побольше калькулятора. Он прав: одна ждёт инструмент, который сам себя обновляет, другая ждёт историю, которая хранится на нескольких git-хостингах. У сборника есть свои взгляды. Практику, которая не подходит, можно убрать: Удалить пакет.

Шаг 5: написать спецификацию

41В подходе redbook программа начинается со спецификации: текста о том, что программа должна делать, написанного до кода. Спецификация служит каналом между вами и агентом. Вы решаете, чем будет калькулятор; агент читает это решение в файле, а не в чате, который кончится вместе с сессией.

42Правила делят такие тексты на два вида. PROP — это контракт: постоянные правила одной части программы, которые меняются редко и никогда не удаляются. FEAT описывает один срез работы под этим контрактом: его границы и проверки, которые говорят, что срез готов. Каждое правило стоит под заголовком с якорем вроде {#division-by-zero}, чтобы тест, коммит или сообщение могли указать ровно на одно правило.

43К одним и тем же двум файлам ведут две дороги. Напишите их сами или попросите агента и ответьте на его вопросы.

Написать самому

441. Создайте папку hello-vibevm/vibevm/vibespecs/modules/calculator/.

452. Создайте в ней PROP-001.md, контракт:

# PROP-001: Калькулятор {#root}

Hello VibeVM — калькулятор для командной строки. Этот документ задаёт его
контракт: что программа принимает, что печатает и как сообщает об ошибке.

## Ввод {#input}

Программа принимает один аргумент, выражение в кавычках: два числа и один
оператор через пробелы, например `hello-vibevm "2 + 3"`.

## Числа {#numbers}

Число записывается десятичной дробью с необязательным знаком и дробной
частью: `-4`, `2.5`.

## Операторы {#operators}

Операторов четыре: `+`, `-`, `*` и `/`, и никаких других.

## Результат {#result}

Программа печатает результат одной строкой в стандартный вывод и выходит
с кодом 0. Целый результат печатается без дробной части: `"2 + 3"` даёт
`5`, а `"7 / 2"` даёт `3.5`.

## Деление на ноль {#division-by-zero}

Деление на ноль считается ошибкой. Программа печатает
`error: division by zero` в поток ошибок и выходит с кодом 1.

## Неверный ввод {#bad-input}

Любой другой ввод тоже ошибка: нет аргумента, слово вместо числа или
оператор не из списка выше. Программа называет проблему в потоке ошибок
и выходит с кодом 2.

## Решение: один аргумент в кавычках {#decision-one-argument}

- Решение: выражение приходит одним аргументом в кавычках.
- Почему: без кавычек оболочка читает `*` как шаблон имён файлов, а Git Bash
  в Windows превращает одинокий `/` в путь.
- Пересмотреть, когда: у калькулятора появится интерактивный режим.

## Решение: Rust {#decision-rust}

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

473. Рядом создайте FEAT-001.md, первый срез:

# FEAT-001: Четыре действия {#root}

Первый срез Hello VibeVM: четыре действия над двумя числами и две ошибки,
как их задаёт [PROP-001](PROP-001.md).

## Границы {#scope}

Всё, что задаёт PROP-001, и ничего больше: ни длинных выражений, ни
истории, ни интерактивного режима.

## Приёмка {#acceptance}

| Команда                    | Стандартный вывод | Поток ошибок                | Код выхода |
|----------------------------|-------------------|-----------------------------|------------|
| `hello-vibevm "2 + 3"`     | `5`               |                             | 0          |
| `hello-vibevm "10 - 4.5"`  | `5.5`             |                             | 0          |
| `hello-vibevm "6 * 7"`     | `42`              |                             | 0          |
| `hello-vibevm "7 / 2"`     | `3.5`             |                             | 0          |
| `hello-vibevm "-4 * 2.5"`  | `-10`             |                             | 0          |
| `hello-vibevm "1 / 0"`     |                   | `error: division by zero`   | 1          |
| `hello-vibevm "2 ^ 3"`     |                   | называет оператор `^`       | 2          |
| `hello-vibevm "2 +"`       |                   | называет недостающее число  | 2          |

494. Попросите агента прочитать оба файла и назвать, чего в них не хватает и что в них двусмысленно. Хорошее ревью находит настоящие пробелы: например, контракт ничего не говорит о результате, который слишком велик, чтобы его напечатать. Каждое замечание решите сами, а правки в файлах доверьте агенту.

505. Закоммитьте спецификацию:

git -C hello-vibevm add vibevm/vibespecs/modules
git -C hello-vibevm commit -m "docs(calculator): specify Hello VibeVM"

Попросить агента

Hello VibeVM — калькулятор командной строки на Rust: `hello-vibevm "7 / 2"` печатает `3.5`. Он принимает одно выражение в кавычках, два десятичных числа вокруг `+`, `-`, `*` или `/`; деление на ноль завершается с кодом 1. Опиши его на Markdown так, как требуют правила этого проекта: короткий контракт (PROP) и его первый срез (FEAT). Кода не пиши; перечисли файлы.

53Всю работу здесь делают слова «так, как требуют правила этого проекта». Агент читает правило redbook о видах документов, решает, что контракт станет PROP, а срез станет FEAT, и пишет оба файла в vibevm/vibespecs/modules/ с якорем на каждом правиле. Когда эту страницу проверяли, два агента от двух разных компаний, получив только этот запрос и установленные правила, положили одни и те же два файла в одно и то же место.

54Будьте готовы получить больше, чем просили. Всё, что запрос оставил открытым, агент закрывает осторожным значением по умолчанию, записывает решение вместе с причиной и помечает REVIEW для вас. В проверочном прогоне передовая модель провела на этом шаге около 25 минут, и большая часть написанного ею была как раз такими решениями. Так практики и задуманы: по правилу двух процессов смысл программы решаете вы.

55Поэтому отвечайте на пометки по одной. Прочитайте список, который даст агент, ответьте простыми словами на те вопросы, по которым у вас есть мнение (например: «результат хранит не больше десяти знаков после точки»), и скажите, что остальное остаётся как есть. Не одобряйте весь файл одной фразой: в проверочном прогоне одна такая фраза закрыла восемь решений, которых её автор так и не прочитал. Когда у каждой пометки будет ответ, попросите агента закоммитить спецификацию.

Что появилось на диске

56Откройте hello-vibevm/vibe.toml: он называет проект, закрепляет формат установленного текста и перечисляет org.vibevm.world/redbook среди требований с диапазоном версий. Откройте hello-vibevm/vibe.lock, лок-файл проекта: он закрепляет все 27 пакетов за точными версиями и отпечатками (fingerprint) содержимого. Остальное делится на два дерева. vibevm/vibedeps/ и сгенерированные стартовые файлы принадлежат vibe, и он переписывает их при каждой установке. vibevm/vibespecs/modules/ и два ваших стартовых файла принадлежат вам, и vibe в них никогда не пишет.

58Если спецификацию писал агент, он мог оставить и vibevm/vibespecs/WAL.xml: короткую запись о том, где стоит работа, которую следующая сессия прочитает первой. Этого требует одна из установленных практик.

59Спецификация стала первым в этом проекте, что принадлежит только вам. Чтобы превратить её в программу, пройдите продвинутый урок Собрать Hello VibeVM на AI-Native Rust: он ставит Rust, просит агента собрать калькулятор по этим двум файлам и добавляет дисциплину, которая держит код привязанным к ним.

Особые случаи и правила

60Повторный vibe install без имён пакетов ставит всё, что требует манифест; это команда после клонирования существующего проекта.

61Если в папке уже есть CLAUDE.md, vibe дописывает свой блок в конец и не трогает ваш текст. Если он находит два блока или сломанный, он останавливается с ошибкой и ничего не меняет, пока вы не почините файл.

63Отказаться от плана установки не ошибка: ничего не записывается, а хранилище сохраняет скачанное на следующий раз.

64Если агент начинает писать код раньше, чем спецификация устоялась, остановите его и спросите, какому правилу он следовал. Практики redbook ставят спецификацию первой; агент, который их пропустил, обычно запущен не в той папке.

65В Windows git add может печатать по предупреждению на каждый файл: LF будет заменён на CRLF. Его вызывает настройка Git core.autocrlf, и оно безвредно: в коммите у файлов остаются окончания LF.