Разработка по спецификации: как работать с ИИ-агентами

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

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

Что такое разработка по спецификации?

Spec-driven development, или разработка по спецификации, при работе с ИИ-агентами — это подход, в котором проверенное описание желаемого поведения служит основой для планирования, постановки задач, реализации и проверки. Спецификация объясняет, что должно происходить и зачем. План — как это реализовать в существующем приложении. Задачи разбивают план на части, результат которых можно проверить.

Практики разработки на основе спецификаций существовали и до ИИ: в них спецификации использовали как исполняемые тесты, например в разработке через поведение — BDD. Эта традиция совместима с описанным процессом, но сама по себе спецификация в Markdown исполняемым тестом не становится. Документация Cucumber по BDD.

Практическое отличие в том, что агенты программирования могут обращаться к этим документам на всём протяжении реализации. GitHub Spec Kit, открытый набор инструментов для организации работы агента, выстраивает процесс вокруг выбранного агента. Kiro, среда разработки от AWS, встраивает работу со спецификациями в сам продукт. Ни один из инструментов не избавляет от необходимости решить, как функция должна работать для пользователя.

Документация проверена 13 октября 2026 года: названия команд, пути к файлам и возможности ниже взяты из актуальной документации GitHub, Kiro, Anthropic и OpenAI. Разбор функции — учебный пример, а не описание внедрения в рабочий продукт или эксперимента с измерением производительности.

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

Разработка по спецификации: пошаговый процесс

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

За решение о поведении отвечает основатель или владелец продукта. За соответствие технического решения системе — руководитель разработки. Агент может подготовить оба документа, но убедительный текст ещё не доказывает, что решения верны.

Инструменты spec-driven development: сколько структуры вам нужно?

Выбирайте инструмент по тому, где возникают трудности с координацией. GitHub Spec Kit подходит, если нужен воспроизводимый процесс в репозитории вокруг уже выбранного агента. Kiro — если удобнее работать с требованиями, техническим решением и выполнением задач прямо в среде разработки. Обычных файлов достаточно для первой функции или команды, которая уже умеет последовательно проверять свою работу.

GitHub Spec Kit: команды и файлы

GitHub Spec Kit предоставляет готовые инструкции, шаблоны и вспомогательные скрипты; саму работу выполняет выбранный агент программирования. В актуальном README прямо указана основная последовательность: сформулировать принципы проекта, описать функцию, подготовить план, создать задачи, реализовать их и проверить, что осталось незавершённым.

Согласно актуальному README, нужны Python 3.11 или новее, uv — инструмент установки пакетов Python — и поддерживаемый агент. В примере настройки используется GitHub Copilot, помощник GitHub для написания кода. Выполните в терминале:

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

Затем запустите агента программирования в этой директории. Вводите инструкции процесса в его чате и проверяйте результат каждой перед переходом к следующей. Это не команды оболочки.

Разница в написании существенна. В README используется стандартный синтаксис навыков Copilot: /speckit-specify. В подробном справочнике команд — форма с точкой: /speckit.specify. Интеграция через навыки в Codex использует $speckit-specify. Выбирайте синтаксис установленной интеграции: эти знаки не взаимозаменяемы. Справочник интеграций.

Названия и назначение команд соответствуют справочнику GitHub по Agentic SDD. Clarify, checklist и analyze — дополнительные этапы проверки качества. Конституция задаёт постоянные правила проекта; переписывать её под каждую небольшую функцию не нужно.

В примере с экспортом инструкция specify должна описывать, кто может выгружать данные, какие записи попадают в выборку, что содержит файл и как обрабатываются ошибки. Информацию о текущем стеке и ограничениях репозитория передайте на этапе планирования. Явно запросите приёмочные тесты: в документации команды tasks их генерация предусмотрена по запросу, поэтому наличие сгенерированного списка задач не доказывает, что нужные тесты в него вошли.

Проверять нужно следующие файлы:

