Спецификации функций Claude Code из кода: простой рабочий процесс

Зачем нужны спецификации, которые соответствуют коду

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

Со временем код становится единственным актуальным источником правды. Документация устаревает, тикеты закрываются, быстрые фиксы накапливаются. У маршрута появляется новое правило валидации. В UI переключатель меняет значение по умолчанию. Хендлер начинает возвращать другие ошибки. Никто не обновляет спецификацию, потому что это кажется необязательным, а каждое изменение кажется слишком мелким, чтобы его документировать.

Это создаёт предсказуемые проблемы. Команды выпускают изменения, которые ломают редкие сценарии, о существовании которых они не знали. QA тестирует счастливый путь и пропускает правила, спрятанные в хендлерах. Новые члены команды копируют поведение из UI, не понимая реальных ограничений. Заинтересованные лица спорят мнениями вместо того, чтобы ссылаться на согласованное поведение.

Хороший результат — это не идеальный документ. Это общая ясность. Каждый должен уметь ответить: "Что произойдёт, если я сделаю X?" и "Какие гарантии даёт система?" без домыслов. Меньше сюрпризов, короче ревью и меньше моментов «Стоп, но оно же уже это делает», потому что команда смотрит на одну и ту же правду.

Когда спецификация соответствует коду, планировать изменения становится безопасно. Видно, что стабильно, что случайно, и чего не хватает до релиза.

Что такое живая спецификация и список разрывов

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

Когда говорят о спецификациях фич, написанных из кода (например, с использованием Claude Code), цель проста: прочитать реальное поведение из маршрутов, хендлеров и экранов, а затем записать его простым языком.

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

• Поведение, заметное пользователю (что происходит при клике, отправке, входе)
• Правила и ограничения (обязательные поля, лимиты, вычисления)
• Крайние случаи (пустые состояния, ошибки, повторные попытки, таймауты)
• Разрешения (кто может просматривать, создавать, редактировать, удалять)
• Важные результаты (отправленные письма, созданные записи, изменения статусов)

То, что не следует покрывать — как организован код. Если вы начинаете называть файлы и планы по рефакторингу, вы уходите в детали реализации. Избегайте:

• Имен функций и классов, деревьев компонентов
• Дебатов об архитектуре и планов по переписке

Список разрывов — это отдельное небольшое перечисление несоответствий и неизвестностей, которые вы обнаружили при написании спецификации.

• Баг: код нарушает текущее поведение или согласованное правило.
• Запрос фичи: хотите новое поведение.
• Разрыв: вы не можете понять, каким должно быть правильное поведение, или поведение неконсистентно на разных экранах/ролях.

Пример: один маршрут отклоняет файлы больше 10 МБ, а UI говорит 25 МБ. Это gap, пока команда не решит, какое правило истинно, и не обновит либо код, либо спецификацию.

Выберите масштаб и простой формат спецификации

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

Выберите точку входа в зависимости от того, где живёт правда:

• Если нужны реальные правила — начните с маршрутов и хендлеров.
• Если важен реальный опыт — начните с точек входа UI.
• Если фича запутана — начните с верхнеуровневой страницы/контроллера и двигайтесь наружу.

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

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

Шаблон спецификации (повторять для каждого пользовательского потока)

• Purpose: что пытается достичь пользователь
• Entry points: где начинается поток (URL, меню, кнопка)
• Preconditions: авторизация, роли, требуемые данные
• Main flow: 5–10 шагов простым языком
• Data and side effects: созданные/обновлённые записи, письма, логи
• Errors and edge cases: что происходит, когда всё идёт не так
• Open questions: неясное поведение, которое нужно подтвердить

Повторяйте эту структуру, и ваши спецификации останутся читаемыми, сопоставимыми и простыми в обновлении.

Извлекаем поведение из маршрутов и хендлеров

Начните с серверных точек входа. Маршруты и хендлеры показывают «что приложение делает» в конкретных терминах: кто может вызывать, что нужно отправить, что возвращают и что меняется в системе.

Перечислите маршруты в области и сопоставьте каждый с пользовательским намерением. Не пишите «POST /api/orders.» Пишите «Оформить заказ» или «Сохранить черновик». Если вы не можете назвать намерение простыми словами — это уже gap спецификации.

