Проблема, цели, ограничения, текущая архитектура и возможные варианты решения.
Техническая спецификация с обоснованием выбора, внедрением и открытыми вопросами.
Кому пригодится
Разработчикам, архитекторам и техническим руководителям.
Требования и ограничения
Согласовать техническое решение до реализации
Скилл превращает описание проблемы и предлагаемый подход в инженерную спецификацию или RFC. Документ предназначен для команды и рецензентов, которым нужно понять устройство будущего изменения, ограничения и причины выбора. Он помогает вынести спорные вопросы на обсуждение до написания кода.
Описать исходную задачу
Сначала собирают проблему, затронутых пользователей или системы, существующее поведение и ограничения. Указывают автора, дату, статус и участников ревью. Краткое начало объясняет, что предлагается изменить и зачем. Допущения обозначают явно: это особенно полезно, когда участники обсуждения по-разному представляют нагрузку, сроки или зависимости.
Зафиксировать цели и границы
Успех описывают через наблюдаемый результат. Функциональные требования дополняют ограничениями по задержкам, масштабу, безопасности и совместимости. Общие слова вроде «быстро» заменяют согласованными целевыми значениями. Отдельно перечисляют близкие задачи, которые читатель мог бы ошибочно включить в объём работ.
Показать работу решения целиком
Основной раздел связывает модели данных, интерфейсы, компоненты и последовательность операций. У каждого компонента должны быть понятны ответственность и взаимодействие с остальными. Описание охватывает тайм-ауты, повторные запросы, частичный сбой и ошибочные входные данные. Если нужна схема, её содержание формулируют достаточно точно для последующей отрисовки.
Объяснить выбор и внедрение
Рассмотренные альтернативы сравнивают по причинам отказа и принятым компромиссам. Риски связывают с конкретными последствиями. План внедрения описывает постепенное включение, перенос или заполнение данных, обратную совместимость и возврат к предыдущему состоянию. Подробные схемы и измерения можно вынести в приложение, сохранив логику решения в основном тексте.
Подготовить документ к обсуждению
Результат содержит спецификацию со всеми существенными разделами и отдельно выделенные открытые вопросы. Нерешённые пункты выносят в начало обращения к рецензентам, чтобы они получили внимание. Достаточность документа оценивают по тому, может ли новый участник понять реализацию без дополнительного восстановления контекста. Проектирование самого API-контракта и инструкции конечным пользователям относятся к соседним скиллам.
Автор и источник
Оригинальное название: technical-spec
Автор или репозиторий: SkillMedev/skills
Лицензия: MIT
Открыть первоисточник