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

Через три месяца у нас сложилось более чёткое представление о том, когда дополнительная структура помогала, а когда мешала.

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

Проблема → Исследование → Спецификация → Проверка → Реализация → Верификация

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

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

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

Тем не менее агенты брались за работу, которая длилась дольше одной сессии, и зачастую одного промпта было недостаточно, чтобы сохранить цель проекта или его обоснование. Это привело нас к созданию /spec-driven — инструмента для управления рабочим процессом, в центре которого находится спецификация. Спецификация сохраняла направление проекта для следующей сессии. Скрипты предоставляли контекст и выполняли проверки. Когда в ходе выполнения выявлялось отсутствие правила, проверки или элемента контекста, мы могли добавить их в рабочий процесс, чтобы последующим агентам не приходилось снова сталкиваться с тем же пробелом.

До сих пор существует немало разногласий по поводу того, стоит ли использовать дополнительную структуру SDD. Microsoft и AWS продвигают SDD, в то время как Thoughtworks характеризует его как формирующийся и спорный подход, а специалисты-практики сообщают о неоднозначном опыте. Критики предупреждают, что SDD может привести к созданию большего количества Markdown, чем инженеры в состоянии поддерживать, превратить подробную спецификацию в код, написанный прозой, или оставить еще одно описание системы, которое будет отличаться от кода.[1][2][3]

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

Почему мы создали /spec-driven

Некоторые инженеры Asana уже пробовали GitHub Spec Kit и OpenSpec, но ни один из этих инструментов не стал частью их обычного рабочего процесса. Нам была нужна версия, которую мы могли бы адаптировать по мере накопления опыта и интегрировать в процесс разработки Asana.

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

Перед реализацией /spec-driven воспроизводил своё понимание проблемы и поднимал вопросы, которые могли изменить план. Это давало инженеру возможность скорректировать направление, прежде чем придётся переписывать код.

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

Рабочий процесс включал в себя несколько команд. Инженеры использовали команду /spec-driven spec, чтобы проработать открытые вопросы и составить спецификацию и план реализации. После ознакомления с планом они использовали команду /spec-driven ship, чтобы реализовать его, проверить результат и подготовить работу к рассмотрению. Конечный автомат отслеживал проект по мере выполнения этих команд, поэтому на последующих сеансах было известно, что произошло и что будет дальше.

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

Это как GPS для работы: в любой момент понятно, каким будет следующий шаг и где принимаются реальные решения, поэтому трудно зайти в тупик.”

Инженеры Asana использовали /spec-driven как в режиме «спецификация в первую очередь», так и в режиме «спецификация как основа». В первом случае они использовали спецификацию, чтобы выбрать направление, а затем перестали её обновлять. При подходе, ориентированном на спецификацию, они поддерживали её актуальность по мере изменения работы. Инженеры также составляли отдельные спецификации для отдельных этапов более масштабной работы, чтобы один человек мог использовать рабочий процесс, не требуя от всей команды его внедрения.

Когда использование /spec-driven оправдывает дополнительные усилия

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

Я только что завершил довольно крупную инициативу с использованием подхода, основанного на спецификациях, и думаю, что это действительно мне помогло! Я работал над планом около двух дней, а затем выполнил все инженерные работы и объединил их за три дня.”

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

Инженеры также использовали /spec-driven для координации больших объёмов работы, выполняемой агентами. В консоли администратора Asana, где ИТ-команды компаний-клиентов управляют настройками безопасности, доступа, интеграций и общего доступа для всей организации, инженеры использовали её для переноса 66 настроек в общие фреймворки. Для переноса этих настроек потребовалось около 150 миграций в нескольких фреймворках консоли администратора. Каждая миграция становилась тикетом Asana для облачного агента, и инженеры запускали их параллельными пакетами, обновляя оставшиеся тикеты на основе более ранних результатов.

Команда, отвечавшая за эту работу, сообщила, что 91 % переносов не потребовали доработки после проверки и что в целом работа была завершена более чем на месяц раньше первоначального плана.

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

Подход /spec-driven также помог в быстром создании прототипов. Инженеры могли быстро ответить на достаточное количество открытых вопросов по продукту, чтобы создать рабочий комплексный процесс. Менеджеры по продукту и дизайнеры могли опробовать прототип до того, как инженеры вложат усилия в доработку продукта для запуска. Если инженеры решали оставить код, обычно перед его объединением требовалась существенная доработка. К тому времени опытный образец уже показывал, стоит ли реализовывать идею.

Что показали первые результаты

Мы призвали всех хотя бы раз попробовать /spec-driven, но не требовали дальнейшего использования. Примерно половина инженеров попробовала его. В последний месяц еженедельно инструментом пользовались от 30 до 50 инженеров. Среди встроенных и разработанных Asana навыков агентов, которыми инженеры пользовались напрямую, /spec-driven занял третье место. Факт постоянного использования был обнадеживающим, но он не давал нам представления о том, как /spec-driven влиял на результаты работы.

Известно, что скорость работы инженеров измерить непросто. Заявки на внесение изменений и добавления в рабочий код — несовершенные показатели продуктивности, но мы считаем, что они часто являются полезными ориентирами. Для сравнения скорости работы мы проанализировали данные семи инженеров и 524 объединённых запроса на внесение изменений за четыре месяца. Мы сравнили работу до и после первого явного использования каждым инженером команды /spec-driven и исключили спецификации, планы и другие артефакты рабочего процесса. Для сравнения отмен мы классифицировали заявку на внесение изменений как основанную на спецификациях (/spec-driven), если она изменяла файлы проекта рабочего процесса.