• .specify/memory/constitution.md: принципы проекта. Шаблон конституции.
• specs/<feature-directory>/spec.md: поведение функции. Директории функций обычно находятся в specs/; имя директории генерируется или задаётся в настройках. Шаблон спецификации.
• plan.md и tasks.md в директории функции: техническое решение и разбивка работы на задачи. На этапе планирования также создаются research.md, data-model.md и quickstart.md, а для соответствующих внешних интерфейсов — contracts/. Шаблон плана, справочник задач.

После реализации converge сравнивает кодовую базу со спецификацией, планом и задачами. Если обнаружены пробелы, команда дописывает работу в tasks.md, но сама код не исправляет. Выполните добавленные задачи и повторите проверку. Результат «Converged» полезен при ревью, но не заменяет тесты и ваше одобрение.

Для существующего приложения руководство GitHub по внедрению предлагает сначала сохранить исходное состояние, затем выполнить инициализацию на месте. Команда — specify init --here --force --integration <key>, где <key> нужно заменить ключом интеграции из документации, например claude или codex. Руководство предупреждает: --force может заменить конфликтующие файлы, которыми управляет инструмент. Просмотрите получившийся diff. Восстанавливать спецификации всего приложения, прежде чем описывать следующее изменение, не требуется.

Ограничение: Spec Kit способен обнаружить противоречия между документами и при этом пропустить ошибочное бизнес-правило, если оно везде описано одинаково. Затраты на поддержку дополнительных файлов оправданы, когда одна договорённость нужна нескольким людям или сессиям.

Разработка по спецификации в Kiro: specs, steering и hooks

Kiro разделяет замысел функции, постоянные указания для проекта и автоматические действия. Используйте specs для конкретной функции, steering — для общих соглашений репозитория, hooks — для повторяемых проверок.

В IDE, редакторе кода Kiro, нажмите + в разделе Specs или выберите Spec в чате. Выберите Feature, затем Requirements-First. Проверьте требования, прежде чем принимать техническое решение и разбивку на задачи. В созданной директории функции будут файлы .kiro/specs/<feature-name>/requirements.md, design.md и tasks.md. После проверки запускайте задачи через предназначенный для этого интерфейс. Документация Kiro по спецификациям.

Kiro использует EARS — Easy Approach to Requirements Syntax — для записи условия и ожидаемого поведения системы. В нашем примере: «Когда участник запрашивает экспорт, система должна отклонить запрос и не выдавать файл экспорта». Это достаточно конкретная формулировка, чтобы превратить её в тест. Спецификации функций.

В Kiro также есть Design-First и Quick Spec. Design-First начинает с технического решения; Quick Spec создаёт документы без промежуточных этапов согласования. Если агент постоянно неверно понимает замысел основателя, стоит выбрать Requirements-First и пользоваться проверками между этапами. Убрав их, вы уберёте именно ту часть процесса, которая решает проблему.

Steering хранит постоянный контекст в Markdown-файлах внутри .kiro/steering/. Основные файлы — product.md, tech.md и structure.md: они описывают продукт, стек и организацию репозитория. Команда Generate Steering Docs в IDE создаёт этот начальный контекст. Сверьте его с репозиторием. Правило «использовать существующую политику авторизации участников» стоит записать здесь, если оно действует для разных функций; правило «экспорт доступен только владельцам» — в спецификации экспорта. Документация по steering.

Hooks запускают команды оболочки или промпты агента при наступлении события. В текущей версии файлы хуков проекта находятся по пути .kiro/hooks/<id>.json; PostFileSave — один из документированных триггеров. Узко настроенный хук может запускать существующие тесты экспорта при изменении соответствующего исходного кода. Сохраните те же проверки в системе непрерывной интеграции, которая автоматически проверяет предлагаемые изменения кода: локальный хук не должен быть единственным местом их запуска. По актуальной таблице возможностей Kiro хуки поддерживаются в IDE и CLI, но не в Web и Mobile. Документация по hooks.

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

Разработка по спецификации с Claude Code

Claude Code, агент программирования от Anthropic, может работать по этому процессу со спецификацией функции и режимом Plan Mode. Чтобы попробовать метод, устанавливать отдельный фреймворк для спецификаций не нужно.

Создайте specs/workspace-export/spec.md самостоятельно или проверьте черновик агента. Затем запустите сессию в терминале в режиме планирования:

claude --permission-mode plan

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

Plan Mode предназначен для изучения задачи и подготовки подхода к её решению. Anthropic описывает исключение для интерактивных сессий терминала, в которых доступен обход разрешений: блокировки редактирования в режиме планирования не применяются. Если нужно сохранить обязательный переход через одобрение, запускайте сессию без включённого обхода. Документация по режимам разрешений.

После проверки предложения сохраните согласованный подход в specs/workspace-export/plan.md, а его чек-лист — в tasks.md, затем разрешите реализацию. Эти пути — соглашение, предложенное в статье, а не файлы, которые Plan Mode обещает создавать автоматически. Управление режимом и переход к одобрению разобраны в руководстве по Claude Code Plan Mode.

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

Ограничение: план, оставшийся только в переписке, легко потерять или нарушить. Сохранение в файл помогает лишь тогда, когда при реализации и ревью к нему явно обращаются.

Codex: режим планирования с тем же файлом спецификации

Codex, агент программирования от OpenAI, поддерживает такой же простой способ передачи задачи. В чате CLI, когда агент не выполняет работу, команда /plan запускает планирование; сам запрос можно дописать в той же строке. Официальная документация команд.

Подойдёт такой запрос: «Прочитай specs/workspace-export/spec.md. Изучи существующую политику прав участников, запрос списка задач и тесты. Предложи минимальный план реализации, который выполнит все требования. До начала реализации укажи решения, которые ещё не приняты».

Проверьте план, сохраните согласованные файлы, затем попросите Codex выполнить задачи и подготовить отчёт о готовности, связывающий требования с тестами. Для постоянных инструкций репозитория используйте AGENTS.md; команда /init может создать его основу. Настройка исходного окружения описана в руководстве по Codex CLI.

OpenAI также описывает хранение спецификаций, планов и хода выполнения в Markdown для длительных задач. Польза в том, что следующая сессия может снова открыть согласованные документы. Ограничение: Plan Mode сам по себе не поддерживает отдельную спецификацию функции в актуальном состоянии. Включите её обновление в проверку изменений. Процесс из документации OpenAI.

Пример разработки по спецификации: CSV-экспорт рабочего пространства

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

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

Спецификация на одну страницу

Сохраните её в spec.md этой функции или перенесите то же описание поведения в requirements.md в Kiro:

Обратите внимание на решение, скрытое в R2: «все подходящие результаты» и «видимая страница» — разные вещи. Если определиться до реализации, это сразу изменит запрос и план тестирования. Если после демонстрации — может понадобиться переделывать и то и другое.

R4 намеренно указывает на решение, которому нужны конкретные примеры. Прежде чем одобрить спецификацию, определите, как обрабатывать значения, похожие на формулы электронных таблиц, и зафиксируйте примеры. Формулировка «сделать экспорт безопасным» оставила бы выбор этих правил агенту.

План: встроить решение в существующее приложение

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

Используйте принятый в репозитории сериализатор CSV, если он есть. Укажите заголовки содержимого и скачивания, правила безопасной обработки полей, поведение при ошибках и тесты. Добавьте кнопку с существующими в приложении состояниями загрузки и ошибки.

В плане также нужно сопоставить ожидаемый размер результата с действующими ограничениями приложения на запросы и память. Если выгрузка всех результатов в них не укладывается, верните вопрос владельцу функции. Согласуйте ограниченную выгрузку или отдельно определите объём работ по фоновой обработке. Агент не должен самовольно вводить максимальный размер или добавлять систему фоновых задач вопреки R6.

Задачи: сделать каждое изменение проверяемым

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

1. Зафиксируйте существующее поведение списка задач и общие правила фильтрации в регрессионных проверках.
2. Добавьте тесты авторизации запросов для владельца, участника, бывшего владельца и другого рабочего пространства.
3. Реализуйте запрос с нужными границами выборки и CSV-ответ по согласованным правилам обработки полей.
4. Добавьте элемент управления экспортом, состояние загрузки и отображение ошибок.
5. Завершите приёмочные проверки и просмотрите diff на предмет изменений за пределами функции.

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

