05 / 06 · Best Practices

📋 Harper Reed

Engineering Executive, бывший CTO Obama for America. Система из трёх документов для управления LLM-разработкой.

📋

Harper Reed

Engineering Executive · бывший CTO Obama for America 2012 · Технологический лидер

Spec-driven TDD Planning Conventional commits Atomic prompts

⚠️

Частая ошибка новичков: пропускают фазу Idea Honing и сразу переходят к Execution — дают CC размытое описание задачи без spec.md. Результат: CC начинает генерировать код, принимает произвольные архитектурные решения, и через 30 минут вы получаете реализацию которая решает не ту проблему. Harper тратит время на spec.md именно потому что это единственный момент когда ошибка стоит дёшево — до написания любого кода.

📋 Трёхшаговый workflow Harper Reed

Harper Reed — один из первых публичных евангелистов LLM-кодогенерации как рабочего процесса. Его статья на harper.blog описывает систему из трёх артефактов которые управляют всем циклом разработки. Ключевая идея: думать сначала, кодировать потом.

Idea Honing — в reasoning-модели

Используй сильную reasoning-модель (Opus/o3) для Socratic-диалога. Один вопрос за раз пока spec не станет кристально чётким. Итог: spec.md — детальное описание что строим, зачем, какие ограничения.

Planning — создание плана выполнения

Из spec.md генерируй prompt_plan.md — упорядоченный список промптов в правильной последовательности. Также todo.md с правилом «no orphaned code» — каждая строка кода должна быть частью конкретной feature.

Execution — в Claude Code

Открывай prompt_plan.md, выполняй по одному промпту, запускай тесты, отмечай выполненные. Каждый промпт — одна атомарная задача. Claude коммитит с conventional commit сообщением.

md prompt_plan.md — пример структуры

# Prompt Plan: Payment Subscriptions

## Prompt 1: Database schema
Create migration for subscriptions table with fields:
user_id (FK), plan_id, status, started_at, expires_at, cancelled_at
Add indexes on user_id and status.
Status: [ ]

## Prompt 2: Model
Create Subscription Eloquent model with:
- Relationships: belongsTo User, belongsTo Plan
- Scopes: active(), expired(), cancelled()
- Accessors: isActive, daysRemaining
Status: [ ]

## Prompt 3: Service layer
Create SubscriptionService with create(), cancel(), renew() methods.
All business logic here, not in controller.
Status: [ ]

## Prompt 4: Tests (write BEFORE implementation)
Write feature tests for all three service methods.
Tests must be RED before Prompt 3 implementation.
Status: [ ]

🤖 Практика: Execution промпт для Claude

md Стартовый промпт для execution-фазы

Открой @prompt_plan.md и найди первый промпт не отмеченный как выполненный.

Реализуй этот промпт следуя всем правилам из @CLAUDE.md и @spec.md.

После реализации:
1. Запусти тесты и покажи полный вывод
2. Если тесты зелёные — отметь промпт как выполненный ([x]) в prompt_plan.md
3. Сделай git commit с conventional commit сообщением (feat/fix/test/refactor)
4. Сообщи что готово и жди следующей инструкции

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

🤖 Практика: Robots LOVE TDD

Главная защита от галлюцинаций — тесты до кода

Harper считает TDD главным инструментом защиты от галлюцинаций при LLM-кодогенерации. Причина проста: Claude сам видит что тест красный → реализует → видит что зелёный. Невозможно «вспомнить» что тест прошёл — либо прошёл либо нет.

Без тестов Claude может написать код который выглядит правильным, уверенно заявить что всё работает — и ошибаться. С тестами у него есть объективный feedback loop который не обмануть.

Harper называет это: "Robots LOVE TDD". CC не чувствует усталость от написания тестов, не ищет сокращений, и охотно следует циклу red-green-refactor.

🚫 Практика: No Orphaned Code

Каждая строка кода должна иметь назначение

Harper ввёл правило: не должно быть «сиротского кода» — кода который написан «на будущее», «может пригодится», «вдруг понадобится». Каждая строка кода должна быть частью конкретной feature из todo.md.

Это особенно важно при LLM-кодогенерации: Claude склонен к over-engineering, добавляет абстракции которые «могут понадобиться». CLAUDE.md с правилом «no orphaned code» сдерживает эту склонность.

🗄 Практика: Conventional Commits

Claude коммитит в правильном формате — автоматически

