build-with-me

Какую проблему решает

Обычная сгенерированная документация объясняет готовый код. Готовый код не может сказать, что сборка падала дважды из-за занятого файла, что очевидный подход оказался неверным, что из трёх попыток сработала четвёртая. Эта информация есть только в истории работы.

Навык сохраняет ошибки. Шаг выглядит так:

Что получается на выходе

• вступление, где сказано, что строится и зачем, до всяких подробностей;
• оглавление томов, глав и элементов;
• каждый элемент разобран трижды: что это, зачем он и что сломается без него — конкретно, а не «он необходим»;
• код, написанный вживую в тексте, а не таблицей;
• два вида ошибок: те, что случались на самом деле, и те, что читатель встретит на другой машине;
• заброшенные подходы — чтобы читатель не потратил тот же час.

Структура

Том     крупная часть программы: платформа, среда, подсистема
  Глава этап с проверяемым результатом: «сборка даёт подписанный APK»
    Элемент файл, ресурс, объект, слой — что сломается без него
      Шаг   действие, описанное с причиной и следствием

Установка

npx skills add fworkslab/build-with-me@build-with-me -a opencode -g -y

Или скопировать вручную — навык это один файл с заголовком YAML:

~/.config/opencode/skills/build-with-me/SKILL.md

Не только для кода

Структура выживает, когда проект не программа. Меняется только словарь: элемент — то, к чему читатель вернётся, когда что-то сломалось, а шаг — любое действие, названное точно настолько, чтобы повторить.

Проект	Элемент — это	Шаг — это
Программа	файл	код
Игра на движке	ассет, актор, Blueprint, уровень	вызов инструмента, консольная команда
Blender	коллекция, модификатор, кость, ключ	операция с её настройкой
Maya, Houdini, ZBrush	нода, subtool, точка привязки	точное изменение параметра
Таблица, анализ	лист, именованный диапазон, формула	формула с адресами ячеек
Документ	уровень заголовка, раздел, стиль	применение названного стиля
Рисунок	слой, проход, палитра	мазок с инструментом, размером, углом

Чего навык не делает

• Не раздувает маленький проект. Число элементов считается с машины до планирования, поэтому папка с одним файлом получает одну главу — а не два тома, оглавление и восемьсот строк.
• Не выдумывает прошлые ошибки. Если шаг прошёл чисто, так и написано. Туториал с выдуманными проблемами учит читателя ждать отказов, которых не будет.
• Не выдумывает историю, которой не видел. Дан чужой репозиторий — структура и рассуждения всё равно выводятся из файлов. Что именно ломалось и что бросили — нет. И туториал прямо говорит, какие части восстановлены из кода, а не из сборки.

Лицензия