05 / 06 · Best Practices

🏗 Mitchell Hashimoto

Создатель Vagrant и Terraform. Дисциплинированный подход: человек исследует архитектуру, Claude реализует.

🏗

Mitchell Hashimoto

Создатель Vagrant и Terraform · Основатель HashiCorp · Independent Engineer

Архитектура Vertical slices Scaffolding Manual review Research first

🏗 Контекст: создатель инфраструктурных инструментов

Mitchell Hashimoto создал Vagrant, Terraform, Packer, Vault и другие инструменты которые используют миллионы разработчиков. Его статья «Non-trivial Vibing» — честный взгляд на то как человек с глубоким техническим опытом адаптировал свой процесс работы под CC.

Главный тезис Mitchell: CC — отличный исполнитель, но плохой архитектор. Не потому что модель слабая — а потому что она не несёт ответственности за архитектурные решения, которые придётся поддерживать годами.

⚠️

Частая ошибка новичков: сразу отдают незнакомую кодовую базу CC без предварительного изучения. CC пишет код который выглядит логично — но не вписывается в существующие паттерны проекта, дублирует уже имеющиеся утилиты, или нарушает архитектурные соглашения о которых CC не знал. Mitchell's правило: 30–60 минут ручного изучения кода сначала — это не потеря времени, это то что делает CC по-настоящему полезным.

🔍 Практика 1: Сначала человек, потом агент

30–60 минут ручного research перед тем как отдать Claude

Mitchell тратит от 30 до 60 минут на ручное изучение кода, документации и зависимостей перед тем как передать задачу Claude. Это не потеря времени — это инвестиция которая резко снижает количество итераций исправлений.

Почему? Claude не понимает почему система устроена именно так. Он видит код — но не видит историю решений, компромиссы, ограничения которые привели к текущей архитектуре. Человек, прочитавший код вдумчиво, даёт контекст который иначе не передать.

Конкретно что делает Mitchell: читает связанные файлы, ищет похожие паттерны в кодовой базе, проверяет тесты чтобы понять ожидаемое поведение, изучает git blame для контекста изменений.

"I spend 30–60 minutes reading code before asking Claude to touch it. This is not wasted time — it's the work that makes Claude useful."

💬 Практика 2: «Consult the Oracle» — план перед кодом

Интерактивное планирование до написания кода

После ручного research Mitchell начинает интерактивный диалог с Claude о подходе — до того как просить написать код. Он задаёт вопросы, Claude предлагает архитектуру, Mitchell валидирует, задаёт уточняющие вопросы.

Этот диалог — «Consult the Oracle» — помогает выявить слепые пятна: вещи которые Claude заметил в коде но Mitchell пропустил, и наоборот. Только после того как оба «согласны» на подход — начинается реализация.

Ключевое: Mitchell не принимает первое предложение Claude. Он задаёт вопрос «а почему именно так, а не иначе?» и требует обоснования.

md Промпт для фазы планирования

Перед тем как писать код, я хочу обсудить подход.

Контекст: [описание задачи и что ты уже изучил]

Вопросы:
1. Как бы ты подошёл к реализации этого?
2. Какие риски ты видишь?
3. Есть ли альтернативные подходы и почему ты предпочитаешь предложенный?

Не пиши код — только обсудим архитектуру.
Я задам уточняющие вопросы.

🪓 Практика 3: Vertical Slices — по одному полному слою

Одна фича целиком, не все модели сразу

Mitchell работает вертикальными срезами (vertical slices): каждая единица работы — одна полная фича от UI до базы данных, включая интеграционный тест. Не «сначала все модели, потом все контроллеры, потом все вью».

Преимущества vertical slices при работе с Claude: на каждом шаге есть working software. Если что-то пошло не так — ошибка локализована в этом срезе. Нет большого merge конфликта в конце когда все горизонтальные слои встречаются.

Каждый vertical slice — отдельный git branch, отдельная Claude-сессия, отдельный PR для review.

❌ Горизонтальный подход (плохо)

Шаг 1: все миграции
Шаг 2: все модели
Шаг 3: все сервисы
Шаг 4: все контроллеры
Шаг 5: все вью

Интеграция только в конце → большие конфликты, сложная отладка

✅ Vertical Slice (хорошо)

Slice 1: полная фича «регистрация»
миграция + модель + сервис + контроллер + тест
Slice 2: полная фича «вход»
Slice 3: полная фича «подписка»

Working software после каждого slice → легкий review и отладка

🧱 Практика 4: Scaffolding — skeleton-файлы с TODO

Скелет структуры создаёт человек, Claude заполняет реализацию

Mitchell создаёт файлы с правильными сигнатурами, типами и TODO-комментариями — и отдаёт их Claude для заполнения реализацией. Это гарантирует что архитектурные решения (какие методы, какие типы параметров, какие зависимости) остаются за человеком.

Claude отлично заполняет реализацию когда структура определена. Он плохо определяет структуру самостоятельно — склонен к over-engineering или наоборот к недостаточной абстракции без понимания контекста проекта.

php Scaffold: SubscriptionService.php

class SubscriptionService
{
    public function __construct(
        private SubscriptionRepository $repository,
        private PaymentGateway $payment,
        private NotificationService $notifications,
    ) {}

