Заведение большого проекта
Скилл делает одно: превращает «есть идея и папка» в проект, к которому можно вернуться через месяц и не потерять день на выяснение, что здесь происходит.
Порядок жёсткий, и первый шаг — не структура, а решение, нужна ли она вообще.
Шаг 0. Гейт размера — большой проект или нет
Разворачивать каркас под всё подряд вредно: спеки, которых никто не читает, дороже их отсутствия. Три вопроса, отвечает владелец:
- Проект проживёт дольше двух недель?
- К нему вернутся после перерыва (неделя и больше не трогали)?
- В нём больше одного исполнителя — человек и агенты считаются разными?
Все три «да» → разворачиваем полный каркас. Иначе — говорим прямо: «это
небольшая работа, каркас будет мешать», делаем git init, .gitignore, README
из трёх строк и на этом останавливаемся. Отказ от каркаса — такой же
нормальный исход, как и разворачивание. Скилл, который всегда отвечает «да»,
превращается в ритуал.
Шаг 1. Интервью — дать себя допросить, а не заполнить анкету
Самый недооценённый приём: владелец знает свою задачу лучше всех, но не знает, чего в ней не хватает. Вопросы, которые он себе не задал, — это будущие переделки.
Поэтому здесь не форма для заполнения, а допрос. Сценарий и обязательные
неудобные вопросы — references/interview.md. Правила ведения:
- По одному вопросу за раз. Список из десяти вопросов человек проглядывает и отвечает на два.
- Не принимать размытый ответ. «Должно быть удобно» — не ответ; спрашиваем, как отличить удобное от неудобного, чем это померить.
- Обязательно спросить про провал: что случится, если этого не сделать вовсе, и что уже пробовали и почему не сработало. Здесь всплывает половина настоящих требований.
- Интервью короткое: 6–10 вопросов, не сорок.
Результат интервью → SPEC.md (шаблон — assets/SPEC.template.md). Спека пишется
словами владельца, а не пересказом: он должен узнать в ней свою задачу.
Шаг 2. Git и GitHub — до первого файла с содержимым
Порядок здесь имеет значение и нарушается чаще всего.
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 — прогон сканера утечек по всему дереву И по истории:
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 — приватный по умолчанию:
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 устаревает назавтра. В трекере — нет, потому что это же и рабочий инструмент.
bd init # заводит .beads/ в репозитории
Нужен CLI bd (Beads, бесплатный). Не установлен — команда /beads-init сама
подскажет способы установки.
Из спеки сразу заводим первые задачи, с критериями приёмки как данными:
bd create "Импорт заявок из почты" \
--acceptance "письмо с вложением .xlsx создаёт карточку; письмо без вложения — запись в лог и никакой карточки; повторное письмо не создаёт дубль"
Критерий в задаче — не украшение. Без него агент придумает критерии сам, напишет проверку под своё решение, и она, разумеется, пройдёт. Формулировка через наблюдаемое поведение, а не «работает корректно».
Разделение обязанностей: документация отвечает «как устроено и почему», бэклог — «где мы сейчас». Смешивать — гарантированный дрейф.
Шаг 5. CI — гейт, а не украшение
Минимум, который окупается сразу (шаблон — assets/ci-minimal.yml):
- типы и линтер;
- тесты;
- проверка связности документации: все пути, упомянутые в
CLAUDE.md, существуют.
Последний пункт — то, ради чего всё затевалось. Врущая карта хуже отсутствующей: без неё агент идёт смотреть факты, а с ней строит выводы на неверном и потом их защищает. CI не даёт вранью доехать до main.
Если в проекте есть свой чекер ссылок — прогонять его с канарейкой (подложенной заведомо битой ссылкой). Без канарейки «ноль ошибок» неотличимо от «проверка сломалась и молчит».
Шаг 6. Приёмка каркаса — онбординг-тест
Каркас готов не тогда, когда файлы созданы, а когда он работает. Проверка:
спавним субагента с чистым контекстом и даём прочитать только CLAUDE.md.
Он должен ответить на пять вопросов без единого поиска по файлам:
- Что этот проект делает?
- Как его запустить?
- Где тесты и как понять, что зелено?
- Где решения и почему они такие?
- Что сейчас в работе?
Не ответил — плохая карта, а не плохой агент. Правим 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)