writing-reels-from-repo

Writing Reels from a Repo (RU)

Обзор

Берёт реальную работу из репозитория — несколько связанных коммитов, инцидент, milestone — и превращает в скрипт 30–60 сек на русском языке для Reels / TikTok / Shorts. Главная цель — звучать как живой инженер, а не AI-копирайтер.

Два жёстких правила, которые отличают этот скилл от плохих рилс-генераторов:

1. Не одиночный коммит. Дефолт — арка из 5–20 коммитов. Один коммит = рилс только если это hotfix/milestone/war-story (см. Шаг 1).
2. Не AI-русский. Перед выдачей текст проходит фильтр запрещённых слов и speak-test. См. references/ban-list-ru.md и references/register-ru.md.

Когда использовать

Да: сценарий короткого видео про свой проект на русском (серия «день N», еженедельный дайджест, война с багом, milestone, архитектурное решение).

Нет: длинные YouTube-видео, лендинги, B2B-кейсы где автор не герой, рилсы не про код (тогда отдельные скиллы), английский контент.

Шаги (по порядку, не пропускать)

Шаг 0  →  Сбор коммитов и логов (git + CLAUDE.md + MEMORY.md)
Шаг 1  →  Кластеризация в АРКИ (5–20 коммитов на арку)
Шаг 2  →  Извлечение лексикона проекта (3+ уникальных терминов)
Шаг 3  →  Скоринг арок (6 осей × 0–2)
Шаг 4  →  Выдать 2–3 кандидата → выбрать арку
Шаг 4.5 → Deep source pass по выбранной арке (diff, файлы, числа, visual proof)
Шаг 5  →  Story atoms (5 буллетов) → подтвердить или продолжить в fast final
Шаг 5.5 → Audience + author voice
Шаг 6  →  Хук с обязательной ротацией формул
Шаг 7  →  Скрипт с тайм-кодами + speak-test
Шаг 7.5 → Trim pass (подрезка до бюджета слов −5%)
Шаг 8  →  Production pack: b-roll, on-screen text, caption, hashtags, обложка
Шаг 9  →  QC pass перед выдачей

Режим работы

Дефолт — guided mode: показать кандидатов, дождаться выбора, показать story atoms, дождаться подтверждения.

Если пользователь просит готовый результат без промежуточных согласований (сразу сделай, дай финальный сценарий, без вопросов) — включи fast final mode:

• сам выбери арку с максимальным score,
• продолжай без стопов,
• в финале явно напиши: Выбрал арку сам: <почему>,
• не выдумывай отсутствующие факты; спорные числа помечай <verify>.

Шаг 0 — Сбор материала

Запусти параллельно:

git log --since="3 weeks ago" --oneline
git log --since="3 weeks ago" --stat | head -200
git log --since="3 weeks ago" --pretty=format:"%h %s%n%b%n---"
git log --since="3 weeks ago" --name-only --pretty=format:"--- %h %ad %s" --date=short | head -300

Дополнительно прочитай (если есть):

• CLAUDE.md, README.md — что за проект, чьи боли
• MEMORY.md, project_*.md, feedback_*.md — инциденты, миграции, решения
• gh pr list --state merged --limit 30 и gh issue list --limit 30 — если просили

Шаг 1 — Кластеризация в арки (КРИТИЧНО)

Один коммит — почти всегда скучно. Делай арки.

Группируй коммиты в арки по:

• Теме — связаны общим словом в сообщении, файлах, директории.
• Времени — серия в 2–10 дней, типичная отладка / разработка фичи.
• Боли — все коммиты решают одну проблему пользователя.

Цель арки: 5–20 коммитов под одной болью. Это будущий сюжет.

Single-commit арка разрешена ТОЛЬКО если:

• hotfix с реальным downtime / data loss / silent break,
• milestone (первый платёж, первый юзер, N-й релиз, лонч),
• war story с очевидным твистом, прожитая в один день.

Иначе агрегируй. Если не получается набрать ≥3 коммитов на одну арку — спроси пользователя, не пора ли подождать неделю и накопить.

Шаг 2 — Лексикон проекта (новый шаг, обязательный)

Это лекарство от generic тона. Найди 3+ термина, существующих ТОЛЬКО в этом проекте:

• Внутренние имена сервисов / модулей (не auth-service, а реальное имя из репо).
• Кодовые слова в коммитах и комментариях (см. git log и grep -r "TODO\|FIXME\|HACK").
• Метрики, которые автор сам выдумал.
• Никнеймы багов (если есть).
• Странные числа из конфигов (порт, retry-count, timeout).

Эти термины должны буквально звучать в скрипте. Без них сценарий получится «универсальным» = скучным.

Если терминов <3 — спроси у пользователя кодовые слова, не выдумывай.

Шаг 3 — Скоринг (6 осей, 0–2 каждая)

