Создание подробного технического плана

  • 12 мин

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

Обзор основных принципов плана

Файл plan.md служит проектным документом, преодолев разрыв между высоким уровнем требований в spec.md и конкретными задачами реализации, которые следуют. Полный технический план содержит следующее:

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

Учитывая эти основы, давайте рассмотрим вопросы расширенного планирования для развития предприятий.

Разделение проблем — спецификация и план

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

Предположим, что для вашей спецификации требуется функция отправки документов для внутреннего портала сотрудников. Спецификация определяет требования пользователей: ограничения размера файла, поддерживаемые форматы, отзывы о отправке и элементы управления доступом. Технический план преобразует эти требования в конкретные архитектурные решения: какую службу хранилища Azure следует использовать, как структурировать API, какой механизм проверки подлинности следует реализовать, и как проверить файлы. Если вы решили перейти с одной технологии на другую, например переход с хранилища BLOB-объектов Azure в файлы Azure, вы обновляете plan.md в то время как spec.md остается в значительной степени неизменным. Требования к функциям не изменяются; изменяется только подход реализации.

Изучение структуры плана и содержимого

Комплексный технический план содержит несколько ключевых разделов, которые коллективно определяют подход к реализации.

Обзор архитектуры

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

Реализуйте новую конечную точку API бэкэнда /api/documents/upload для обработки загрузки многопартийных файлов. Интерфейс React включает новый компонент DocumentUpload с индикатором выбора файлов и индикатором хода выполнения. Когда пользователь выбирает файл, интерфейс проверяет размер и тип перед отправкой. Серверная часть получает файл, проверяет его еще раз, сохраняет его в хранилище BLOB-объектов Azure и записывает метаданные в базе данных SQL. После успешной отправки интерфейс обновляет список документов, чтобы отобразить новый файл".

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

Стек технологий и ключевые решения

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

Примеры технологических решений:

  • Серверная часть: веб-API .NET 8 с пакетом SDK Azure.Storage.Blobs версии 12 для операций blob-объектов.
  • Фронтенд: React 18 с компонентом загрузки Ant Design для согласованности пользовательского интерфейса.
  • Проверка подлинности: Используйте существующий токен идентификатора Microsoft Entra из контекста проверки подлинности портала.
  • Хранилище: контейнер хранилища BLOB-объектов Azure с именем employee-documents.
  • База данных: расширение существующей базы данных SQL с помощью таблицы DocumentMetadata (столбцы: Id, UserId, FileName, BlobUrl, UploadDate, FileSize).

Каждое решение должно соответствовать как требованиям спецификации, так и принципам конституции. Если ваша конституция требует "Использовать службы Azure для всех облачных ресурсов", план явно выбирает хранилище BLOB-объектов Azure и ссылается на этот принцип.

Последовательность реализации

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

Типичная последовательность реализации для функции отправки документа:

  1. Обновление схемы базы данных: создание таблицы DocumentMetadata с соответствующими индексами и ограничениями.
  2. Разработка серверного API: реализуйте endpoint POST /api/documents/upload с валидацией файлов, интеграцией хранилища BLOB-объектов и сохранением метаданных.
  3. Создание внешнего компонента: компонент Build DocumentUpload с выбором файла, проверкой на стороне клиента и отображением хода отправки.
  4. Интеграция. Подключение внешнего компонента к внутреннему API, обработке ответов и обновлению списка документов.
  5. Обеспечение безопасности: реализация проверки типа файлов на стороне сервера, ограничения размера и проверки подлинности.
  6. Обработка ошибок. Добавление комплексных сообщений об ошибках для сбоев на стороне клиента и сервера.
  7. Тестирование: разработка модульных тестов для методов API и интеграционных тестов для потока отправки.

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

Проверка конституции

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

Если ваша конституция включает в себя "Все хранилища данных должны использовать службы Azure" и "API должны проверять входные данные как на клиенте, так и на сервере", раздел проверки плана подтверждает:

  • "Использование хранилища BLOB-объектов Azure удовлетворяет требованиям служб Azure".
  • «Реализация проверки в компоненте React (клиенте) и API .NET (сервере) соответствует принципу безопасности глубинной защиты».
  • "Требование проверки подлинности идентификатора Microsoft Entra выполняется с помощью существующего контекста проверки подлинности портала".

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

Предположения и открытые вопросы

Хорошо составленные планы документируют предпосылки и неразрешенные вопросы. Эта прозрачность помогает выявить потенциальные проблемы перед началом реализации.

Примеры предположений:

  • Предположим, что контейнер хранилища BLOB-объектов Azure "employee-documents" существует и настроен для закрытого доступа".
  • Предположим, что существующая база данных SQL имеет достаточную емкость хранилища для метаданных".
  • "Предположим, что проверка вирусов отправленных файлов выходит за рамки этой итерации".