Читая каждый хендлер, фиксируйте входные данные и правила валидации как требования для пользователя. Включайте обязательные поля, допустимые форматы и правила, которые приводят к реальным ошибкам. Например: "Email должен быть валидным", "Количество должно быть не менее 1", "Дата начала не может быть в прошлом."

Пишите проверки авторизации и ролей так же. Вместо "middleware: requireAdmin" документируйте: "Только админы могут отменять любой заказ. Обычные пользователи могут отменять только свои заказы в течение 10 минут." Если код проверяет принадлежность, feature flags или границы арендатора, включите и это.

Затем отметьте выводы и исходы. Что возвращает успех (созданный ID, обновлённый объект)? Какие типичные ошибки (401 не авторизован, 403 нет доступа, 404 не найдено, 409 конфликт, 422 ошибка валидации)?

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

Извлекаем поведение из компонентов и UI-потоков

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

Начните с поисков точек входа в фичу: страницу, обёртку layout и несколько «решающих» компонентов, которые контролируют фетчинг, права доступа и навигацию. Именно там обычно живёт реальное поведение.

Читая компоненты, фиксируйте правила, которые чувствует пользователь: когда кнопки отключены, обязательные шаги, условные поля, состояния загрузки и как отображаются ошибки (инлайн-подполе против тоста, автоповтор, кнопки «повторить попытку»). Также отметьте поведение состояния и кэширования: сначала показывается устаревшая информация, оптимистичные обновления или отметки "последнее сохранение".

Ищите скрытые потоки, которые тихо меняют то, что видит пользователь. Ищите feature flags, экспериментальные корзины и гейты только для админов. Зафиксируйте тихие редиректы, например отправку неавторизованных пользователей на страницу входа или отправку пользователей без доступа на страницу апгрейда.

Конкретный пример: на экране "Сменить email" задокументируйте, что кнопка Сохранить остаётся отключённой, пока email не пройдет валидацию, отображается спиннер во время запроса, успех вызывает баннер подтверждения, а ошибки валидации от бэкенда рендерятся под полем ввода. Если код показывает флаг newEmailFlow, отметьте оба варианта и в чём их различие.

Опишите каждый UI-поток короткими шагами (что делает пользователь, что UI делает в ответ) и держите условия и ошибки рядом со шагом, на который они влияют. Это делает спецификацию читаемой и упрощает выявление разрывов.

Превратите наблюдения в читаемые спецификации фич

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

Практичный подход — одна user story на маршрут или экран. Держите её маленькой и конкретной. Например: "Как вошедший пользователь, я могу сбросить пароль, чтобы восстановить доступ." Если код показывает разное поведение по ролям (админ vs пользователь), разделите это на отдельные истории, а не прячьте в сносках.

Пишите acceptance criteria, которые отражают реальные пути кода, а не идеальный продукт. Если хендлер возвращает 401 при отсутствии токена, это критерий. Если UI блокирует отправку до валидности поля — это критерий.

Включайте правила данных простым языком, особенно те, которые вызывают сюрпризы: лимиты, порядок, уникальность, обязательные поля. "Имена пользователей должны быть уникальными (проверяется при сохранении)" понятнее, чем "уникальный индекс".

Крайние случаи часто отличают приятный документ от полезного. Выделяйте пустые состояния, null-значения, повторы, таймауты и то, что видит пользователь при ошибке API.

Если встречаете неизвестные вещи, помечайте их, а не догадывайтесь:\n

• Unknown: какое сообщение показывать, если email не найден?\n- Unknown: разрешать ли 0 элементов или требовать как минимум 1?\n- Unknown: должна ли эта ошибка быть видна пользователю или только логироваться?\n Эти метки превращаются в быстрые вопросы к команде вместо молчаливых предположений.

Создайте список разрывов, не превращая его в бэклог

Список разрывов — не вторая Jira. Это короткий, основанный на доказательствах список мест, где код и ожидаемое поведение не совпадают или где никто не может чётко объяснить, что правильно. Хорошо сделанный, он служит инструментом для согласования, а не предметом планировочной ссоры.