В приложении на TypeScript проверяемое изменение кода могло бы включать server/exports/tasks.ts для авторизации, фильтрации и ответа; ui/tasks/ExportButton.tsx для взаимодействия с пользователем; tests/task-export.test.ts для приёмочных сценариев. Это примеры путей, а не обязательные соглашения фреймворка. Новый обработчик очереди или миграция базы данных означали бы изменение объёма работ, которое нужно согласовать до слияния.

От критериев приёмки к решению о слиянии

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

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

Допустим, на ревью выяснилось, что эндпоинт читает только текущую страницу. Если владельцу по-прежнему нужны все подходящие результаты, сохраните R2, исправьте запрос и добавьте тест с совпадениями за пределами этой страницы. Если владелец меняет границы задачи, до одобрения обновите вместе R2, план и тесты.

Сливайте изменения, когда результаты проверок соответствуют договорённости: включите в один пул-реквест проверенную спецификацию, окончательный план, отметки о выполнении задач, реализацию и тесты. Там же зафиксируйте все согласованные изменения объёма работ. После слияния либо поддерживайте спецификацию как актуальный контракт, либо пометьте её как историческую запись о функции. Устаревшая спецификация, которая выглядит действующей, создаёт почву для следующей путаницы.

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

Сколько это стоит и когда окупается?

Цена метода — время на проверку и поддержку документов плюс работа агента по их подготовке и реализации. Spec Kit имеет открытый исходный код, но подключённый агент программирования по-прежнему используется на собственных условиях. Обычный Markdown не требует отдельной подписки на инструмент спецификаций, но использование модели от этого не становится бесплатным.

В стандартных коммерческих тарифах Kiro указаны Free за $0 в месяц с 50 кредитами и Pro за $20 на пользователя в месяц с 1,000 кредитов, без учёта применимых налогов. Значит, четыре подписки Pro стоят 4 × $20 = $80 в месяц, без дополнительных кредитов и налогов. Это расчёт стоимости мест, а не прогноз того, сколько функций вы сможете выпустить. Страница тарифов Kiro.

Дополнительные платные кредиты стоят $0.04 за кредит. По данным Kiro, уточнение спецификации, выполнение задач и запуск агентских хуков расходуют кредиты, а сложная задача из спецификации может потребовать больше одного кредита. Без наблюдения за реальной нагрузкой обоснованно пересчитать «кредиты» в «готовые функции» нельзя. Описание кредитов Kiro.

Экономический критерий прост: дополнительные затраты на описание, проверку и поддержку функции должны быть меньше затрат на переделки, которых удалось избежать. Измеряйте их в своём процессе. Если метод добавляет документы, но те же решения по-прежнему откладываются до ревью кода, накладные расходы не оправданы.

Что в этом подходе переоценено и когда он избыточен?

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

Полезно различать заявленное намерение и поведение, обеспеченное системой. Требование говорит, что участникам запрещён экспорт; серверная проверка и её тесты помогают обеспечить это правило. Чек-лист требований проверяет описание. Он не запускает приложение. Приравнивание одного к другому создаёт ложную уверенность.

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

Начинайте сейчас, если агент регулярно упускает права доступа, пограничные случаи, интеграции или критерии приёмки. Используйте этот процесс для функции, в которой неоднозначность затрагивает несколько компонентов или участников ревью.

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

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

Ориентир — не число строк кода, а количество существенных предположений, которые иначе придётся сделать агенту.

Первая неделя разработки по спецификации

Выберите небольшую функцию, которая уже есть в бэклоге. Пусть её владелец согласует одностраничную спецификацию поведения, включая исключения из объёма работ и сценарии ошибок. Используйте текущего агента в режиме планирования или соответствующий процесс в Spec Kit либо Kiro, чтобы получить план с опорой на существующий репозиторий.

Разберите вопросы до реализации. Попросите список задач, связанных с требованиями. На этапе пул-реквеста сверяйте подтверждения с той же договорённостью и фиксируйте изменившиеся решения. Усложняйте процесс лишь настолько, насколько этого требует неоднозначность задачи.

Подпишитесь на рассылку, чтобы получать практические материалы о разработке и работе с ИИ.