Пример открытых вопросов:

  • "Должны ли администраторы иметь возможность удалять загруженные документы других пользователей?"
  • "Требуется ли ведение журнала аудита для всех попыток доступа к документам?"
  • "Следует ли системе отправлять уведомления по электронной почте при отправке документов?"

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

Создание плана с помощью /speckit.plan

GitHub Spec Kit создает планы с помощью команды /speckit.plan в чате GitHub Copilot. Эта команда использует как spec.md, так и constitution.md в качестве входных данных для создания комплексного технического проектирования.

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

Для функции отправки документов в сценарии внутреннего портала сотрудников можно указать такой контекст:

"Существующий портал использует интерфейс React с серверной частью веб-API .NET 8. Необходимо интегрировать функцию отправки в этот стек. Используйте хранилище BLOB-объектов Azure для сохранения файлов. Требуется проверка подлинности идентификатора Microsoft Entra для всех операций отправки. На портале уже есть база данных SQL, доступная для хранилища метаданных".

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

Вызов команды планирования

Откройте чат GitHub Copilot в Visual Studio Code и введите /speckit.plan. Если ИИ запрашивает дополнительные сведения, укажите свой архитектурный контекст. GitHub Copilot обрабатывает спецификацию, структуру и дополнительный контекст для создания plan.md.

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

Анализ и утверждение плана

Создание плана — это только первый шаг. Критический обзор гарантирует, что план является точным, полным и согласован с потребностями проекта.

Проверка охвата требований спецификации

Систематически сравнивайте план и spec.md. Каждое требование в спецификации должно соответствовать подходу реализации в плане.

Например, если в spec.md требуется выводить сообщение об ошибке для файлов размером более 50 МБ, план должен описывать, где и как выполняется эта проверка. Если план игнорирует эту проверку, план является неполным или спецификация нуждается в уточнении.

Проверка соответствия техническим стандартам

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

Вопросы, которые следует рассмотреть:

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

Для функции загрузки документов в среде Azure убедитесь, что Хранилище BLOB-объектов Azure является утвержденной службой, что подход аутентификации совпадает с корпоративными стандартами аутентификации (например, с помощью Microsoft Entra ID) и что предлагаемая схема SQL соответствует соглашениям об именовании баз данных.

Проверка соблюдения конституции

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

Если в вашей конституции требуется "Все секреты должны храниться в Azure Key Vault", а план предлагает хранение строк подключения службы хранилища Azure в appsettings.json, существует конфликт. План следует пересмотреть, чтобы получать строки подключения из Key Vault в процессе выполнения.

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

Повторите и уточните план

Планы часто требуют уточнения после первоначального создания. Не ожидайте совершенства на первой попытке. Используйте возможности уточнения GitHub Copilot для улучшения качества плана.

Устранение неоднозначности и пробелов

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

Используйте GitHub Copilot Chat, чтобы задать дополнительные вопросы: "Какие конкретные ошибки должна обрабатывать конечная точка загрузки?" или "Что должно произойти, если хранилище блобов Azure недоступно?" ИИ способен превратить расплывчатые формулировки в конкретные спецификации.

Проверка технического обеспечения

Убедитесь, что предлагаемая архитектура технически возможна с учетом ограничений. Если план предлагает отправку файлов размером 50 МБ синхронно через веб-API с 30-секундным тайм-аутом, возникла проблема. Для файлов, которые имеют более 50 МБ, могут потребоваться фрагментированные отправки или увеличение времени ожидания.

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

Рассмотрите нефункциональные требования

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

Для отправки документов убедитесь, что план включает:

  • Производительность: как быстро должна завершиться отправка? Что такое максимальный объем параллельной отправки?
  • Безопасность: как сканируются файлы для вредоносных программ? Как контролируется доступ? Где хранятся журналы аудита?
  • Масштабируемость. Как система обрабатывает увеличенный объем отправки? Каковы ограничения емкости хранилища?
  • Удобство обслуживания: как удаляются загруженные файлы, когда сотрудники покидают организацию?
  • Доступность: Соответствует ли пользовательский интерфейс загрузки стандартам доступности веб-содержимого (WCAG) 2.1 AA?

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

Оценка целесообразности и полноты

Оцените, предоставляет ли план достаточное руководство по реализации. Планы, которые слишком расплывчаты ("Реализация отправки файлов") не являются полезными. Планы, которые слишком предписательны ("Использовать ровно 47 строк кода"), накладывают чрезмерные ограничения.

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

  • Какие компоненты необходимо создать или изменить?
  • Как взаимодействуют эти компоненты?
  • Какие технологии и библиотеки используются?
  • Какой порядок реализации?
  • Какие шаги проверки обеспечивают правильность?

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

Определение отсутствующих элементов

Найдите пробелы в плане. Распространенные упущения включают:

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

Устранение этих пробелов путем ручного редактирования plan.md или предоставления дополнительных контекстов и повторного создания соответствующих разделов.

Повторное создание с помощью уточненного контекста

