Scaffold Project

scaffold-project — bootstrap нового проекта

Когда пользователь говорит «новый проект» — этот скилл разворачивает полный скелет за один диалог. После scaffold все задачи в проекте идут через dev-workflow.

Шаг 0 — определить режим

Скилл различает три режима по триггер-фразе пользователя:

| Триггер | Режим | |---|---| | «новый проект», «init project», «scaffold проект», «развернуть проект», и т.п. | fresh / extension (Шаги 1–5 ниже) | | «причеши проект», «оформи как dev-проект», «back-fill бэклог», «добавь дев-обвязку», /scaffold-project --backfill | back-fill (секция «Back-fill mode» — пропускаем Шаги 1–5, идём туда) |

Если триггер двусмысленный (например, просто /scaffold-project в каталоге с CLAUDE.md) — спросить пользователя один раз: «у проекта уже есть CLAUDE.md. Это fresh-init где-то ещё, или back-fill сюда?».

Шаг 1 — pre-checks (fresh / extension режим)

Перед стартом скилл проверяет целевой каталог:

| Состояние | Действие | |---|---| | Каталог не существует / пустой | Продолжаем (mkdir создаст). | | Не пуст, нет CLAUDE.md/package.json/pyproject.toml | Продолжаем, но предупреждаем «каталог не пуст, продолжить?». | | Есть package.json или pyproject.toml без CLAUDE.md | Предлагаем extension mode: добавить недостающие base-файлы, не трогая существующее. | | Есть CLAUDE.md | Отказ + подсказка: «проект уже инициализирован. Если хочешь добавить недостающую дев-обвязку — скажи back-fill или причеши проект (см. секцию Back-fill mode)». |

Шаг 2 — диалог

Скилл задаёт пять вопросов. Не больше, не меньше.

1. Имя проекта (kebab-case). Валидация: ^[a-z][a-z0-9-]{1,40}$.

Не проходит — спрашиваем заново.

1. Однострочное описание — 1 предложение, чем проект полезен.

Если пользователь хочет дать развёрнутый scope — приветствуется, уйдёт в {{SCOPE_DESCRIPTION}} as-is.

1. Стек:

• node-cli — Node 20+ CLI или библиотека, тесты через node --test.
• python-mcp — Python MCP-сервер или скрипт, тесты через pytest.
• both — оба extension'а.
• none — только base, никакого языкового скелета.

1. Внешние сервисы, которые предполагаются сразу (Notion / Gmail /

Stripe / Sentry / другое). Список справочный — попадёт в .env.example и в комментарий к BL-001. Если ничего — none.

1. Работа с user data? — yes / no. Это любые

пользовательские данные: профили, контент пользователя, сообщения, email/telegram-чаты, транзакции. Если yes — обязательно подключаем extension multi-user-base (см. секцию «Identity & PII rules»). Это не «потом докрутим» — потом стоит недели работы.

Шаг 3 — preview + approve

Перед записью — плоский список файлов, которые скилл создаст:

/
├── CLAUDE.md
├── README.md
├── DEVELOPMENT.md
├── CHANGELOG.md
├── incidents.md
├── .gitignore
├── .env.example
├── rfc/_README.md
├── docs/decisions/_README.md
├── private/backlog.base                  # Obsidian Bases view
├── private/backlog/_README.md            # конвенции: frontmatter, статусы, теги версий
├── private/backlog/BL-1.md               # первый таск (scaffold), in_progress
├── package.json                          (если node-cli)
├── engine/index.js                       (если node-cli)
├── engine/index.test.js                  (если node-cli)
├── pyproject.toml                        (если python-mcp)
├── server.py                             (если python-mcp)
└── tests/test_smoke.py                   (если python-mcp)

Жду явного «ok» от пользователя.

Шаг 4 — запись

По approve:

1. Pre-flight check. До любых mkdir / write:

• git --version отвечает (git установлен).
• git config --get user.name и git config --get user.email оба

возвращают значение. Если что-то из этого не выполнено — отказ с понятным сообщением («настрой git config --global user.email … и попробуй заново»). Никаких файлов не создаём, пока pre-flight красный — иначе получим скаффолд без коммита и тупик в следующем запуске («есть CLAUDE.md, отказ»).

1. mkdir -p если не существует. Запомним флаг

