Coroid использует разработку на основе спецификаций: спецификация сопровождает каждую задачу от этапа планирования до тестирования и рецензирования, благодаря чему все этапы работают исходя из одного и того же определения успеха.
Вместо того чтобы начинать с общего описания и определять детали во время написания кода, Coroid превращает запрос в явное определение области применения, исключений и критериев приемки. Этот документ становится источником истины для плана, реализации, тестов и финального рецензирования.
Что такое разработка на основе спецификаций?
Разработка на основе спецификаций — это подход к созданию программного обеспечения на основе согласованного и поддающегося тестированию описания результата. В спецификации указывается, что именно изменится, что останется без изменений, какие ограничения применяются и как рецензент сможет определить, что работа выполнена успешно.
Она разделяет два решения, которые легко спутать друг с другом:
- Спецификация спецификация определяет, что считается успешным результатом.
- Это план реализации определяет способ достижения цели.
Такое разделение позволяет скорректировать область задачи ещё до написания кода, не предписывая деталей реализации заранее. В Coroid также можно включить необязательный рабочий процесс SDLC , если требуется утвердить намерение и спецификацию до начала планирования.
Как работает этот рабочий процесс в Coroid
- Опишите желаемый результат. Передайте в Coroid нужный результат, соответствующий контекст, а также любые ограничения или нецелевые задачи.
- Просмотрите спецификацию. Проверьте область применения, исключения и критерии приемки в разделе «Задача»: Спецификация Раздел.
- Утвердите план. Архитектор преобразует согласованный результат в упорядоченные шаги реализации.
- Собрать и проверить. Агенты-разработчики и специалисты по контролю качества используют одни и те же критерии для реализации изменений и подтверждения соответствия заявленному поведению.
- Просмотрите документ pull request. Внедренное изменение возвращает план, результаты тестов, выводы и подтверждающие данные к исходной спецификации.
В итоге обеспечивается прослеживаемость от цели продукта до кода и подтверждающих данных, которые видит человек-рецензент. Подробнее — Как Задача превращается в документ pull request — полный путь выполнения.
Зачем нужен дополнительный этап?
Инструкция вроде «добавить кэширование при поиске пользователя» допускает как минимум четыре разумных способа реализации, но не имеет четкого определения готовности. Агент выберет один из них. То, попадет ли он на ваш вариант, — вопрос удачи.
Спецификация делает этот выбор явным еще до начала реализации, когда изменить решение стоит наименьше всего.
Она также дает возможность для верификации что проверять. Без критериев приемки вопрос «сработало ли это?» сводится к «проходят ли тесты?», что является гораздо более слабым критерием оценки.
Что включает в себя спецификация
| Часть | На какой вопрос дает ответ |
|---|---|
| Область применения | Что изменится |
| Вне области охвата | То, что намеренно не будет включено, чтобы изменения не разрастались |
| Критерии приемки | Как понять, что работа выполнена корректно |
| Контекст | Ограничения, нормы и ранее принятые решения, которые применимы |
Вы можете прочитать и отредактировать его на вкладке задачи Спецификация перед началом выполнения. Подробное описание работы и сопутствующий контекст, необходимые для этого процесса, см. в разделе Описание необходимых требований.
Пример: от краткого описания до проверяемой спецификации
Предположим, исходное краткое описание выглядит так:
Add caching to the user lookup so repeated requests are faster.В нём указан желаемый результат, но важные аспекты остаются неопределёнными. Качественная спецификация превращает эти аспекты в чёткие границы и критерии:
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.Теперь план может выбрать способ реализации, команда QA — создать тесты на основе критериев, а рецензент — сравнить результат с ожидаемым поведением в pull request.
Что делает критерии приемки качественными
Их должен быть способ проверить человек, не участвовавший в обсуждении.
Неудачный вариант:
Caching works correctly and performance is improved.Хороший вариант:
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.Второй вариант подсказывает агенту-разработчику, что создавать, агенту-QA — что тестировать, а вам — что проверять в pull request. Первый вариант оставляет все эти решения на усмотрение исполнителей.
Границы области охвата так же важны, как и критерии
Самая частая причина чрезмерного увеличения объёма pull request — не превышение полномочий агента, а отсутствие в спецификации чётких границ области охвата.
Если вы не хотите, чтобы сопутствующий модуль рефакторился во время выполнения задачи, укажите это явно. Условие «не изменять места вызовов» — законное и полезное ограничение.
Распространённые ошибки в спецификациях
| Ошибка | Более эффективный подход |
|---|---|
| Описание способа реализации вместо результата | Укажите требуемое поведение и ограничения, а выбор способа реализации оставьте на усмотрение плана. |
| Использование слов вроде «быстро», «надёжно» или «работает корректно» | Замените их на наблюдаемые пороги, поведение или тесты. |
| Отсутствие упоминания нецелевых функций | Укажите код, интерфейсы или поведение, которые должны остаться без изменений. |
| Объединение несвязанных результатов | Разделите работу так, чтобы одна задача завершалась одним проверяемым pull request. |
| Копирование задачи без проверки исходных предположений | Добавьте контекст и решения, которые не видны в репозитории. |
Если вы не согласны с содержанием спецификации
Отредактируйте её. Спецификация является рабочим документом до начала выполнения, и исправить её гораздо дешевле, чем исправлять код, созданный на её основе.
Если по результатам спецификации становится ясно, что работа фактически состоит из двух частей, разделите её на две задачи. Одна задача должна завершаться одним pull request, который один человек сможет рассмотреть за один присест.
Куда двигаться дальше
Для любых изменений, кроме небольших, спецификация становится планом. Подробнее Задачи, планы, спринты и этапы, где описывается порядок разделения и согласования работы до написания кода.
Часто задаваемые вопросы
Является ли спецификация техническим проектом?
Нет. Спецификация определяет требуемый результат и его границы. Технический проект или план реализации описывают архитектуру и шаги для достижения этого результата.
Нужна ли для каждого изменения подробная спецификация?
Нет. Для небольшого однозначного изменения может потребоваться лишь несколько строк с описанием области применения и критериев приемки. Спецификация должна устранять существенную неопределенность, а не создавать лишнюю формальность.
Кто должен утверждать спецификацию?
Лицо, ответственное за результат, должно подтвердить, что область применения и критерии соответствуют потребностям команды. Технические, сетевые или нормативные эксперты могут участвовать в утверждении, если их ограничения влияют на успех.
Может ли спецификация измениться после начала работы?
Может, но такое изменение должно привести к созданию новой версии и запуску рецензирования соответствующего плана и работы. Незаметные изменения области применения разрывают цепочку подтверждений между запросом и готовым pull request.