От папки в Obsidian до большого проекта

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

03Образец — тот самый волт, на котором проверяли эту страницу: восемь заметок и папка настроек, которую Obsidian держит для себя.

my-vault/
  .obsidian/
  Daily/2026-09-20.md
  Inbox.md
  Projects/calculator/decisions.md
  Projects/calculator/spec.md
  Prompts/release-checklist.md
  Skills/code-review.md
  Skills/commit-messages.md
  Skills/writing-style.md

Папка, которая есть почти у всех

05Волт растёт, как ящик письменного стола. Правила для сообщений коммитов лежат рядом со спецификацией калькулятора, чек-листом релиза и прошлым вторником. Строчка в CLAUDE.md велит агенту читать правила, и для одного проекта этого хватает.

06Беда начинается со вторым проектом. Правила пригодились бы и там, и вы их копируете. Через неделю вы улучшаете одну копию, а другая остаётся прежней. Коллега просит ваш чек-лист ревью и получает файл в чате, и третья копия начинает собственную жизнь. Ничто в папке не говорит, какие заметки — правила для агента, а какие — просто заметки, и никакой другой проект не может от них зависеть.

Шаг 1: сделать папку проектом

07Проект VibeVM — это папка с манифестом vibe.toml и собственным деревом в vibevm/. Когда волт становится проектом, эти файлы добавляются, и ничего не сдвигается: заметки и .obsidian/ остаются ровно там, где были. Дайте агенту такую просьбу:

Сделай волт Obsidian в ./my-vault проектом VibeVM, не трогая мои заметки и папку .obsidian: запусти в нём vibe init, затем vibe check и перечисли все созданные файлы.

09Или руками:

101. Откройте терминал в волте и запустите vibe init. Проект получает имя папки:

Initializing project `my-vault` in `.`
  ✓ 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 `my-vault`: 10 files created, 0 kept.

122. Запустите vibe check. Он ответит, что все проверки пройдены.

13CLAUDE.md, AGENTS.md и GEMINI.md агенты-кодеры читают первыми. Теперь каждый из них кончается коротким блоком, который отправляет агента к стартовой полосе (boot lane) — списку чтения на начало сессии.

Шаг 2: переложить заметки в vibevm/vibespecs

14vibevm/vibespecs/ — дерево текста, который вы пишете сами, и установка пакета его никогда не правит. Заметки, переложенные туда, становятся собственным текстом проекта. Obsidian не против. Ссылка вида [[spec]] находит заметку по имени, где бы та ни лежала, лишь бы имя было единственным.