    // TODO: реализуй создание подписки
    // Должен: валидировать план, создавать запись, обрабатывать платёж, отправлять welcome email
    // Бросать: SubscriptionException если платёж неудачен
    public function create(User $user, Plan $plan): Subscription
    {
    }

    // TODO: реализуй отмену подписки
    // Должен: проверить что подписка активна, установить cancelled_at, NOT удалять запись
    // Отправить cancellation email через notifications
    public function cancel(int $subscriptionId): void
    {
    }
}

👀 Практика 5: Manual review перед любым шипом

Ни одна строка AI-кода без личного прочтения

Mitchell категоричен: он прочитал каждую строку кода которую зашипил, независимо от того написан ли он Claude или другим человеком. Это не недоверие к Claude — это профессиональная ответственность за код который ты выпускаешь.

Практически: diff-view в IDE (или git diff) — обязательный шаг перед каждым PR. Mitchell ищет не только баги, но и несоответствие намерению, скрытые предположения, места которые будет сложно поддерживать.

Особое внимание: security-чувствительный код (auth, платежи, данные пользователей) требует особо тщательного review даже если Claude написал «очевидно правильный» код.

"I have shipped zero AI-written code that I haven't read line by line. This is not distrust of Claude — it's professional responsibility."

💡

Тонкость для опытных: паттерн Scaffolding от Mitchell особенно силён когда скелет-файл содержит не просто // TODO, а инварианты — что метод должен гарантировать, какие исключения бросать, какие side effects недопустимы. CC читает эти комментарии как спецификацию и пишет код который соответствует им, а не «разумным предположениям». Это пересекается с философией Thorsten Ball об описании ограничений вместо реализации.

🔑 Ключевой вывод

Разделение труда: человек думает, Claude исполняет

Система Mitchell Hashimoto строится на чётком разделении труда. Человек: исследует архитектуру, принимает структурные решения, создаёт scaffolding, делает review. Claude: заполняет реализацию, пишет тесты, делает рутинную работу быстрее. Это не «vibe coding» — это дисциплинированное партнёрство где каждый делает то в чём силён.

🔗

Смотрите также: Паттерны экспертов — Spec Pipeline как расширение scaffolding-подхода. Мульти-агентность — vertical slices с параллельными агентами. Git Worktrees — изоляция vertical slices.

📋 Детальный пример диалога планирования

Вот как выглядит реальный диалог фазы «Consult the Oracle» у Mitchell. Он ведёт его письменно чтобы иметь запись решений:

markdown Диалог планирования: система уведомлений

Mitchell: Изучив код, вижу что уведомления сейчас отправляются синхронно в контроллере.
Хочу вынести их в очередь. Как бы ты подошёл к этому?

Claude: Вижу несколько вариантов:
1. Laravel Queue с database driver (уже настроен судя по config)
2. Redis Queue для высокой нагрузки
3. Простой Event/Listener паттерн

Учитывая что в проекте уже есть database queue config — предлагаю начать с него.

Mitchell: А почему не Redis сразу? Мы же планируем рост.

Claude: Преждевременная оптимизация. Database queue на текущих объёмах
(судя по миграциям — ~1000 пользователей) достаточна.
Redis добавляет зависимость и сложность. Переход несложный когда понадобится.

Mitchell: Согласен. Что насчёт retry логики при сбое отправки?

Claude: Laravel Queue имеет встроенный retry. Рекомендую:
- maxTries: 3
- backoff: [60, 300, 900] секунд (exponential backoff)
- failedJob table для анализа сбоев

Mitchell: Хорошо. Теперь пиши код.

🔍 Checklist перед отдачей задачи Claude

Mitchell использует внутренний checklist перед тем как начать работу с Claude над любой нетривиальной задачей:

markdown pre-claude-checklist.md

## Перед тем как отдать задачу Claude

# Research
- [ ] Прочитал все файлы которые будут затронуты
- [ ] Понял почему они устроены именно так (git blame / история)
- [ ] Нашёл похожие паттерны в кодовой базе
- [ ] Прочитал тесты чтобы понять ожидаемое поведение

# Planning
- [ ] Провёл «Consult the Oracle» диалог
- [ ] Согласовали подход — не принял первое предложение
- [ ] Создал scaffold-файлы с TODO если нужно

# Execution
- [ ] Задача разбита на vertical slice
- [ ] Есть тесты (или план их написания)
- [ ] Знаю как верифицировать результат

# Review
- [ ] Прочту каждую строку diff перед merge
- [ ] Особое внимание: security, auth, payment-код

⚠ Антипаттерны которые Mitchell видит у других

«Дай мне весь сервис подписок» — слишком широкий промпт

Широкие промпты дают широкие результаты: Claude придумывает архитектуру без понимания контекста, создаёт лишние абстракции, нарушает существующие паттерны проекта. Результат требует значительного рефакторинга.

Merge без чтения — «Claude же написал, значит правильно»

Mitchell видел достаточно production инцидентов от AI-кода который «выглядел правильным» чтобы стать категоричным: личное чтение кода — не опциональный шаг. Это ответственность за то что ты выпускаешь.