Рабочий процесс greenfield с Claude Code: от пустого репозитория до первого вертикального среза

Чего стоит избегать при старте greenfield

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

Некоторые проблемы повторяются снова и снова:

• Код «работает на моей машине», потому что настройка живёт в чьей‑то голове, а не в скриптах.
• Дерево папок отражает порядок создания файлов, а не то, как приложение должно развиваться.
• Цикл, где каждая новая подсказка переписывает предыдущие решения, так что ничего не становится стабильным.

Ранние решения тяжело отменять, потому что всё на них нарастает. Запутанная структура постоянно закрепляется. Ручная сборка превращается в десять разных наборов шагов. Если вы не зафиксируете простую команду dev рано, то не сможете понять, сломало ли изменение приложение или просто окружение.

Когда в этом тексте говорится «запускаемое приложение», подразумевается конкретное поведение: одна команда запускает проект, печатает предсказуемый вывод и громко падает, если чего‑то не хватает. Вы должны иметь возможность удалить локальную установку, склонировать репозиторий, выполнить эту команду и получить тот же результат.

«Вертикальный срез» — это минимальная сквозная фича, которая доказывает, что приложение реально. Не макет UI. Не отдельная таблица в базе. Это тонкая линия через всю систему: страница с формой, один API‑эндпоинт, который сохраняет данные, одна запись в базе и видимый результат на странице.

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

Решите первый срез до генерации файлов

Чётко определённый первый срез держит репозиторий в порядке и делает подсказки целенаправленными. Это момент, чтобы решить, что вы хотите продемонстрировать end‑to‑end, а не то, каким станет полный продукт.

Выберите наименьшую пользовательскую историю, которая доказывает работу приложения по всему пути. Хороший срез затрагивает UI, данные и одно реальное действие. Пример: «Как пользователь, я могу добавить задачу и увидеть её в списке после перезагрузки.» Это небольшая история, но она заставляет продумать маршрутизацию, валидацию, хранение и базовый экран.

Выберите одну целевую платформу на первую неделю и придерживайтесь её. Если вы начинаете с web, делайте только web. Не добавляйте мобильные экраны «на всякий случай». Даже если вы планируете позже использовать платформу вроде Koder.ai, первый срез даст лучшие результаты, если он останется в одной «полосе» (React web, Go API или Flutter).

Опишите в чёткой форме, что значит «готово для первой недели»:

• Запускается локально из свежего клона одной командой
• Одна рабочая фича, через которую можно пройти кликами end‑to‑end
• Ошибки показывают понятное сообщение для человека (не стек‑трэйс)
• Данные где‑то сохраняются простым способом (даже локальная база)

Запишите затем три не‑цели, которые защищают область работ. Например: без аутентификации, без темы оформления, без фоновых задач.

Когда эти решения зафиксированы письменно, ваша генерационная подсказка может быть строгой: строить только то, что поддерживает срез, а всё остальное пометить TODO.

Пара предварительных решений, которые спасут от доработок

Перед тем как попросить Claude сгенерировать что‑то, зафиксируйте несколько значений по умолчанию. Они кажутся мелочами, но предотвращают путаницу «переименовать потом всё».

Во‑первых, решите форму приложения. Если вам действительно нужен браузерный UI и бэкенд, начните с двух частей (frontend + API) и общего места для контрактов (типы API или простой schema). Если приложение может быть серверно‑рендеренным, держите его в одном кодовом базе, чтобы локальная разработка оставалась простой.

Далее договоритесь о правилах конфигурации. Используйте локальный env‑файл, не кладите секреты в git и заведите шаблон (например, .env.example) с безопасными плейсхолдерами и короткими комментариями. Это упрощает онбординг и снижает утечки секретов.

Выберите стандартные порты для разработки и держите их стабильными. Порты попадают в скрипты, документацию и сообщения об ошибках, поэтому менять их позже неприятно. То же касается наименований: папки, сервисы и пакеты должны следовать одной конвенции. Последовательность важнее «идеальной» конвенции.

Простой набор начальных решений:

• Форма приложения: одно приложение или frontend + API
• Конфиг: локальный .env, в репозитории .env.example
• Порты: один для web, один для API, один для БД (если нужно)
• Имена: единый стиль именования для папок и сервисов
• Секреты: не коммитить, ротировать при утечке