Если начальный план не соответствует цели, предоставьте более конкретный контекст и пересоздайте его. Например, если план предлагает использовать новую базу данных, но ее необходимо использовать, проясните: "Используйте существующую базу данных EmployeePortal. Добавьте таблицу DocumentMetadata в эту базу данных, а не создайте новую.

Повторно создайте план, /speckit.plan включив этот обновленный контекст. ИИ корректирует подход соответствующим образом.

Изменение плана вручную

Так как plan.md является файлом Markdown, его можно изменить напрямую. Если ИИ предлагает подход, который на 90% правильный, но требует незначительных изменений, отредактируйте файл вместо повторного создания всего.

Например, если план предлагает определенное имя контейнера объектов Blob, но у вашей организации есть свои соглашения об именовании, обновите имя контейнера непосредственно в plan.md.

Совместная работа с участниками группы

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

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

Документирование архитектурных решений

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

Альтернативы записи, которые рассматриваются

При выборе между несколькими жизнеспособными подходами задокументируйте варианты, которые вы рассмотрели, и почему вы выбрали один из них.

Для хранилища файлов можно рассмотреть три подхода:

  • Хранилище BLOB-объектов Azure: выбрано для экономии, масштабируемости и интеграции с существующей средой Azure.
  • Файлы Azure: Отклонено из-за более высоких затрат на хранилище больших файлов и избыточной нагрузки, связанной с протоколом SMB.
  • SQL Database FILESTREAM: было отклонено, чтобы избежать увеличения размера и сложности базы данных.

Эта документация запрещает будущим разработчикам задавать вопрос о том, почему более простые подходы не использовались. Обоснование решения сохраняется, а не теряется во времени.

Фиксация предположений

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

Примеры предположений для отправки документов:

  • Контейнер employee-documents хранилища BLOB-объектов Azure подготавливается командой инфраструктуры перед началом разработки.
  • Существующая проверка подлинности портала предоставляет проверенные токены Microsoft Entra ID, которым можно доверять для идентификации пользователей.
  • База данных SQL имеет достаточную емкость для другой таблицы метаданных, не требуя расширения хранилища.
  • Сетевая инфраструктура поддерживает отправку HTTP размером 50 МБ без ограничений прокси-сервера или брандмауэра.

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

Планирование будущих эволюций

Рассмотрим, как эта функция может развиваться и обеспечить соответствие архитектуре вероятным расширениям.

Для загрузки документов возможные потенциальные будущие требования могут включать:

  • Поддержка других типов файлов за пределами PDF и DOCX.
  • Реализация общего доступа к файлам между сотрудниками.
  • Добавление управления версиями документов.
  • Включение массовой загрузки нескольких файлов.
  • Интеграция сканирования вирусов

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

Предоставление общего доступа и обслуживание плана во время реализации

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

Предоставление общего доступа к плану заинтересованным лицам

После завершения плана поделитесь им с соответствующими заинтересованными лицами для проверки:

  • Менеджеры по продуктам: убедитесь, что план предоставляет все требования к спецификациям.
  • Группа безопасности. Подтвердите контроль безопасности в соответствии со стандартами организации.
  • Команда инфраструктуры. Убедитесь, что предлагаемые ресурсы Azure можно подготовить и настроить.
  • Команда по архитектуре. Проверка соответствия принципам архитектуры организации.

Этот обзор заинтересованных лиц перехватывает проблемы до начала реализации. Если отзыв группы безопасности показывает, что предлагаемая проверка подлинности недостаточна, перед написанием кода обновите план.

Обновление плана по мере необходимости

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

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

Синхронизировать plan.md с фактической реализацией. При изменении плана и кода план теряет значение в качестве справочной документации.

  • Подходы к безопасности соответствуют требованиям организации?
  • Соответствует ли схема базы данных соглашениям об именовании?

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

Распространенные ошибки планирования, которых следует избегать

Избегайте этих распространенных ошибок при создании и проверке планов:

  • Пропуск этапа планирования: переход непосредственно из спецификации в код без плана повышает риск ошибок архитектуры. Время, вложенное в планирование, платит дивиденды, предотвращая повторную работу.

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

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

  • Игнорируя конфликты конституции: если план нарушает принципы конституции, немедленно решить конфликт. Либо измените план для соблюдения или обновления конституции, если этот принцип нуждается в пересмотре.

  • Забыли обновить планы: когда реализация отображает новые сведения, обновите plan.md. Устаревшие планы вводят в заблуждение разработчиков в будущем и уменьшают ценность вашей документации.

Сводка

Технический план преобразует спецификацию в действимную архитектуру. Создайте планы с использованием /speckit.plan в контексте вашего стека технологий и инфраструктуры. Критически просмотрите планы, чтобы обеспечить, чтобы они охватывали все требования спецификации, согласуются с вашей конституцией и предоставляют достаточное руководство по реализации. Используйте проверенный план, чтобы управлять созданием и реализацией задач. Рассматривайте plan.md как живой документ, который развивается по мере вашего понимания и предоставляет весьма ценный контекст для всего жизненного цикла разработки.