Строго определите, что считается разрывом:\n

• Неясное поведение: приложение делает что-то, но правило не зафиксировано нигде.\n- Несоответствие: два места ведут себя по-разному в одной и той же ситуации.\n- Отсутствующее правило: существует крайний случай, но в коде или документах нет решения.

Когда вы записываете разрыв, включайте три части, чтобы он оставался привязанным к фактам:\n

• Тип: баг (код, похоже, неправильный) или отсутствие решения (неясный intent)\n- Влияние: путаница пользователя, риск безопасности, потеря данных или незначительное\n- Доказательство: где вы это увидели и что именно наблюдали (route/handler/component)

Доказательства не дают списку превратиться в набор мнений. Пример: "POST /checkout/apply-coupon принимает просроченные купоны, но CouponBanner.tsx блокирует их в UI. Влияние: доходы и путаница пользователя. Тип: баг или отсутствие решения (подтвердить желаемое правило)."

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

Не добавляйте даты и планирование в сам список разрывов. Если нужна ответственность, укажите, кто должен принять решение (product) или кто может проверить поведение (engineering), а планирование перенесите в основной бэклог.

Пример: документирование реальной фичи из кода

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

Начните с бэкенд-маршрутов. Часто правила проявляются сначала там. Вы можете найти маршруты вроде POST /checkout/apply-promo, GET /checkout/shipping-options и POST /checkout/confirm.

Из хендлеров запишите поведение простыми словами:\n

• Промокоды валидируются на сервере (истёкшие, лимит по использованию, права клиента).\n- Итого пересчитывается после применения промо, но только после повторной проверки инвентаря.\n- Варианты доставки зависят от доставки, веса и от того, помечен ли какой-либо товар как restricted.\n- Подтверждение падает, если запас по позиции изменился с момента загрузки корзины.\n- Налог считается после выбора доставки (не при применении промо).

Затем проверьте UI-компоненты. PromoCodeInput может показывать обновлённые суммы только после успешного ответа, а ошибки рендерятся под полем ввода. ShippingOptions может автоматически выбирать самый дешёвый вариант при загрузке и триггерить обновление разбивки цен при смене пользователем.

Теперь у вас есть читаемая спецификация и небольшой список разрывов. Например: сообщения об ошибках различаются между промо-маршрутом и UI ("Invalid code" vs "Not eligible"), и никто не знает точное правило округления налогов (по строке или по сумме заказа).

При планировании команда сначала соглашается с реальностью, потом решает, что менять. Вместо споров вы просматриваете задокументированное поведение, выбираете одно несоответствие для исправления и оставляете остальное помеченным как "текущее поведение" до следующего ревью.

Верифицируйте спецификацию с командой и поддерживайте её актуальной

Спецификация помогает только если команда согласна, что она отражает реальность. Проведите короткий прогон с одним инженером и одним продуктовым. Держите его в пределах: 20–30 минут, сосредоточившись на том, что пользователь может сделать и как система отвечает.

Во время проверки превращайте утверждения в вопросы да/нет. "Когда пользователь попадает на этот маршрут, мы всегда возвращаем 403 без сессии?" "Это пустое состояние — намеренно?" Так вы отделяете намеренное поведение от случайных изменений, которые накопились со временем.

Согласуйте словарь до редактирования. Используйте слова, которые видны в UI (названия кнопок, заголовки страниц, сообщения). Добавляйте внутренние имена только когда они помогают инженерам найти код (имена маршрутов, компонентов). Это предотвращает несоответствия вроде того, что продукт говорит "Workspace", а спецификация — "Org".

Чтобы держать спецификацию актуальной, сделайте явными владение и ритм обновлений:

• Владелец спецификации: один человек, который мержит изменения (часто владелец фичи или tech lead)\n- Триггер обновления: при мёрже PR, меняющем поведение, или при каждом релизе\n- Быстрая проверка: добавьте чекбокс "spec updated?" в шаблон PR\n- Хранение: держите рядом с кодом, чтобы оно обновлялось вместе с ним