Пример: вы выбираете web на порту 3000 и api на порту 8080. В шаблоне env есть API_URL=http://localhost:8080 и DATABASE_URL=.... Когда Claude позже генерирует скрипты и документацию, всё становится согласованным, вместо того чтобы разъезжаться.

Как подсказывать Claude Code, чтобы он оставался структурированным

Начните с запроса исполняемого скелета, а не «всего приложения». Самый быстрый путь к нездоровому результату — просить фичи до того, как есть место для них.

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

Простой способ держать дисциплину — установить правила в подсказке:

• Сначала сгенерируйте минимальный runnable skeleton (страница приветствия, health‑эндпоинт или один экран).
• Предложите структуру папок и поясните назначение каждой папки в 1 предложении.
• Добавьте скрипты, которые работают на чистой машине (install, dev, test, build) и укажите предпосылки.
• Держите изменения в пределах одного PR‑размера и перечислите точно, какие файлы будут созданы или отредактированы.
• Остановитесь после scaffold и скажите, как его запустить.

Вот подсказка, которую можно переиспользовать и править:

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder’s README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my “ran it” confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

Держите цикл коротким. Не просите пять изменений сразу. Сгенерируйте одно маленькое изменение, запустите его, вставьте точную ошибку (или успех), затем попросите минимальную правку. Такой цикл «генерация‑запуск‑исправление» делает проект предсказуемым и мешает структуре разъезжаться.

Пошагово: от пустого репозитория до исполняемого скелета

Начните с одного обещания: любой может склонировать репозиторий и выполнить одну команду, чтобы увидеть что‑то работающее. Это даёт стабильную базу перед тем, как просить ИИ добавить реальные фичи.

Создайте репозиторий и напишите крошечный README, пока всё свежо. Держите его практичным: предусловия, одна команда dev и как запускать тесты (даже если тесты пока пустые).

Далее выберите верхнеуровневую раскладку, соответствующую форме приложения, которую вы выбрали.

Если вы строите несколько деплоимых частей (например, frontend + API), workspace‑структура может помочь:

/
  apps/
  packages/
  scripts/
  docs/
  README.md

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

Теперь добавьте минимальные ограничители, чтобы код оставался согласованным. Выберите один форматтер и один линтер, примите их дефолтные настройки и добавьте один конфигурационный файл для каждого. Цель — чистые diffs, а не идеальные правила с первого дня.

Сделайте опыт разработки предсказуемым одной командой, которая всегда работает из корня репозитория. Вот простая форма:

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

Прежде чем генерировать что‑то ещё, запустите эту dev‑команду, подтвердите, что она успешно завершилась (или подняла заглушечный сервер), затем сделайте первый коммит только со scaffold. Если коллега (или вы сами в будущем) сможет воспроизвести setup с нуля, можно приступать к первому срезу.

Структура папок, которая выдержит рост приложения

Хорошая greenfield‑структура делает две вещи: помогает быстро находить код и даёт Claude меньше пространства для придумывания новой структуры при каждом запросе. Цель не в идеале. Цель — стабильность.

Если вы работаете внутри одного приложения (или в apps/<name>/), простая внутренняя раскладка обычно держится хорошо:

• src/ — код приложения (фичи, общие компоненты, точки входа)
• config/ — небезопасная конфигурация
• tests/ — более высокоуровневые тесты, читающиеся как поведение пользователя
• scripts/ — вспомогательные скрипты (dev setup, сброс БД, релизные задачи)
• docs/ — короткие заметки и чек‑листы, которые вы реально поддерживаете

Внутри src/ разделяйте код фич от общего кода по шаблонам изменения. Код фич часто меняется и должен жить рядом. Общий код — скучный и переиспользуемый.

Практическое правило: помещайте экраны UI, обработчики и логику конкретной фичи под src/features/<featureName>/.... Коды вроде логирования, API‑клиентов, компонентов дизайн‑системы и утилиты — под src/shared/.... Если хелпер имеет смысл только в одной фиче, держите его в этой фиче даже если он кажется переиспользуемым. Перенесёте, когда появится второй реальный кейс.

Имена папок должны описывать назначение, а не технологию. features и shared остаются понятными при смене стека. Избегайте имён вроде misc или new.