Harper включает в CLAUDE.md требование использовать conventional commits формат: feat:, fix:, test:, refactor:, docs:. Claude следует этому без напоминаний — правило в файле инструкций.

Результат: история git становится читаемой и пригодной для автоматической генерации changelog. Особенно ценно при работе с несколькими параллельными Claude-сессиями.

bash Примеры conventional commits от Claude

# feat: новая функциональность
git commit -m "feat(subscription): add cancel() method with grace period"

# fix: исправление бага
git commit -m "fix(auth): correct token expiry check for refresh flow"

# test: добавление тестов
git commit -m "test(subscription): add edge cases for expired plan renewal"

# refactor: рефакторинг без изменения поведения
git commit -m "refactor(service): extract payment gateway to separate class"

⚡ Практика: Один промпт = одна атомарная задача

Атомарность промптов — залог предсказуемости

Harper строго соблюдает принцип: один промпт = одна чётко ограниченная задача. Не «создай подписочную систему», а «создай миграцию для таблицы subscriptions с такими-то полями и индексами». Не «напиши тесты», а «напиши тест для метода cancel() покрывающий случай активной и уже отменённой подписки».

Атомарные промпты дают предсказуемый результат, легко верифицируются, и в случае ошибки легко откатываются (один коммит → один revert).

💡

Тонкость для опытных: Harper использует разные модели на разных фазах намеренно. Фаза Idea Honing — Opus или сильная reasoning-модель (её глубина нужна для диалога и нахождения слабых мест в spec). Фаза Execution — Sonnet (быстрее, дешевле, отлично выполняет атомарные промпты). Переключение между моделями — не случайность, а осознанная оптимизация стоимости и качества для каждой фазы.

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

Документ управляет исполнением

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

🔗

Смотрите также: Правила CLAUDE.md — как зафиксировать no orphaned code. Паттерны экспертов — Spec Pipeline подробнее. Мульти-агентность — параллельное выполнение prompt_plan.

📝 Детальный пример spec.md

Вот как выглядит реальный spec.md который Harper создаёт в фазе Idea Honing перед написанием кода:

markdown spec.md — Система подписок

# Spec: Subscription System

## Цель
Реализовать систему платных подписок для SaaS-приложения.
Пользователи выбирают план → платят → получают доступ к функциям.

## Планы
- Free: базовые функции, без оплаты
- Pro: $29/мес, все функции
- Enterprise: договорная цена, неограниченные пользователи

## Пользовательский флоу
1. Пользователь выбирает план на странице /pricing
2. Вводит данные карты (Stripe Checkout)
3. Редирект на /dashboard с активированным планом
4. Email с подтверждением и датой следующего списания

## Технические ограничения
- Stripe для платежей (уже настроен в проекте)
- Webhook для обновления статуса при успешном/неудачном платеже
- Подписка в БД: user_id, plan_id, status, stripe_subscription_id
- Grace period: 3 дня после неудачного платежа до деактивации

## НЕ входит в scope
- Годовые подписки (только месячные в этом релизе)
- Промокоды
- Trial период

🔄 Цикл iteration в фазе Execution

Harper не просто отдаёт список промптов Claude и ждёт. Execution — это активный процесс управления прогрессом:

Открыть prompt_plan.md

Найти первый незавершённый промпт. Прочитать контекст. Убедиться что предыдущие промпты действительно выполнены (тесты зелёные, коммит сделан).

Выполнить промпт

Дать Claude чёткую задачу из prompt_plan.md. Если задача слишком большая — разбить на sub-промпты прямо здесь.

Верифицировать

Запустить тесты. Если TDD — тест был красным до реализации, должен стать зелёным. Проверить что нет orphaned code.

Коммит и отметка

Claude делает git commit с conventional commit сообщением. Harper отмечает промпт как [x] в prompt_plan.md. Переходит к следующему.

💬 FAQ: частые вопросы о системе Harper Reed

Что если spec изменился в процессе?

Обновить spec.md → пересмотреть prompt_plan.md → отметить затронутые промпты как невыполненные. Не игнорировать изменения — они аккумулируются в технический долг.

Сколько времени занимает фаза planning?

Harper тратит 20–40% общего времени проекта на planning. Это кажется много — но сокращает время execution в 2–3 раза за счёт отсутствия переделок и ясного направления.

Нужна ли spec.md для маленьких задач?

Для задач < 2 часов — нет. Для всего что займёт больше — да. Граница субъективна, но Harper предпочитает overspecify чем underspecify.