Ось	0	1	2
Ставки	Косметика, dev-only	Затрагивает юзеров	Деньги / данные / SLA / репутация
Твист	Прямой фикс «как и думали»	Неочевидное решение	Смешно-тупое решение / парадокс
Универсальность	Только девы поймут	Кому-то за пределами IT понятно	Боль ясна любому
Доказуемость	Нечего показать	Diff / лог / число	Сильный визуал (графики, до/после, скрин чата)
Эмоция	Нейтрально	Удивление / лёгкое раздражение	Стыд / восторг / страх / боль
Веха	Просто работа	Косвенный итог недели	Круглое число / первый раз

Порог: сумма ≥ 7 — снимать, 5–6 — слабый, <5 — не снимать.

Шаг 4 — Кандидаты

Выдай 2–3 топ-арки в формате:

### Кандидат A: <название арки> · score 9/12
- Период: <с — по>
- Коммиты: <5–7 хешей или 1-line>
- Боль: <одна фраза разговорным языком>
- Виральный угол: <ось с максимумом>
- Лексикон проекта: <3+ терминов из Шага 2>
- Риск на камере: <что может не сработать>

В guided mode: стоп, ждать выбор пользователя. Не идти дальше без подтверждения.

В fast final mode: выбери арку сам. При равном score побеждает арка с лучшим визуальным доказательством, затем с более понятной болью.

Шаг 4.5 — Deep source pass по выбранной арке

После выбора арки обязательно проверь не только сообщения коммитов, но и реальные изменения:

git show --stat --patch <hash1> <hash2> ...
git log --name-status --pretty=format:"--- %h %ad %s" --date=short <range>

Извлеки:

• Files touched — 3–7 файлов/директорий, которые объясняют арку.
• Diff moments — 2–3 конкретных изменения, которые можно показать на экране.
• Source numbers — строки, проценты, миллисекунды, цена, количество ошибок, размеры diff. Только из источников.
• Visual proof — что зритель физически увидит: diff, лог, график, UI before/after, terminal output, issue, PR.

Если visual proof слабый — понизь score по Доказуемость. Если twist не подтверждается diff/log/issue — перепиши twist как гипотезу или спроси пользователя.

Шаг 5 — Story atoms (5 буллетов)

После выбора арки выпиши 5 атомов. Если хоть один не вытаскивается из источника — спроси, не выдумывай.

• Pain — что было сломано? Буквально, одной фразой.
• Escalation — почему стало хуже / почему долго не замечал.
• Twist — каким на самом деле оказался фикс. Чем глупее — тем лучше.
• Lesson — принцип, который переживает этот баг.
• Visual — один реальный кадр для b-roll (diff, дашборд, лог, скрин чата).

Покажи пользователю атомы. В guided mode: стоп, ждать подтверждение. В fast final mode: продолжай.

Шаг 5.5 — Audience + author voice

Перед хуком зафиксируй 4 настройки. Не превращай это в анкету: если пользователь не дал вводных, используй дефолты.

Настройка	Дефолт
Аудитория	русскоязычные разработчики + люди, которым интересен build in public
Обращение	ты
Голос автора	живой инженер, без маркетинга, без лекции
Мат / жёсткость	без мата, лёгкая самоирония разрешена

Если контекст канала известен из README/MEMORY/прошлых эпизодов — следуй ему. Если автор явно пишет грубее или мягче, копируй его регистр.

Шаг 6 — Хук (с ОБЯЗАТЕЛЬНОЙ ротацией)

1. Если история хуков уже есть в запросе или файлах проекта — используй её. Если истории нет, один раз спроси у пользователя формулы последних 5 эпизодов; в fast final mode не спрашивай, продолжай без ротации.
2. Выбери формулу из references/hook-bank-ru.md (20+ формул), которая не повторяет формулы последних 3 эпизодов.
3. Произнеси вслух — должен помещаться в ≤3 сек (~7 слов).
4. Дай альтернативу из другой формулы (backup-hook).

Если пользователь не дал историю — не блокируй сценарий. Отметь: Истории хуков нет, выбрал формулу без ротации. Попроси сохранить формулу в лог после финала.

Шаг 7 — Скрипт с тайм-кодами

Время	Блок	Задача
0:00–0:03	Хук	Pattern interrupt. Одно предложение из Шага 6.
0:03–0:12	Сетап	Кто я + что за арка человеческим языком. Можно дропнуть, если хук уже представил контекст.
0:12–0:30	Напряжение	Проблема растёт. Здесь — ставки для зрителя-не-айтишника.
0:30–0:45	Поворот	Фикс / разгадка. Одно число из источника; если числа нет — конкретный файл, строка, лог или before/after кадр.
0:45–0:55	Вывод	Принцип, который больше, чем баг. Одно предложение.
0:55–end	CTA + петля	Soft follow + последний кадр рифмуется с хуком.

Бюджет слов (русская речь на камеру, ~150 wpm):

• 30 сек ≈ 75 слов
• 45 сек ≈ 110 слов
• 60 сек ≈ 150 слов

Шаг 7.5 — Trim pass (отдельный, обязательный)

После написания скрипта — отдельным проходом подрежь его до бюджета минус 5%. Это компенсирует естественное замедление на камере.

Алгоритм:

1. Посчитай слова в voiceover по блокам и суммой.
2. Цель: ≤95% от бюджета (45 сек → ≤104 слова, 30 сек → ≤71, 60 сек → ≤142).
3. Если перебор — режь:
   • Hedging-слова (см. ban-list разделы 1 и 6): убираются первыми.
   • Длинные причастия: «обработавший» → «который обработал» → «обработал».
   • Дубли смысла («полностью убрал», «совсем закрыл»): убрать наречие.
4. Дай финальный подсчёт пользователю: «102 слова из лимита 104 — влезает».

Это отдельный шаг, не комбинируй с написанием. Писать и резать одновременно не работает.

Правила русской речи (главное против AI-тона)

Полный список запрещённых слов и фраз — в references/ban-list-ru.md. Прочитай его, когда пишешь Voice/Dialog.

Самые частые провалы:

❌ Запрещено	✅ Замена
«давайте разберёмся», «итак», «погружаемся», «представьте»	Cold open. Сразу к делу.
«является», «представляет собой», «осуществляет»	Любой нормальный глагол.
«данный», «вышеуказанный», «в рамках»	«этот», «выше», «когда»
«это о том, как…»	«я сделал X» / «X сломался»
«имеет смысл», «таким образом», «в конце дня»	Удали.
«крутой», «топ», «потрясающий», «киллер-фича»	Конкретное число или сравнение.
«лайфхак», «секрет», «инсайт» (без иронии)	Удали.
Generic метафоры (иголка в стоге сена, слон в посудной лавке)	Метафора только если она буквально есть в источнике (например, имя ветки needle-in-haystack).

Speak-test: прежде чем отдать скрипт — мысленно прочитай каждый voiceover-блок вслух. Спотыкаешься на слове? Это слово вылетает. Длинное причастие? Заменяй на придаточное «который…».

Под-правило для разговорности:

• Короткие предложения. ≤12 слов в одном предложении voiceover.
• Один глагол в одном смысловом блоке.
• Активный залог. «Я сломал», не «было сломано».
• Цифры — буквально (47, 3.40$, 6 строк), а не «много», «несколько», «достаточно».

Шаг 8 — Что отдать пользователю

В таком порядке:

1. Story atoms (5 буллетов) — если ещё не подтверждены.
2. Hook (1 строка ≤3 сек) + 1 backup-hook другой формулы.
3. Скрипт — таблица: Время | Камера | Voice/Dialog | Текст на экране.
4. Подсчёт слов — буквально: «64 слова, влезает в 30 сек».
5. Production pack — 3–5 b-roll кадров + что писать на экране + что снять лицом.
6. Caption — 2–4 предложения, тем же тоном что и voiceover.
7. Хэштеги — 4–8 штук: нишевый (#buildinpublic), вертикаль (#petproject, #разработка), широкий (#айти). Без #tagsforlikes.
8. Обложка — описание первого кадра как постера.

Стоп. Никаких «надеюсь, понравится», никаких «дай знать если что».

Шаг 9 — QC pass перед выдачей

Перед финальным ответом проверь:

• Хук ≤7 слов и не повторяет формулы последних 3 эпизодов, если история известна.
• Все числа/даты/длительности взяты из источников или помечены <verify>.
• Voiceover влезает в 95% бюджета слов.
• В каждом voiceover-предложении ≤12 слов.
• В скрипте есть 1–3 термина проекта, не больше. Если термин непонятен вне проекта — дай объяснение на одну секунду или покажи его на экране.
• Каждый b-roll пункт можно реально снять или захватить с экрана.
• Текст на экране короткий: до 2 строк, до 28 символов в строке.
• Первый и последний кадр рифмуются: финал возвращает к хуку или показывает его разгадку.

Антигаллюцинации (нерушимо)

• Если факта нет в источнике — его нет в скрипте. Помечай <verify> рядом со всеми числами/датами, которые не извлечены из коммитов или явно не названы пользователем.
• Не обещай контент следующего эпизода, если он не написан.
• Не выдумывай юзер-каунты («200 человек написали»), severity («это была катастрофа»), длительности («неделю не мог понять»).

Red Flags — СТОП и переписать

Сигнал	Что значит
В скрипте появилось «итак» / «давайте» / «погружаемся»	Включился AI-тон. Откатить хук, переписать заново.
Скрипт работает для любого проекта (можно скопировать в другой)	Пропустил Шаг 2 (лексикон). Вернуться.
Хук длиннее 7 слов	Произнеси вслух. >3 сек — режь.
Слов больше бюджета	Пересчитай. RU ≈ 2.5 слова/сек.
Хук той же формулы что в прошлом эпизоде	Вернись в hook-bank, выбери другую.
Атом «Pain» сформулирован девелоперским языком	Переформулируй так, чтобы поняла мама.
Один коммит как материал без признаков hotfix/milestone	Вернись в Шаг 1, агрегируй.
Score <5 — но всё равно пишу скрипт	Не надо. Скажи пользователю «материал слабый, подожди неделю».

Reference files

• references/ban-list-ru.md — полный чёрный список фраз с заменами.
• references/hook-bank-ru.md — 20+ хук-формул с примерами.
• references/register-ru.md — bad/good трансформации, как звучит живой инженер.
• references/arc-clustering.md — приёмы кластеризации коммитов в арки.