Держите docs/ маленьким. Хорошая стартовая подсказка — docs/checklists.md с несколькими строками: как запускать, как тестировать, как добавлять новую папку фичи и что значит «готово».

Скрипты сборки, которые делают проект предсказуемым

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

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

Вот простая база, которую можно адаптировать под любой стек:

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

Сделайте dev‑скрипт основной дорогой. Он должен стартовать приложение, печатать, где оно работает, и вывод логов должен быть читабельным. Если сервер не может запуститься, пусть он быстро падёт с одним чётким сообщением (отсутствует переменная окружения, порт занят, база недоступна).

build должен всегда создавать чистую директорию вывода: удалять старые артефакты, а затем генерировать новые. Это избегает странных багов от файлов вчерашнего билда.

Для тестов разделите быстрые и медленные проверки. Быстрые тесты запускаются при каждом изменении (unit, проверки типов). Полные тесты включают интеграционные проверки и запускаются перед мерджем.

Стиль поддерживайте одной командой. Простое правило: format исправляет, lint жалуется.

Наконец, добавьте smoke‑проверку, которая валидирует базовые вещи перед тем, как вы тратить время на дебаг:

• Обязательные env‑переменные установлены (и не пустые)
• Выбранные порты свободны
• Приложение может стартовать и ответить на простой запрос
• Подключение к базе работает (если используется)
• После build существует ожидаемый вывод

Постройте первый вертикальный срез

Ваш первый вертикальный срез должен доказать, что приложение работает end‑to‑end, а не просто что UI выглядит красиво. Это значит: одна маленькая фича, затрагивающая экран, логику и хранение, даже если хранение временное.

Выберите что‑то скучное и полезное, например «Добавить заметку» или «Создать задачу». Держите фичу достаточно маленькой, чтобы закончить за один присест, но полной, чтобы можно было кликать и видеть реальные изменения состояния.

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

Начните с заглушки для хранилища, чтобы двигаться быстро. Массив в памяти, локальный JSON‑файл или простой stub‑интерфейс — нормально. Главное — создать границу, которую потом легко заменить. Если сегодня код вызывает taskRepository.save(task), переход на реальную базу позже будет маленьким изменением, а не переписыванием.

UI держите простым. Пропустите споры о дизайн‑системе, состояния пустоты и анимации.

Проверки приёмки, которые можно сделать за две минуты:

• Страница открывается без ошибок
• Можно ввести значение и нажать Save
• Новый элемент сразу появляется
• Перезагрузка показывает ожидаемое поведение (сохранённое, если реальное хранение, или сброшенное, если заглушка)
• Плохой ввод обрабатывается (пустой заголовок показывает сообщение и не сохраняется)

Сделайте проект достаточно стабильным для итераций

Когда у вас есть исполняемый скелет и один вертикальный срез, цель меняется: сделайте так, чтобы поломки были очевидны, а исправления — быстрыми. Многие greenfield‑старты разваливаются не из‑за сложности фичи, а из‑за того, что мелкие изменения начинают вызывать сюрпризы.

Установите маленький порог стабильности, которому вы будете соответствовать при добавлении каждого среза:

• Один smoke‑тест, который доказывает, что приложение поднимается и основной маршрут/экран рендерится
• Один smoke‑тест, который прогоняет срез end‑to‑end (даже если использует тестовую БД)
• Понятные сообщения об ошибках для обычного пользователя (не стек‑трэйсы)
• Логирование, которое объясняет, что произошло, без печати секретов
• Минимум зависимостей, версии зафиксированы, обновления выполняются осознанно

Конкретный пример: ваш первый срез позволяет создать «Project» и увидеть его в списке. Добавьте тест, который стартует сервер, вызывает endpoint создания, затем получает список и проверяет, что новый элемент появился. Если тест падает, он должен падать громко с понятным сообщением типа «Create Project endpoint вернул 500», а не стеной вывода.

Для обработки ошибок придерживайтесь небольшой согласованной схемы. Ошибки валидации возвращают короткое сообщение («Требуется имя») и имя поля. Неожиданные ошибки — «Что‑то пошло не так. Попробуйте снова.» Детали — в логах.

Логирование наиболее полезно, когда отвечает на вопросы: какой запрос, какой пользователь (или anonymous), что упало и где. В dev включайте request id и время выполнения, но избегайте дампа токенов, паролей, ключей API или полных полезных нагрузок по умолчанию.