Количество заявок на внесение изменений в неделю увеличилось на 38%, а количество добавлений в реализационный код — в 2,66 раза. На результат по добавлению кода повлиял один короткий период с необычно большим объёмом работы. Даже без учёта этого периода количество добавлений всё равно было на 66 % больше. Показатель явных откатов также был немного ниже: 1,2% для работы, основанной на спецификациях (/spec-driven), по сравнению с 1,66% для других заявок на внесение изменений.

Больший объем кода не обязательно является хорошим результатом. Агент может создать объемную реализацию, когда достаточно было бы менее объемной, поэтому увеличение количества добавлений кода могло отражать неоправданно масштабные решения, а не большее количество завершенной работы. Обычная проверка дала нам возможность выявить этот вид ошибок. Мы полагались на то, что рецензенты будут отмечать реализации, которые были больше или сложнее, чем того требовала задача, и эти изменения всё равно проходили. Это дало нам некоторую уверенность в том, что не все увеличение было обусловлено чрезмерно масштабными реализациями.

Эти сравнения не контролировались, и мы не могли отделить влияние тегов /spec-driven от состава проектов или более масштабных улучшений в инструментарии агентов. Даже с учётом этих ограничений результаты нас обнадежили.

Над чем ещё нужно поработать

Проверка документов может стать узким местом

Создание спецификации занимало от 30 минут до нескольких дней в зависимости от того, насколько хорошо инженер был знаком с данной областью, а также от сложности проекта и связанных с ним рисков. Инженеры могли использовать /spec-driven, чтобы агент быстро подготовил черновик спецификации, но на её проверку всё равно уходило время.

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

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

В одной команде, занимающейся инфраструктурой, проверка спецификаций стала новым препятствием перед внедрением.

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

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

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

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

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

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

Внедрение циклов обратной связи в систему

Иногда решением становился не ещё один документ, а изменение системы, в которой работает агент. Одним из примеров была ошибка в том, как /spec-driven считывал Markdown: заголовки и флажки внутри примеров могли быть ошибочно приняты за реальные важные этапы или незавершенные задачи. Зафиксировав ошибку, мы просмотрели остальную часть /spec-driven и обнаружили несколько команд с собственным небольшим парсером Markdown и той же «слепой зоной». Мы заменили их одним общим парсером, добавили регрессионные тесты и проверку архитектуры, а затем внедрили исправление в среду. OpenAI описывает схожий подход как «инженерную разработку инструментария»: размещать важную информацию там, где агенты могут её найти, обеспечивать возможность применения правил и использовать сбои для улучшения среды вокруг агента.

Другие выводы не могли быть преобразованы в тест или правило архитектуры. Мы обобщили повторяющиеся ошибки и составили на их основе рекомендации. Поскольку /spec-driven направлял пользователей по предсказуемому рабочему процессу, мы могли показывать каждый урок, когда агент доходил до соответствующего этапа. Инженеры по-прежнему решали, какие рекомендации применимы за пределами первоначального проекта.

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

Наиболее полезные рекомендации касались изменений в поведении, затронутых пользователей и вариантов, а также связей между API, схемами или парсерами. Оценки касались только вопросов и планов. Мы не оценивали, ускорило ли руководство процесс реализации. Узконаправленные рекомендации также быстрее устаревали и иногда всплывали в несвязанной работе.

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

Как бы мы сейчас подошли к принципу /spec-driven

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

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

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

• Не нужно включать в спецификацию каждый недостающий элемент. Инструмент должен предоставлять контекст и выполнять проверки; архитектурные решения всё равно нуждаются в проверке человеком.

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

Что дальше?

По прошествии трёх месяцев инженеры по-прежнему используют /spec-driven, когда работа продолжается в течение нескольких сессий, передаётся от одного человека к другому или разбивается на множество связанных задач. Они использовали его для поддержания хода многомесячных проектов и организации больших объёмов работы, выполняемой агентами. Это хороший результат для внутреннего эксперимента.

По мере того как мы расширяли /spec-driven, чтобы поддерживать больше видов работ, некоторые новые функции решали реальные проблемы для конкретных команд, но усложняли рабочий процесс для всех. В следующей версии мы хотим сделать ядро меньше и более целенаправленным.

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

[1] Биргитта Бёкелер, «Понимание разработки на основе спецификаций: Kiro, spec-kit и Tessl», октябрь 2025 г.

[2] Франсуа Занинотто, «Разработка на основе спецификаций: водопад наносит ответный удар», ноябрь 2025 г.

[3] Габриэлла Гонсалес, «Достаточно подробная спецификация — это код», март 2026 г.

Об авторе

Уолтер Ли — инженер-программист команды базовой инфраструктуры хранения данных Asana, а Рохан Батра — инженер-программист команды фреймворков серверной части. Оба несколько месяцев работали в команде Agent Success Tiger Team, где руководили разработкой и оценкой описанного в этой публикации рабочего процесса /spec-driven.

Благодарности команде

Особая благодарность Лео Чжану, Каролю Крупе, Горди Левицкому и Митчу Конкеру за помощь в формировании и разработке подхода /spec-driven, а также за то, что они стали одними из первых его пользователей.