Репозиторий и стартовая база capstone

1. Capstone не начинается с «сделай приложение»

На этом месте очень хочется открыть Claude Code и написать что-нибудь бодрое вроде: «Сделай мне сервис для подписок, дашборд, красивый интерфейс и желательно без ошибок». Желание понятное, человеческое и даже слегка трогательное. Но именно так обычно появляются репозитории, где код уже есть, а ответов на «что это делает?» и «как это проверять?» ещё нет.

Capstone почти никогда не ломается из-за того, что вы слишком мало попросили у ИИ. Куда чаще он ломается из-за слишком раннего старта. Большой генеративный рывок даёт ощущение движения — но движения без дорожной разметки: код уже в src/, а структуры репозитория, правил работы и привычки записывать решения ещё нет.

К этому моменту у вас уже должен быть личный SPEC.md: формат выбран, core flow назван, non-goals записаны. Теперь контракту нужно место в репозитории, и EVIDENCE.md из абстрактного напоминания становится реальным рабочим файлом. Стартовая база даёт управляемость: следующий шаг после неё меньше и спокойнее — вы не прыгаете в темноту, а идёте короткими проверяемыми этапами. Держите в голове схему:

flowchart TD
    A[Идея проекта] --> B[SPEC.md]
    B --> C[Git baseline]
    C --> D[CLAUDE.md]
    D --> E[EVIDENCE.md]
    E --> F[Первая маленькая задача]

Здесь важно ещё одно уточнение. Когда мы говорим «рабочее пространство проекта», мы имеем в виду не только открытую папку в IDE, а весь стартовый контур: репозиторий, структура файлов, инструкции для Claude, режим осторожности, имена сессий, точки для отката. К нему вернёмся в разделе 4.

Хороший capstone стартует не с большого запроса к ИИ, а с маленькой скучной дисциплины. И это прекрасно.

2. Git-baseline: репозиторий должен быть скучным

Скучный старт — это хороший признак. Когда у вас есть понятная ветка, чистое состояние файлов и нормальный .gitignore, вы уже защищены от половины будущих сюрпризов. А их в capstone и так хватит; не зовите их ещё и хаотичным Git.

У вас обычно есть один из двух стартовых сценариев: фича в существующем коде — начинаете с готового репозитория; новый MVP, автоматизация или отдельный инструмент — создаёте с нуля. Логика одна: нужна чистая точка отсчёта.

Эта логика общая для всех шести форматов. Modernization и migration чаще стартуют внутри уже живого репозитория. DevOps automation и team workflow design нередко похожи не на продукт с UI, а на toolkit-репозиторий с .claude/, .github/, docs/ и scripts/. Форма меняется — точка отсчёта та же.

Если проект новый и похож на приложение или небольшой инструмент с кодом, старт может выглядеть так:

git init                              # создаём новый репозиторий
git status                            # проверяем стартовое состояние
mkdir -p .claude docs src             # готовим базовые папки
touch .gitignore docs/SPEC.md docs/EVIDENCE.md .claude/CLAUDE.md

Если ваш формат крутится вокруг automation или team workflow, вместо src/ вполне могут появиться scripts/, .github/ или дополнительные docs/-артефакты. Имя ветки не принципиально; важно, чтобы до первого baseline-коммита была одна чистая точка отсчёта без мусора.

Если проект уже существует, старт чуть другой:

git clone <ваш-репозиторий>           # забираем проект локально
cd <папка-проекта>
git status                            # проверяем, что дерево чистое
git switch -c feature/capstone-start  # отдельная ветка под ваш старт

Для новичков особенно важна фраза clean working tree: перед стартом вы точно понимаете, какие файлы изменены. Если там уже валяются временные файлы, вчерашние эксперименты и загадочный notes-final-final-2.txt, это не рабочая база, а археология.

Очень полезен и короткий, но честный .gitignore — не эпопея на двести строк, но отсекает то, чему в репозитории не место:

# сборка и зависимости
node_modules/
build/
dist/

# секреты и локальные настройки
.env
.env.*
*.log

Если у вас Java-проект, сюда добавятся каталоги сборки Gradle; если Python — виртуальное окружение и кэш. В репозиторий попадает то, что относится к проекту, а не всё, что случайно завелось на диске.

Полезная привычка на этом этапе — не откладывать первый коммит «до появления настоящего кода». Стартовая база — и есть настоящий код: она задаёт структуру и фиксирует первую точку отсчёта.

3. CLAUDE.md: короткая инструкция вместо уточнений