Добавьте маленькую health‑проверку. В web это может быть /health, возвращающий ok. На мобильных — состояние «Connected», которое переключается в «Offline», когда приложение не может достучаться до бэкенда. Это быстрый индикатор перед тем, как вы начнёте дебаг не той вещи.

Распространённые ловушки при использовании ИИ для greenfield

Быстрейший способ провалить greenfield — попросить модель сгенерировать «целое приложение», а запускать это потом. Крупные генерации скрывают мелкие ошибки: отсутствующие зависимости, неверные пути импортов, скрипты, которые предполагают инструменты, которых у вас нет. Относитесь к каждому выводу как к тому, что вы должны суметь запустить за несколько минут.

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

Также часто происходит дрейф команд. ИИ добавляет новый способ запуска сервера, вы добавляете ещё один для тестов, и скоро никто не знает, какая команда — «та самая». Если коллега клонирует репозиторий и спрашивает «Как запустить?», вы уже платите по процентам.

Ошибки, вызывающие наибольшую переработку:

• Генерация множества сервисов, экранов и конфигураций за один раз вместо создания одного runnable пути сначала
• Подтягивание аутентификации, платежей, сложной стилизации и полной модели данных до того, как первая фича работает end‑to‑end
• Хранение инструкций по настройке в чате вместо скриптов (или единого README)
• Забвение чистого env‑шаблона, из‑за чего на следующей машине ничего не запускается без догадок

Простой пример: вы сгенерировали «полное» приложение с логином, темами и биллингом, но первый запуск падает из‑за отсутствующего секретного ключа и .env.example. В результате вы тратите час на настройку вместо того, чтобы понять, полезна ли фича.

Держите всё честно: одна runnable‑команда, одна маленькая фича, один env‑шаблон, затем расширение.

Быстрый чек‑лист перед следующей итерацией

Перед тем как добавить «ещё одну фичу», убедитесь, что проект легко поднимется завтра (или кем‑то другим). Скорость — не единственная цель. Важна предсказуемость.

• "Одна команда" для запуска: новый разработчик может скопировать env‑шаблон, задать несколько требуемых значений и стартовать приложение одной командой. Если нужны доп. шаги (подготовка БД, миграции, seed), автоматизируйте их в скрипте.
• Скрипты покрывают базовые команды: dev, test, build и быстрый smoke‑чек.
• Очевидная структура: раскладка сама рассказывает историю (код приложения, конфиг, скрипты, тесты) без чтения всего репозитория.
• Путь демонстрации вертикального среза: можно описать демо одной фразой, например «создать элемент, увидеть его в списке, обновить страницу — и он на месте».
• Точка отката: перед крупными изменениями у вас есть безопасная точка возврата (чистый коммит, тег или снимок/rollback механизм).

Если что‑то не проходит — исправьте это сейчас. Упорядочивание скриптов и имен — дешёвая операция, пока репозиторий маленький.

Следующие шаги: сделайте процесс повторяемым

Greenfield‑старт окупается только если вы можете повторять его. После того как первый вертикальный срез успешно работает end‑to‑end, заморозьте удачные вещи в небольшой шаблон: те же шаблоны папок, те же имена скриптов и тот же способ связывать UI, API и данные.

Обращайтесь к первому срезу как к эталонной реализации. При старте среза №2 копируйте форму, а не код. Если у среза №1 есть маршрут, обработчик, слой доступа к данным и базовый тест, срез №2 должен следовать той же дорожке.

Планируйте легко. Одностраничная заметка достаточна для следующих 2–3 срезов: цель и пользовательское действие для каждого среза (одно предложение), данные, которые нужны, критерии «done» и риски, которые стоит протестировать раньше.

Делайте обслуживание привычкой. Раз в неделю делайте короткий проход по чистке: упорядочивайте скрипты, обновляйте README новыми шагами настройки и освежайте .env.example, чтобы онстробордирование оставалось простым.

Если вы предпочитаете цикл «чат‑первый», Koder.ai (koder.ai) — один из вариантов, который поддерживает режим планирования, снимки и откат, и может экспортировать исходный код, когда хотите перенести проект.

Цель — рабочий процесс, который можно выполнять автоматически: планируйте 2–3 среза, строите один срез, стабилизируйте, повторяйте.