Репозиторій і стартова база 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

## Старт проєкту
- вибрано формат: фіча в наявній кодовій базі
- створено чернетку `SPEC.md`
- Claude допоміг перевірити специфікацію на двозначності
- вручну скорочено scope до одного core flow
- основний ризик: неочевидні edge cases у скасуванні підписки

Зверніть увагу: тут немає стенограми кожного натискання клавіші. І не треба. EVIDENCE.md — не транскрипт, а журнал рішень. Фіксуйте чотири речі: що ви попросили в Claude; що він реально зробив корисного; які рішення ухвалили ви самі; чим потім це перевірили. Хороший запис короткий: дата, один-два кроки, рішення, перевірка, ризик. Цього вистачить, щоб за тиждень не читати власні записи у старому блокноті з обличчям людини, яка не розуміє, хто це писав.

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

7. Перший 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 перестає бути абстрактною ідеєю й стає проєктом, з яким зручно працювати. А це, якщо чесно, набагато важливіше, ніж ефектний старт на адреналіні.