vibe-runbooks

Runbook для установки среды курса «Вайбкодинг» на чистом MacBook (Apple Silicon или Intel). Это набор пошаговых инструкций (runbook.md) и готовых скриптов-«волшебных кнопок» (*.sh), по которым агент Codex проводит абсолютного новичка от пустого Mac до рабочей среды и первой видимой победы — запущенного приложения и первого коммита в GitHub.

Границы репозитория: здесь лежит только подготовка среды (Фаза 0). Самих уроков курса здесь нет — Фаза 1 и дальше живут в онлайн-школе (LMS): https://academy.adarasoft.com/course/vibecoding. После успешного чек-поинта (фаза 7) гид передаёт новичка туда — см. «Контракт завершения» в FOR-CODEX.md.

Быстрый старт (для новичка)

Заранее нужно только одно: установленный Codex (аккаунт ChatGPT + подписка Plus + приложение Codex). Дальше всё делает раннбук — он сам станет твоим гидом.

1. Открой Codex.
2. Вставь ему одно сообщение и отправь:

   Склонируй репозиторий https://github.com/bronxtc52/vibe-runbooks, зайди в его папку, прочитай файл AGENTS.md и делай ровно то, что там написано — веди меня как гид с самого начала.

3. Дальше просто следуй за Codex: он проведёт тебя по всем шагам от настройки Mac до первого запущенного приложения. Заранее ничего знать не нужно.

Codex сам подхватит инструкцию проекта из AGENTS.md — тебе не надо ничего настраивать или писать вручную.

Для кого это

• Новичок — взрослый человек, никогда не писавший код. Он не читает эти файлы напрямую: с ним работает Codex, проговаривая всё простым языком.
• Codex — агент в Терминале. Его инструкция — FOR-CODEX.md. Он идёт по INDEX.md, запускает скрипты, останавливается перед паролями/входами, ведёт прогресс.
• Ты (владелец курса) — забираешь эту папку и отдаёшь её Codex.

Что делается

Сначала настройка самого MacBook (Finder, режим сна, клавиатура, безопасность, Dock — материал «настройка MacBook»), затем установка стека курса (взят из реальных уроков Фазы 0): Homebrew · tree · Git · GitHub CLI (gh) · Node/npm · Claude Code · Codex · затем по выбору: мобильный трек (Flutter · Xcode · Android Studio · CocoaPods · iOS Simulator → приложение на симуляторе + коммит/push) и/или веб-трек (Netlify CLI → сайт по живой ссылке + коммит/push).

Дополнительные инструменты Фазы 2 курса (в LMS) — Python/venv, Railway — в 99-appendix-backend/, по требованию, не в первом маршруте.

Как этим пользуется Codex

1. Читает FOR-CODEX.md.
2. Запускает 00-preflight/check-system.sh — осмотр машины.
3. Идёт по INDEX.md фаза за фазой: runbook.md → скрипты → verify.sh.
4. Ведёт прогресс в state/progress.json. Ошибки — по TROUBLESHOOTING.md.
5. Финал — 07-checkpoint/self-check.sh (порог по выбранным трекам: 5/6, 8/10 или 11/14).
6. После успешного чек-поинта — передача в LMS: runbook завершён, дальше урок 1.1 курса на https://academy.adarasoft.com/course/vibecoding (в проекте ~/vibecoding/vibecoding_first_app, если проходил мобильный трек).

После фазы 4 — развилка треков по желанию: мобильный (5→6: Flutter/Xcode, счётчик на симуляторе) и/или веб (5w→6w: Netlify, сайт по живой ссылке). Гид предлагает, человек выбирает; отказ от Flutter — 05-flutter/skip.sh. Чек-поинт сам собирает чек-лист по трекам.

Структура

vibe-runbooks/
  README.md · FOR-CODEX.md · RITUALS.md · INDEX.md · TROUBLESHOOTING.md
  AGENTS.md                       # авто-инструкция агента — точка входа (Codex читает её первой)
  CLAUDE.md                       # то же для Claude Code (отсылает к AGENTS.md)
  scripts/lib.sh                  # общие функции (лог, проверки, идемпотентность, детект чипа)
  scripts/command-guard.py        # сторож команд: блок опасных команд агента (hook Claude Code)
  03-git-github/setup-secret-guard.sh  # сторож секретов (gitleaks + глобальный pre-commit)
  03-git-github/setup-command-guard.sh # установка сторожа команд (+самотест)
  state/progress-template.json    # шаблон прогресса (Codex копирует в progress.json)
  00-preflight/                   # осмотр машины (read-only)
  01-macbook-setup/               # настройка Mac: Finder, сон, клавиатура, безопасность, Dock
  02-foundation/                  # Homebrew + tree
  03-git-github/                  # Git + GitHub
  04-ai-helpers/                  # Node + Claude Code + Codex
  05-flutter/                     # мобильный трек: Flutter + Xcode + Android Studio + CocoaPods
  06-first-win/                   # мобильная победа: приложение на симуляторе + первый коммит
  05w-netlify/                    # веб-трек: Netlify CLI + вход (издательство сайтов)
  06w-first-site/                 # веб-победа: сайт по живой ссылке + AGENTS.md в проекте
  templates/project-AGENTS.md     # правила ИИ-агента для проектов новичка (commit→push→deploy)
  07-checkpoint/                  # самопроверка Фазы 0
  99-appendix-backend/            # Python/venv + Railway (по требованию)
  tests/                          # bats-тесты скриптов и сторожей
  .github/workflows/              # CI: shellcheck + bash -n + bats

Принципы скриптов

• set -euo pipefail; идемпотентность (повторный запуск безопасен, без дублей в ~/.zprofile);
• детект чипа (uname -m) → правильный префикс Homebrew (/opt/homebrew vs /usr/local);
• никаких rm -rf, скрытого sudo, хардкод-секретов;
• перед паролем / GUI / входом в аккаунт скрипт останавливается и предупреждает;
• после установки — реальная проверка (--version, тестовый запуск), а не предположение;
• весь вывод — по-русски, на «ты», без жаргона.

Запуск (вручную, для проверки)

Все команды — из этой папки. Полная шпаргалка в INDEX.md:

bash 00-preflight/check-system.sh
bash 02-foundation/install-homebrew.sh
# … далее по INDEX.md …

Источник истины

Стек и порядок шагов взяты из уроков курса «Вайбкодинг» в LMS (Фаза 0, уроки 0.1–0.8; аппендикс — уроки 2.2 и 2.7). Сами уроки в этом репозитории не хранятся — они доступны на https://academy.adarasoft.com/course/vibecoding. Команды — дословно из уроков, со ссылками на официальные источники внутри самих уроков.