Если вы используете инструмент вроде Koder.ai, снапшоты и откаты помогут сравнить "до" и "после" при обновлении спецификации, особенно после больших рефакторингов.

Распространённые ошибки и ловушки

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

Ещё одна ловушка — копирование структуры кода в документ. Спецификация, читающаяся как "Controller -> Service -> Repository", не является спецификацией, это карта папок. Пишите на языке, понятном пользователю: что запускает действие, что видит пользователь, что сохраняется и как выглядят ошибки.

Права доступа и роли часто игнорируют до финала, а потом всё ломается. Добавляйте правила доступа с самого начала, даже если они запутаны. Отмечайте, какие роли могут просматривать, создавать, редактировать, удалять, экспортировать или утверждать, и где правило применяется (только UI, только API или и там, и там).

Не пропускайте не-хэппи-пати. Реальное поведение скрыто в повторах, частичных сбоях и правилах по времени: истечения, кулдауны, планировщики или лимиты типа "только раз в день". Рассматривайте их как поведение первого порядка.

Быстрый способ выявить разрывы — проверить:\n

• Ошибки валидации и точные сообщения, которые видит пользователь\n- Обработка дубль-отправок (идемпотентность)\n- Фоновые задачи (очереди, cron) и что происходит при их падении\n- Проблемы конкурентности (два пользователя меняют одну запись)\n- Поведение, зависящее от времени (таймауты, истечения, лимиты скорости)

Наконец, двигайте список разрывов вперёд. Каждому разрыву присвоьте статус из: "unknown/needs decision", "bug/fix" или "missing feature/plan". Если список не помечается, он застывает и спецификация перестаёт быть "живой".

Быстрый чек перед тем, как поделиться спецификацией

Сделайте быструю проверку на ясность, покрытие и пригодность к действию. Тот, кто не писал спецификацию, должен понять, что фича делает сегодня и что ещё неясно.

Ясность и общее понимание

Прочитайте спецификацию как новый человек в команде в первый день. Если он может пересказать фичу за минуту — вы близки к цели. Если он всё время спрашивает: "Откуда начинается поток?" или "Каков счастливый путь?" — усилите начало.

Проверьте:\n

• Одностраничный тест: в начале сказана цель пользователя, откуда начинается поток и где он заканчивается.\n- Роли и доступ: ключевые роли и что каждая может и не может делать.\n- Результаты: как выглядит успех и что видит пользователь при провале (сообщения, редиректы, повторы).\n- Края и лимиты: ограничения по размерам, лимиты скорости, таймауты, правила валидации и что происходит при отсутствии данных.\n- Язык: сначала термины, которые видит пользователь; специфический жаргон объясните однократно.

Полезные gaps, а не шум

Каждый gap должен быть конкретным и проверяемым. Вместо общего "неясна обработка ошибок" напишите: "Если платёжный провайдер возвращает 402, UI показывает общий тост; подтвердить желаемое сообщение и стратегию повтора." Добавьте одно следующее действие (спросить продукт, добавить тест, посмотреть логи) и укажите, кто должен ответить.

Следующие шаги на этой неделе

Выберите одну область фич и ограничьте время до 60 минут. Возьмите что-то небольшое, но реальное (логин, оформление заказа, поиск, админ-экран). Напишите одно предложение масштаба: что включено и что исключено.

Пройдите workflow один раз целиком: пробегитесь по ключевым маршрутам/хендлерам, проследите основной UI-поток и выпишите наблюдаемое поведение (входы, выходы, валидация, ошибки). Если застряли — зафиксируйте вопрос как gap и идите дальше.

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

Держите gaps отдельно от бэклога. Группируйте их в "неизвестное поведение", "несогласованное поведение" и "недостающие тесты" и кратко пересматривайте каждую неделю, чтобы решить, что важно сейчас.

Если набрасывание и итерация идут медленно, чат-базированный билдeр вроде Koder.ai может помочь получить первоначальную версию быстро. Опишите фичу, вставьте ключевые фрагменты или имена маршрутов, уточняйте формулировки в разговоре и экспортируйте исходники при необходимости. Смысл — скорость и общая ясность, а не громоздкий процесс.