В начале capstone CLAUDE.md часто воспринимают как что-то магическое: кажется, что сейчас вы напишете туда пару суровых строк — и Claude начнёт читать ваши мысли, держать архитектуру в голове и по вечерам ещё подливать чай. Увы, телепатию пока не включили. Но хороший CLAUDE.md экономит уточнения: он объясняет, что за проект перед ним, как его запускать, что норма, а что — запрещённая самодеятельность. И он не должен наследовать правила чужого репозитория только потому, что вы видели их когда-то в Commerce OS.

Нормальный стартовый CLAUDE.md короткий, конкретный, под ваш проект:

# CLAUDE.md

## Цель проекта
Сервис для управления отменой подписки в одном сценарии.

## Команды
- run: ./gradlew bootRun
- test: ./gradlew test

## Правила
- не добавляй зависимости без запроса
- после изменений перечисляй файлы и проверки
- не трогай `.env` и секреты

Это один из типовых baseline-вариантов — сервис с явными run/test командами. В migration slice тут будут команды аудита, pilot-checks и regression suite. В DevOps automation или team workflow design — scripts/..., CI dry run, hook validation, schema checks. Важны реальные команды и границы вашего проекта.

В этом файле не нужно писать всё, что вы знаете о программировании: трактат о красоте архитектуры на шесть экранов Claude не нужен. Хороший CLAUDE.md держит четыре вещи: цель проекта в одной-двух фразах; команды запуска и проверки; правила изменения кода; границы, за которые нельзя без вашего отдельного решения — не добавлять зависимости, не менять публичный API, не трогать секреты, не делать широких рефакторингов «заодно».

Если файл начинает разрастаться до размеров небольшой повести, это почти всегда сигнал, что вы смешали постоянные правила и рабочие заметки: правила пусть живут в CLAUDE.md, а гипотезы и идеи — отдельно. И ещё один важный момент: не копируйте чужой CLAUDE.md целиком. Это очень популярная ошибка: копия выглядит солидно, но работает как костюм не по размеру — одежда вроде есть, а двигаться неудобно.

4. Рабочее пространство: permissions, сессии, папки

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

Начать стоит с режима осторожности. Точные названия permission-режимов могут меняться от версии к версии, поэтому важен принцип, а не конкретная кнопка. Для capstone почти всегда разумен консервативный режим: с явными подтверждениями на рискованные действия, без «пусть сам поправит всё подряд». На baseline скорость не нужна. Нужна предсказуемость.

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

capstone/spec
capstone/api/cancel-subscription
capstone/review/core-flow

Такие имена скучные, и в этом их сила. Через несколько дней вы не гадаете, что скрывается за экзотическим названием вроде finally-real-version.

Полезно и то, как вы раскладываете файлы по репозиторию. Базовая структура может быть очень простой:

my-capstone/
  .claude/
    CLAUDE.md
  docs/
    SPEC.md
    EVIDENCE.md
  src/
  .gitignore

Это тоже не универсальный шаблон на все шесть форматов, а спокойный стартовый вариант. У automation- и workflow-проектов дерево сильнее строится вокруг .claude/, .github/, docs/, scripts/, а src/ окажется маленьким или его не будет вовсе. Если проект связан с модернизацией или миграцией, рядом со SPEC.md можно завести пустые заготовки под карту рисков или заметку по откату. Но если у вас фича или небольшой MVP, не нагружайте репозиторий папками только потому, что «вдруг пригодится».

Удобно смотреть на стартовые артефакты вот так:

.claude/CLAUDE.md

docs/SPEC.md

docs/EVIDENCE.md

src/

Если говорить совсем честно, всё это — первая защита от ощущения «я уже сделал много, но не понимаю, где что лежит». А это ощущение приходит к новичкам удивительно быстро.

5. Backlog: core flow распадается на задачи

После настройки репозитория очень хочется наконец-то писать код. Но прямо перед этим есть ещё один скучный и невероятно полезный шаг — разложить будущую работу на короткие задачи. Даже если ваш capstone состоит из одного core flow, он почти никогда не делается одним махом: внутри прячутся настройка запуска, один happy path, проверка, документация и пара уточнений, о которых вы сначала даже не подумали.

Здесь не нужен отдельный сложный артефакт. Самый простой путь — добавить раздел с ближайшими шагами прямо в SPEC.md: так контракт и ближайший план живут рядом, а вы не плодите сущности без необходимости.

## Ближайшие шаги