created_root = (true | false) — пригодится для отката.

1. Для каждого файла из templates/base/ (и выбранных

templates/extensions//):

• читаем шаблон,
• подменяем плейсхолдеры (см. ниже),
• пишем в / без .tpl в имени.
• исключение: файл README.md в корне каждого

templates/extensions// — это документация самого extension'а (для скилла, не для проекта). Не копируется в проект.

• запоминаем список записанных файлов (created_files[]) —

для отката.

1. Sanity-check: grep -l '{{' (только по

только-что-записанным файлам, не по всему каталогу — иначе ловим ложные срабатывания на _README.md-примерах). Если что-то осталось — error и откат:

• fresh-mode (created_root = true): rm -rf всего каталога.
• extension-mode (created_root = false): удаляем только

created_files[], не трогая ничего другого. Никогда не удаляем целиком чужой каталог.

1. cd → git init → git add . →

git commit -m "scaffold from scaffold-project v{{SCAFFOLD_VERSION}}".

1. Спросить про push в origin (по правилу из workspace-CLAUDE.md

«после каждого коммита спрашивать про push»). Если remote ещё нет — предложить gh repo create (с подтверждением).

Плейсхолдеры

| Плейсхолдер | Источник | |---|---| | {{PROJECT_NAME}} | ответ пользователя | | {{PROJECT_NAME_UPPER}} | UPPERSNAKECASE из имени (- → _) | | {{SHORT_DESCRIPTION}} | ответ на вопрос 2, первое предложение | | {{SCOPE_DESCRIPTION}} | ответ на вопрос 2 целиком (или то же, что short) | | {{STACK}} | human-readable mapping: node-cli → Node.js 20+ (CLI / library), python-mcp → Python 3.11+ (MCP server), both → Node.js 20+ + Python 3.11+, none → TBD — choose during BL-001 | | {{DATE}} | сегодняшняя дата YYYY-MM-DD | | {{AUTHOR}} | git config user.name, или unknown | | {{SCAFFOLD_VERSION}} | версия скилла из его CHANGELOG.md | | {{EXTERNAL_SERVICES}} | ответ на вопрос 4, или none | | {{today}} | сегодняшняя дата YYYY-MM-DD (alias к {{DATE}} для frontmatter) | | {{project_name}} | то же что {{PROJECT_NAME}} (alias для frontmatter-шаблонов) |

Подмена — простой текстовый replaceAll по содержимому файла.

Шаг 5 — после scaffold

После первого коммита Claude:

1. Резюмирует что создано (файлы, какие extensions подключены).
2. Указывает на private/backlog/BL-1.md как первую задачу

(in_progress, scaffold). Открыть private/backlog.base в Obsidian — увидишь backlog как таблицу с view'ми Active / Archived / Cards.

1. Напоминает: «дальше работаем через dev-workflow. Все M/L задачи —

через RFC, тесты, code-review».

Back-fill mode — добавить дев-обвязку в существующий проект

Режим для проектов, у которых уже есть CLAUDE.md и свой контент, но нет (или есть не вся) дев-обвязка: private/backlog/, backlog.base, rfc/, incidents.md, CHANGELOG.md. Скилл добавляет недостающее из тех же templates/base/, чтобы формат был один к одному с тем, что получают свежие проекты.

Зачем: раньше Claude в таких проектах делал обвязку руками, сочинял собственные поля в frontmatter, нарушал конвенции и потом приходилось переделывать. Back-fill mode закрывает эту дыру — формат всегда из templates, ничего не сочиняется.

Когда триггерится

• Триггер-фраза: «причеши проект», «оформи как dev-проект»,

«back-fill бэклог», «добавь дев-обвязку», /scaffold-project --backfill.

• Каталог: CLAUDE.md уже существует (иначе это fresh-init, не back-fill).

Что back-fill делает (scope)

| Файл шаблона | Действие | |---|---| | templates/base/CHANGELOG.md.tpl | добавить если нет | | templates/base/incidents.md.tpl | добавить если нет | | templates/base/rfc/_README.md | добавить если rfc/_README.md нет | | templates/base/docs/decisions/_README.md | добавить если нет (опционально, спросить) | | templates/base/private/backlog/_README.md | добавить если private/backlog/_README.md нет | | templates/base/private/backlog.base.tpl | добавить если private/backlog.base нет | | templates/base/.gitignore.tpl | merge: если в существующем .gitignore нет правила, закрывающего private/ — append блок про private и Obsidian. Иначе не трогать. |

Что back-fill НЕ делает (out of scope)

• Не перезаписывает существующие CLAUDE.md, README.md,

DEVELOPMENT.md, .env.example, CHANGELOG.md, incidents.md, .gitignore — только добавляет недостающие или мерджит .gitignore.

• Не создаёт BL-1. В fresh-mode BL-1 — это «задача scaffold».

В back-fill у проекта уже есть свой backlog и/или своя первая задача — навязывать наш не нужно.

• Не мигрирует существующий BACKLOG.md или tasks/ в формат

private/backlog/BL-NN.md. Если найден BACKLOG.md — скилл скажет «найден старый формат, миграция руками или отдельной задачей, back-fill не трогает».

• Не нормализует frontmatter существующих BL-NN.md. Если в них

не-каноничные поля (area, type, статусы вроде wip/backlog) — скилл предупреждает, но не правит. Это отдельная задача (см. dev-workflow groom).

• Не подключает stack-extensions (node-cli, python-mcp) — у

существующего проекта стек свой.

• Не делает git init — проект уже git.

Алгоритм

1. Pre-check. Убедиться, что CLAUDE.md существует в cwd. Если

нет — отказ «back-fill применяется в существующем проекте, а здесь нет CLAUDE.md. Если хотел fresh-init — скажи "новый проект"».

1. Сканирование. Для каждого пункта из таблицы scope выше — проверить

target. Собрать checklist:

• ✓ файл присутствует (для backlog — проверить что есть хотя бы

_README.md или BL-*.md);

• + файл отсутствует, будем добавлять;
• ~ файл существует, но требуется merge (.gitignore);
• ⚠ файл существует, но в нём подозрительные несоответствия (см.

ниже) — не трогаем, флагуем пользователю.

Дополнительные проверки:

• private/backlog/BL-*.md существуют → прочитать frontmatter первого

попавшегося. Если поля отличаются от каноничных (например, есть area/type/updated/related или статус не из набора open|in_progress|done|archived) — ⚠ с пояснением.

• В корне есть BACKLOG.md → ⚠ «старый формат, миграция вручную».

1. Render checklist пользователю. Пример:

``` Back-fill сканер по : ✓ CHANGELOG.md ✓ incidents.md ✓ rfc/_README.md

• docs/decisions/_README.md

✓ private/backlog/_README.md ✓ private/backlog.base ~ .gitignore (добавить блок про private/) ⚠ private/backlog/BL-3.md содержит поле area: (не в каноне) — не трогаю ```

1. Если все строки ✓ — вывести «всё уже на месте, ничего делать

не надо» и завершиться. Никаких записей, никаких коммитов.

1. Иначе — preview. Показать ровно те файлы, которые будут записаны

(+) или смерджены (~). Никаких других файлов в preview быть не должно.

1. Один вопрос approve: «добавить?» — yes / no.

1. На yes:

• mkdir -p для родительских каталогов под новые файлы.
• Для каждого +: прочитать шаблон, подменить плейсхолдеры,

записать. Запомнить в created_files[].

• Для ~ .gitignore: прочитать существующий → если каких-то

строк из шаблона нет, дописать в конец отдельным блоком с комментарием # Added by scaffold-project back-fill v{{SCAFFOLD_VERSION}}. Никогда не удалять и не переупорядочивать существующие строки.

• Sanity-check: grep -l '{{' — если остатки

плейсхолдеров, error и откат только created_files[] (не трогать ничего другого в каталоге).

1. Git. git add только тех файлов, которые попадают в git (не

private/, потому что он gitignored). Предложить коммит-сообщение: `` chore: back-fill dev scaffolding via scaffold-project v{{SCAFFOLD_VERSION}} `` Не коммитим без явного approve пользователя (правило из global CLAUDE.md).

Плейсхолдеры в back-fill

Только те, что встречаются в файлах из scope:

• {{SCAFFOLD_VERSION}} — версия скилла из его CHANGELOG.md.
• {{DATE}} — сегодня YYYY-MM-DD.
• {{PROJECT_NAME}} — basename cwd (как fallback, если в файле

плейсхолдер встретится; в текущих шаблонах back-fill scope его нет).

Edge cases

• Каталог не git-репозиторий → выполнить back-fill, но не предлагать

git add/коммит. Сказать «это не git-репо, инициализируй git руками, если хочешь».

• **Есть CLAUDE.md, но нет любого другого индикатора проекта (только

пустой CLAUDE.md)** → продолжить back-fill, это валидный случай.

• Пользователь сказал «новый проект» в каталоге с CLAUDE.md →

отказ + подсказка про back-fill (см. Шаг 1).

• Пользователь сказал «back-fill» в пустом каталоге → отказ «здесь

нет CLAUDE.md, ты, видимо, хотел fresh-init. Скажи "новый проект"».

Self-update triggers — петля обратной связи

Когда пользователь работает внутри проекта, созданного через scaffold-project (или живущего по тем же конвенциям), и впервые появляется один из паттернов ниже — до коммита Claude обязан сказать:

> «Это первый раз, когда мы делаем X в этом проекте. Хочешь, я вынесу > обвязку в ~/.claude/skills/scaffold-project/templates/extensions//, > чтобы следующие проекты получали её сразу?»

| Триггер | Имя extension'а | |---|---| | Профильно-пользовательская архитектура (multi-user, identity, PII разделение) | multi-user-base | | Подключение event analytics (PostHog/Amplitude/Mixpanel/GA4) | ui-analytics | | Подключение error tracking (Sentry/Bugsnag/Rollbar) | error-tracking | | Auth-флоу (OAuth/Clerk/Supabase Auth/Auth0) | auth | | Платежи (Stripe/Paddle/LemonSqueezy) | payments | | Первый GitHub Actions workflow | ci-github | | Pre-commit secret-guard, написанный руками | secret-guard | | Feature flags (GrowthBook/LaunchDarkly/Unleash) | feature-flags | | DB migrations (Prisma/Alembic/Knex) | db-migrations | | Dockerfile + deploy-config (Fly/Railway/Render) | deploy-saas | | UI SPA scaffold (React/Vue/Svelte) | ui-spa | | MCP server в Node | mcp-node |

Решение принимает пользователь. Если «не сейчас» — в этом же проекте Claude больше не спрашивает про этот паттерн (на текущую сессию). В другом проекте — спросит снова.

Как добавить новый extension (по approve пользователя)

1. Создать каталог

~/.claude/skills/scaffold-project/templates/extensions//.

1. Положить туда файлы паттерна с плейсхолдерами вместо

project-specific значений (имена, токены, URL, продакт-named константы).

1. Добавить короткий README.md в самом extension'е: что включает,

когда подключать, какие env-vars ждёт, как тестировать локально.

1. Обновить CHANGELOG.md скилла: новая запись «extension ``

added» с датой и кратким резюме.

1. Обновить таблицу выше (триггер → имя extension'а), если паттерн

новый.

1. Обновить Шаг 2 / вопрос про стек, если extension может быть

подключён на старте проекта (а не только инкрементально).

1. Если extension должен подсказывать threat-model в RFC (для auth,

payments, secret-guard) — упомянуть это в его README.

После этого вынос в текущем проекте идёт как обычно: код в проекте коммитится, а его обобщённая копия живёт в скилле.

Backlog как DB (Obsidian Bases)

С v0.3.0 бэклог скаффолдится как база, а не как страница.

• Один таск = один файл BL-NN.md (только номер, без слага в имени).
• В каждом — frontmatter: id, title, status, priority, tier, created, tags (опц. closed, refs, blocked_by).
• Статусы — только 4: open, in_progress, done, archived.
• Версии (mvp-0, v0.5, v1.0, v2.0) — через теги, не отдельные поля.
• private/backlog.base — Obsidian Bases view с готовыми таблицами (Active / Archived / Cards). Юзер открывает в Obsidian и видит всё как DB.

Конвенции расписаны в templates/base/private/backlog/_README.md. Шаблон первого таска — в BL-1.md.tpl. Правило: **не создавать единый `BA

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ymuromcev
• Source: ymuromcev/claude-scaffold-project
• License: MIT

Install and usage instructions live in the source repository linked above.