# Project Bootstrap

> Заводит большой проект: интервью, спека, git и GitHub, каркас docs, бэклог bd, CI. Триггеры: «заведи проект правильно», «новый большой проект». НЕ каркас стека→/init-project

- Skill: `jhamidun/project-bootstrap` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx get-skill add jhamidun/project-bootstrap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jhamidun/project-bootstrap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JHamidun (https://skillmd.com/u/jhamidun)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/jhamidun/project-bootstrap

---


# Заведение большого проекта

Скилл делает одно: превращает «есть идея и папка» в проект, к которому можно
вернуться через месяц и не потерять день на выяснение, что здесь происходит.

Порядок жёсткий, и первый шаг — не структура, а **решение, нужна ли она вообще**.

---

## Шаг 0. Гейт размера — большой проект или нет

Разворачивать каркас под всё подряд вредно: спеки, которых никто не читает,
дороже их отсутствия. Три вопроса, отвечает владелец:

1. Проект проживёт **дольше двух недель**?
2. К нему **вернутся после перерыва** (неделя и больше не трогали)?
3. В нём **больше одного исполнителя** — человек и агенты считаются разными?

**Все три «да» → разворачиваем полный каркас.** Иначе — говорим прямо: «это
небольшая работа, каркас будет мешать», делаем `git init`, `.gitignore`, README
из трёх строк и на этом останавливаемся. **Отказ от каркаса — такой же
нормальный исход, как и разворачивание.** Скилл, который всегда отвечает «да»,
превращается в ритуал.

---

## Шаг 1. Интервью — дать себя допросить, а не заполнить анкету

Самый недооценённый приём: владелец знает свою задачу лучше всех, но не знает,
**чего в ней не хватает**. Вопросы, которые он себе не задал, — это будущие
переделки.

Поэтому здесь не форма для заполнения, а допрос. Сценарий и обязательные
неудобные вопросы — `references/interview.md`. Правила ведения:

* **По одному вопросу за раз.** Список из десяти вопросов человек проглядывает
  и отвечает на два.
* **Не принимать размытый ответ.** «Должно быть удобно» — не ответ; спрашиваем,
  как отличить удобное от неудобного, чем это померить.
* **Обязательно спросить про провал:** что случится, если этого не сделать
  вовсе, и что уже пробовали и почему не сработало. Здесь всплывает половина
  настоящих требований.
* Интервью короткое: 6–10 вопросов, не сорок.

Результат интервью → `SPEC.md` (шаблон — `assets/SPEC.template.md`). Спека пишется
**словами владельца**, а не пересказом: он должен узнать в ней свою задачу.

---

## Шаг 2. Git и GitHub — до первого файла с содержимым

Порядок здесь имеет значение и нарушается чаще всего.

```bash
git init -b main
# .gitignore ПЕРВЫМ, до первого коммита (основа — assets/gitignore-base навыка)
cp ~/.claude/skills/project-bootstrap/assets/gitignore-base .gitignore
git add .gitignore && git commit -m "chore: gitignore"
```

**`.gitignore` до первого коммита — не педантизм.** Секрет, попавший в историю,
простым удалением файла оттуда не вынимается: он остаётся в объектах и уезжает
вместе с репозиторием. Базовый набор — `assets/gitignore-base`, дополняем под стек.

Перед первым `push` — прогон сканера утечек по всему дереву И по истории:

```bash
python ~/.claude/skills/leak-scan/scripts/leak_scan.py .            # рабочая копия
git log --all -p > scratchpad/history.txt                           # вся история одним текстом (scratchpad/ в .gitignore)
python ~/.claude/skills/leak-scan/scripts/leak_scan.py scratchpad/history.txt
rm scratchpad/history.txt
```

История обязательна: сканировать только рабочую копию бессмысленно, когда
проверяем перед публикацией. Ключ, удалённый вторым коммитом, из истории не
уходит, а сканер файлов его не видит. (В версии сканера с флагом `--git-history`
второй и третий вызов заменяет один: `leak_scan.py . --git-history`.)

GitHub — **приватный по умолчанию**:

```bash
gh repo create <имя> --private --source=. --remote=origin
git push -u origin main
```

Публичным делаем только по явной просьбе владельца и только после чистого
прогона сканера.

---

## Шаг 3. Каркас — карта, а не библиотека

```
CLAUDE.md          карта проекта, ≤20 строк: где что лежит и куда идти за чем
SPEC.md            что строим и как отличить готовое от неготового
docs/
  adr/             принятые решения: почему так, а не иначе
  specs/           спека на фичу — по одной, по мере появления
progress.md        журнал: дата, что сделано, чем подтверждено
.beads/            бэклог (создаётся bd init)
scratchpad/        черновики и пробы — В GITIGNORE
```

Шаблоны файлов — в `assets/`: `CLAUDE.template.md`, `SPEC.template.md`,
`progress.template.md` (при копировании в проект имя без слова template). Три
правила наполнения, каждое выучено дорого:

**`CLAUDE.md` — навигация, а не описание.** Он грузится в системный промпт
целиком и в каждый запрос. Не «модуль импорта делает то-то», а «импорт —
src/import/, спека docs/specs/import.md, решения docs/adr/003-*.md».
Двадцать строк, а не двести.

> Примеры путей в прозе пишем **без обратных кавычек**. В кавычках их не
> отличить от настоящих ссылок, и проверка связности из шага 5 начнёт ругаться
> на выдуманное. Кавычки — только для путей, которые реально существуют.

**Числа и списки в него не пишем.** Счётчики протухают молча и потом служат
основанием для неверных выводов. Вместо «12 модулей» — команда, которой их
посчитать.

**Не документируем то, что выводится из кода.** Структура — `codegraph`,
зависимости — lockfile, API — генератор из схемы. Дублирование гарантированно
разойдётся с оригиналом.

---

## Шаг 4. Бэклог — состояние живёт в задачах, не в прозе

«Что сделано, что осталось» в markdown устаревает назавтра. В трекере — нет,
потому что это же и рабочий инструмент.

```bash
bd init                    # заводит .beads/ в репозитории
```

Нужен CLI `bd` (Beads, бесплатный). Не установлен — команда `/beads-init` сама
подскажет способы установки.

Из спеки сразу заводим первые задачи, **с критериями приёмки как данными**:

```bash
bd create "Импорт заявок из почты" \
  --acceptance "письмо с вложением .xlsx создаёт карточку; письмо без вложения — запись в лог и никакой карточки; повторное письмо не создаёт дубль"
```

Критерий в задаче — не украшение. Без него агент придумает критерии сам, напишет
проверку под своё решение, и она, разумеется, пройдёт. Формулировка через
наблюдаемое поведение, а не «работает корректно».

Разделение обязанностей: **документация отвечает «как устроено и почему»,
бэклог — «где мы сейчас».** Смешивать — гарантированный дрейф.

---

## Шаг 5. CI — гейт, а не украшение

Минимум, который окупается сразу (шаблон — `assets/ci-minimal.yml`):

* типы и линтер;
* тесты;
* **проверка связности документации**: все пути, упомянутые в `CLAUDE.md`,
  существуют.

Последний пункт — то, ради чего всё затевалось. Врущая карта хуже отсутствующей:
без неё агент идёт смотреть факты, а с ней строит выводы на неверном и потом их
защищает. CI не даёт вранью доехать до main.

Если в проекте есть свой чекер ссылок — прогонять его **с канарейкой**
(подложенной заведомо битой ссылкой). Без канарейки «ноль ошибок» неотличимо от
«проверка сломалась и молчит».

---

## Шаг 6. Приёмка каркаса — онбординг-тест

Каркас готов не тогда, когда файлы созданы, а когда он работает. Проверка:
**спавним субагента с чистым контекстом** и даём прочитать только `CLAUDE.md`.
Он должен ответить на пять вопросов без единого поиска по файлам:

1. Что этот проект делает?
2. Как его запустить?
3. Где тесты и как понять, что зелено?
4. Где решения и почему они такие?
5. Что сейчас в работе?

Не ответил — **плохая карта, а не плохой агент**. Правим `CLAUDE.md` и повторяем.
Замер честный: считаем, сколько вызовов инструментов он потратил до первого
верного ответа.

---

## Шаг 7. Правило удержания

Каркас разъезжается с реальностью не сразу, а через месяц. Поэтому в
`CLAUDE.md` проекта дописываем одну строку договорённости:

> Правка кода, которая делает утверждение в документации неверным, обязана
> править и документацию — в том же коммите.

Без этого через два месяца получится набор файлов, уверенно указывающих не туда.

---

## Чего этот скилл НЕ делает

| Задача | Куда |
|---|---|
| Каркас под выбранный стек (папки, конфиги, Dockerfile) | команда `/init-project` |
| Работа с задачами в уже заведённом бэклоге | skill `beads` |
| Ветки, PR, разбор конфликтов | skill `git-workflow` |
| Фазовая разработка по методологии GSD | команды `/gsd:new-project`, `/gsd:next` |
| Разбор существующего кода перед правкой | skill `codegraph` |
| Автодокументация кодбазы для агентов | skill `openwiki` |

## Справочники

* `references/interview.md` — сценарий допроса и обязательные вопросы
* `references/anti-patterns.md` — на чём этот процесс ломается и как это выглядит
* `assets/` — шаблоны `CLAUDE.template.md`, `SPEC.template.md`, `progress.template.md`, основа `.gitignore` (`gitignore-base`), CI (`ci-minimal.yml`)