- [ ] поднять проект локально
- [ ] реализовать один happy path
- [ ] добавить smoke-check для core flow
- [ ] зафиксировать проверки в EVIDENCE.md
- [ ] проверить diff и обновить SPEC.md при необходимости

Смысл backlog не в том, чтобы устроить себе корпоративный трекер задач в одиночку, а в том, чтобы разбить туман на понятные куски. Пока задача звучит как «сделать проект», мозг слегка паникует; «поднять проект», «реализовать один сценарий», «проверить команду запуска» — уже по-человечески. Очень важно, чтобы первые задачи были маленькими и проверяемыми. Не «реализовать весь модуль подписок», а «сделать один рабочий сценарий отмены». Не «написать все тесты», а «добавить один smoke-check на основной маршрут». Чем короче первая итерация, тем спокойнее дальше.

Если вам удобнее держать это не в SPEC.md, а в issue-списке репозитория — это тоже нормально. Главное — чтобы у проекта появился ритм. Claude полезнее, когда вы просите помочь с одной конкретной задачей, а не с облаком намерений.

6. EVIDENCE.md: проектный дневник

EVIDENCE.md появляется рядом со SPEC.md не «на потом», а сразу. Это проектный дневник без драмы. Вначале он выглядит почти слишком скромно: пустой файл, пара заголовков, никакого визуального блеска. Но именно этот документ потом спасает, когда вы забыли, почему приняли спорное решение, и когда надо спокойно объяснить, где помог Claude, а где решили вы сами.

Очень важно создать этот файл сразу, даже если первая запись будет короткой: пустой EVIDENCE.md на старте — не недоделка, а правильная заготовка под рабочий процесс. Вы не пишете его задним числом как героическую хронику — вы ведёте его по мере движения проекта.

# EVIDENCE.md

## Старт проекта
- выбран формат: feature in existing codebase
- создан draft `SPEC.md`
- Claude помог проверить спецификацию на двусмысленности
- вручную сокращён scope до одного core flow
- основной риск: неочевидные edge cases в отмене подписки

Обратите внимание: тут нет стенограммы каждого нажатия клавиши. И не надо. EVIDENCE.md — не транскрипт, а журнал решений. Фиксируйте четыре вещи: что вы попросили у Claude; что он реально сделал полезного; какие решения приняли вы сами; чем потом это проверили. Хорошая запись короткая: дата, один-два шага, решение, проверка, риск. Этого хватит, чтобы через неделю не читать собственные записи в старом блокноте с лицом человека, который не понимает, кто это писал.

И ещё одна тонкость: EVIDENCE.md — внутренний рабочий документ, а не публичная витрина. Он ваш инженерный след: что изменилось, почему, на основании чего и что ещё не до конца проверено.

7. Первый commit baseline: спокойная точка отсчёта

Когда стартовая база собрана, не оставляйте её болтаться в воздухе — зафиксируйте её отдельным спокойным коммитом. Это удивительно полезная точка отсчёта: бизнес-логики ещё нет, сложных правок нет, зато есть репозиторий, контракт проекта, инструкции для Claude и журнал решений. Следующий шаг делаете не на вере, а на инженерной опоре.

В первый baseline-коммит попадают самые важные стартовые элементы:

.gitignore

.claude/CLAUDE.md

docs/SPEC.md

docs/EVIDENCE.md

Команды самые обычные — в этом и прелесть:

git add .                                        # добавляем baseline-файлы
git status                                       # проверяем, что нет случайного мусора
git commit -m "Стартовая база capstone-проекта"  # первая надёжная точка отсчёта

Если ваш capstone связан с модернизацией или миграцией, в этот же коммит можно добавить пустые заготовки под карту рисков и заметку по откату, но только когда это правда соответствует формату проекта. Незачем превращать простой capstone в музей серьёзных документов.

После такого коммита у вас появляется важное ощущение: проект уже существует как инженерная система, даже если кода в нём почти нет. И это правильное ощущение, потому что теперь следующий запрос к Claude может быть маленьким и точным. Не «сделай мне весь сервис», а «помоги реализовать первый основной сценарий в рамках этого SPEC.md, не выходя за границы проекта». На такой запрос Claude отвечает лучше, да и вам на diff смотреть приятнее.

С этого момента capstone перестаёт быть абстрактной идеей и становится проектом, с которым удобно работать. А это, если честно, куда важнее, чем эффектный старт на адреналине.

1

Задача

Claude code, 25 уровень, 3 лекция

Недоступна

Первый CLAUDE.md через Claude Code in-session

Первый CLAUDE.md через Claude Code in-session

Открыть