В проекте VibeVM ./my-vault перенеси Projects/calculator/*.md в vibevm/vibespecs/modules/calculator/, а Inbox.md, Daily/ и Prompts/ — в vibevm/vibespecs/notes/. Затем назови обе папки в vibevm/vibespecs/boot/90-user.md, чтобы сессия их читала. Запусти vibe check.

17Руками:

181. Переложите заметки. Эти команды работают на macOS, в Linux и в Git Bash на Windows:

mkdir -p vibevm/vibespecs/modules/calculator vibevm/vibespecs/notes
mv Projects/calculator/*.md vibevm/vibespecs/modules/calculator/
mv Inbox.md Daily Prompts vibevm/vibespecs/notes/

202. Скажите агенту, где теперь заметки. Откройте vibevm/vibespecs/boot/90-user.md — единственный файл стартовой полосы, который принадлежит вам, — и допишите в конец раздел:

## Где лежат заметки

- `vibevm/vibespecs/modules/calculator/`: что должен делать калькулятор
  и почему он устроен так. Читай это, прежде чем в нём что-то менять.
- `vibevm/vibespecs/notes/`: входящие, дневник и чек-лист релиза.
  Файл отсюда читай, только если задача его называет.

223. Запустите vibe check. Он проходит.

23Второй пункт обычно пропускают. Заметка в vibevm/vibespecs/ — собственный текст проекта. Но стартовая полоса называет только свои файлы, поэтому ни одна сессия не прочитает заметку, пока на неё что-нибудь не укажет. Этот указатель — 90-user.md, и ни одна установка его не переписывает. Папку notes/ объявлять не нужно: vibe принимает любую папку внутри vibevm/vibespecs/.

Шаг 3: вынести общую часть в пакет

24Правила из Skills/ — та часть, которая нужна другим проектам. VibeVM делится текстом через пакет: папку с манифестом, версией и файлами, которые пакет приносит. Этот пакет остаётся внутри волта, в vibevm/vibepacks/, — папке пакетов, которые проект пишет сам. vibe читает эту папку как реестр проекта, поэтому волт ставит собственные пакеты вообще без публикации.

25Вид (kind) пакета — flow: способ работать, например правила коммитов и порядок ревью. Флоу агент читает в начале каждой сессии.

В ./my-vault создай пакет-флоу org.acme/my-skills в дереве проекта командой vibe init package --kind flow, перенеси Skills/*.md в его vibevm/vibespecs/flows/my-skills/, дай каждой заметке якорь {#root}, перепиши его стартовый фрагмент так, чтобы он называл три заметки адресами spec://, и установи пакет в хранилище.

27Руками:

281. Создайте пакет. Вид укажите сразу: по нему команда называет файлы пакета.

vibe init package org.acme/my-skills --kind flow

30Команда создаёт папку пакета для версии 0.1.0, vibevm/vibepacks/org.acme/my-skills/v0.1.0/, и три файла в ней: манифест vibe.toml, README.md и vibevm/vibespecs/boot/10-flow-my-skills.md.

312. Перенесите правила в пакет:

P=vibevm/vibepacks/org.acme/my-skills/v0.1.0
mkdir -p $P/vibevm/vibespecs/flows/my-skills
mv Skills/*.md $P/vibevm/vibespecs/flows/my-skills/

333. Дайте каждому файлу правил якорь (anchor) на первом заголовке: # Code review {#root}. Замените ссылки Obsidian между тремя файлами адресами: [[code-review]] превращается в spec://org.acme/my-skills/flows/my-skills/code-review#root. Адрес работает в любом проекте, который поставил пакет, а имя заметки — только внутри хранилища.

344. Замените текст $P/vibevm/vibespecs/boot/10-flow-my-skills.md — стартового фрагмента (boot snippet) пакета. Его читает каждая сессия каждого проекта, который поставил пакет:

<!-- vibe:static org.acme/my-skills — boot snippet -->

# my-skills

Рабочие правила этого волта. Прочитай все три документа до первой
правки в сессии и следуй им, а не своим привычкам.

- Сообщения коммитов —
  `spec://org.acme/my-skills/flows/my-skills/commit-messages#root`:
  Conventional Commits, повелительное наклонение, одно изменение на коммит.
- Ревью —
  `spec://org.acme/my-skills/flows/my-skills/code-review#root`:
  сначала описание, тесты раньше реализации, блокирующее замечание
  помечено как блокирующее.
- Стиль текста —
  `spec://org.acme/my-skills/flows/my-skills/writing-style#root`:
  короткие предложения, без воды, действительный залог.

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

365. В $P/vibe.toml заполните description одной строкой, понятной постороннему: description = "The working rules of my vault: commit messages, code review, writing style".

376. Установите пакет в сам волт:

vibe install org.acme/my-skills --assume-yes

39vibe скопировал пакет в vibevm/vibedeps/org.acme.my-skills/0.1.0/ — дерево копий, которые приходят с пакетами, — и записал версию в лок-файл. Список чтения стартовой полосы, vibevm/vibespecs/boot/INDEX.md, теперь называет фрагмент пакета между двумя собственными файлами проекта:

[[entry]]
path = "vibevm/vibespecs/boot/00-core.md"
kind = "static"

[[entry]]
path = "vibevm/vibedeps/org.acme.my-skills/0.1.0/vibevm/vibespecs/boot/10-flow-my-skills.md"
kind = "static"

[[entry]]
path = "vibevm/vibespecs/boot/90-user.md"
kind = "static"

41Теперь волт и автор пакета, и его первый пользователь. Когда потом поменяете правило, снова запустите в волте vibe install --assume-yes. vibe заметит, что пакет приходит из папки, которая может меняться, прочитает её заново и скопирует новый текст:

  → re-resolving — `org.acme/my-skills` resolves from an in-workspace file:// source (a mutable working tree); re-resolving to pick up any source edit (PROP-011 §2.6)

[[skill]]
name = "vault-rules"
path = "vibevm/vibespecs/skills/vault-rules"
description = "Apply this vault's working rules to a commit, a review or a draft"

  → vault-rules [flow:my-skills] → agents: all — Apply this vault's working rules to a commit, a review or a draft
1 skill(s) declared.

Шаг 4: пакет в других проектах

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

Сделай пакеты из ~/my-vault доступными всем проектам на этом компьютере: добавь его папку vibevm/vibepacks первым [[registry]] с именем my-vault в ~/.vibe/registry.toml, затем установи org.acme/my-skills в проект ~/code/other-project.

50Руками, на одну установку, запустите в другом проекте:

vibe install --registry ~/my-vault/vibevm/vibepacks org.acme/my-skills --assume-yes

52--registry принимает путь к папке и больше ничего не читает, поэтому установка обходится без сети. В проверочном прогоне она заняла десятую долю секунды.

53Руками, насовсем:

541. Откройте ~/.vibe/registry.toml — список реестров, который vibe ведёт для всей машины, — и поставьте папку волта первой:

[[registry]]
name = "my-vault"
url = "file:///home/me/my-vault/vibevm/vibepacks"

562. На Windows оставьте букву диска и пишите прямые слеши: file:///C:/Users/me/my-vault/vibevm/vibepacks.

573. Записи ниже не трогайте. Два центральных реестра vibe записал туда при первом запуске.

584. В любом проекте на этом компьютере запустите vibe install org.acme/my-skills --assume-yes.

59Порядок важен: vibe опрашивает реестры в том порядке, в каком они перечислены в файле. Когда волт стоял первым, свежий проект поставил пакет за 1,4 секунды. Когда последним, vibe сначала спросил оба центральных реестра, и та же установка заняла 5,9 секунды.

62Когда правило в волте меняется, запустите в другом проекте vibe update org.acme/my-skills --assume-yes. Он заново прочитает пакет, скопирует новый текст и запишет в лок-файл его новый отпечаток (fingerprint).

Шаг 5: на другой компьютер

63Дорога на второй компьютер та же, по которой уже ходит ваш код: закрытый Git-репозиторий. Волт уходит туда целиком, вместе с пакетами, а второй компьютер работает со своим клоном так же, как шаг 4 работал с папкой.

Подготовь ./my-vault к переносу на мой второй компьютер: добавь .gitattributes, который держит у текстовых файлов окончания строк LF, добавь .obsidian/workspace.json в игнор, затем сделай его git-репозиторием на ветке main и закоммить всё, включая vibevm/vibedeps и vibevm/vibepacks. Не пушь.

65Руками:

661. В корне волта создайте .gitattributes с одной строкой:

* text=auto eol=lf

682. Добавьте .obsidian/workspace.json в .gitignore. Obsidian переписывает этот файл всякий раз, когда вы двигаете панель.

693. Сделайте волт репозиторием, закоммитьте всё и отправьте в закрытый репозиторий:

git init -b main
git add -A
git commit -m "chore: make the vault a VibeVM project"
git remote add origin git@github.com:<you>/my-vault.git
git push -u origin main

714. На втором компьютере склонируйте репозиторий и добавьте папку клона vibevm/vibepacks в ~/.vibe/registry.toml этого компьютера, как в шаге 4.

72Первый пункт этого списка спасает от сюрприза, который встретил проверочный прогон. Git для Windows при выгрузке файла меняет окончания строк, а с ними и байты файла. vibe проверяет пакет по отпечатку его байтов, поэтому у того же пакета в клоне оказался другой отпечаток. Один файл правил весил 727 байт там, где его написали, и 744 на втором компьютере. С .gitattributes оба компьютера видят одни и те же байты и записывают один и тот же отпечаток.

73vibevm/vibedeps/ тоже коммитьте. Копии, которые принесли пакеты, коммитят нарочно: агент, склонировавший репозиторий, может прочитать всё, ничего не запуская. .vibe/, где vibe держит состояние этого компьютера, vibe init уже добавил в игнор Git.

Шаг 6: коллегам, в одном репозитории

74Коллегам не нужен отдельный репозиторий на каждый пакет. Дайте им доступ к репозиторию волта: каждый клонирует его и направляет свою машину на свой клон, как вы сделали на втором компьютере. Пакеты остаются там, где вы их пишете, рядом с заметками, которые их объясняют.

Я склонировал волт нашей команды в ./team-vault. Добавь его папку vibevm/vibepacks первым [[registry]] с именем team-vault в мой ~/.vibe/registry.toml, затем установи org.acme/my-skills в мой проект ./team-notes и покажи его стартовую полосу.

76Когда правило меняется, вы коммитите и пушите. Коллега делает git pull в своём клоне, а затем vibe update org.acme/my-skills --assume-yes в каждом проекте, где стоит пакет.

77Так репозиторий VibeVM хранит собственные пакеты. Redbook и его соседи живут в его же vibevm/vibepacks/, тридцать пакетов в одной только группе. Проекты, вложенные в репозиторий, ставят их оттуда одной командой, а --offline не даёт vibe ни о чём спрашивать центральные реестры:

vibe install --offline --registry <repository>/vibevm/vibepacks <group>/<name> --assume-yes

Шаг 7: свой реестр или центральный

79Клон перестаёт подходить, когда тем, кому нужен пакет, не стоит видеть весь волт или когда вы знаете уже не всех, кому он нужен. Тогда пакет публикуют. Собственный реестр — организация на GitHub или другом Git-хостинге, где у каждого пакета свой репозиторий и где вы решаете, кто его читает. Как это сделать, показывает страница Опубликовать пакет, в том числе vibe workspace publish, который публикует все пакеты репозитория за один прогон. Чтобы предложить пакет всем, попросите место в центральном реестре, как показывает страница Опубликовать пакет в центральном реестре.

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

80Волт в конце проверочного прогона, без служебного состояния Git и vibe:

my-vault/
  .gitattributes  .gitignore  .obsidian/
  AGENTS.md  CLAUDE.md  GEMINI.md  vibe.toml  vibe.lock
  vibevm/
    vibespecs/
      boot/00-core.md  boot/90-user.md  boot/INDEX.md
      modules/calculator/decisions.md  modules/calculator/spec.md
      notes/Inbox.md  notes/Daily/  notes/Prompts/
    vibepacks/org.acme/my-skills/v0.1.0/
      vibe.toml  README.md
      vibevm/vibespecs/boot/10-flow-my-skills.md
      vibevm/vibespecs/flows/my-skills/  (три правила)
      vibevm/vibespecs/skills/vault-rules/SKILL.md
    vibedeps/org.acme.my-skills/0.1.0/  (установленная копия)

82Внутри vibevm/ три дерева. vibespecs/ — текст, который вы пишете для этого проекта. vibepacks/ — пакеты, которые вы пишете для других, и этот проект тоже в их числе. vibedeps/ — копии, которые принесли пакеты; их пишет vibe, а вы никогда не правите.

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

83--registry принимает путь к папке, а url в registry.toml — адрес file:///. Каждый отвергает форму другого, причём с ошибкой операционной системы, а не с понятной фразой.

84vibe registry add принимает только Git-хостинг, поэтому папку вписывают в registry.toml руками.

85vibe registry list показывает только собственный список проекта. Запись в ~/.vibe/registry.toml работает, но там не появляется.

86Создавайте проект волта вне других проектов. vibe init внутри чужого проекта молча вкладывает второй проект в первый.

87vibe skill install --scope user пишет в папки агентов в вашем домашнем каталоге, сразу для всех проектов. Эта страница пользуется --scope project, который пишет только в волт.