Создание четкой, точной и эффективной спецификации

14 мин

Файл спецификации (spec.md) — это единственный источник истины для того, что должно делать ваше программное обеспечение. В этом уроке рассматриваются расширенные методы написания спецификаций корпоративного уровня.

Ознакомьтесь с основами спецификаций

Сводка. Краткое описание приложения (или новой функции) с точки зрения конечного пользователя.
Истории пользователей: краткое описание взаимодействия пользователей с приложением.
Критерии принятия: конкретные тестируемые условия, которые должны быть верными для завершения.
Функциональные требования: подробные описания системного поведения.
Нефункциональные требования: атрибуты качества, такие как производительность, безопасность и масштабируемость.
Пограничные случаи: нетипичные сценарии, условия ошибок и поведение на границе.

Спецификация как единственный источник истины

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

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

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

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

Структура спецификации

GitHub Spec Kit упорядочивает спецификации в стандартизированных разделах, охватывающих функциональное поведение, требования к качеству и пограничные варианты.

Раздел "Сводка"

Краткое описание функции с точки зрения конечного пользователя. В этом разделе должен быть ответ "Что делает эта функция?" в одном или двух предложениях.

Рассмотрим пример.

## Summary

This feature enables employees to upload PDF and DOCX documents to their personal dashboard. Files are stored securely in Azure Blob Storage and appear in the user's document list immediately after upload.

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

Раздел "Истории пользователей"

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

Рассмотрим пример.

## User Stories

As an employee, I want to upload documents to my dashboard so that I can access them from any device.

As an employee, I want to see upload progress for large files so that I know the system is processing my request.

As a system administrator, I want uploads to be logged so that we can audit file activity for compliance purposes.

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

Раздел условий принятия

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

Рассмотрим пример.

## Acceptance Criteria

- User can select PDF or DOCX files for upload
- Maximum file size is 50MB
- Files larger than 50MB display an error message
- Unsupported file types display an error message
- Successfully uploaded files appear in the document list within 2 seconds
- Upload progress is displayed for files larger than 1MB
- Only users with 'Contributor' role can upload documents
- Uploaded files are stored in user-specific folders in Azure Blob Storage

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

Раздел "Функциональные требования"

Подробные описания поведения системы. Функциональные требования подробно описаны в том, как работает функция.

Рассмотрим пример.

## Functional Requirements

### Upload interface
- Dashboard displays an "Upload Document" button in the documents section
- Clicking "Upload Document" opens a file selection dialog
- User selects a file from their local filesystem
- System validates file type and size before initiating upload

### Upload process
- Files are uploaded via multipart HTTP POST to /api/documents endpoint
- Upload includes file content and metadata (filename, size, content type)
- Server validates authentication token before accepting upload
- Server checks user has 'Contributor' role before processing

### Storage
- Files are stored in Azure Blob Storage container 'employee-documents'
- Storage path follows pattern: {userId}/{fileId}/{filename}
- Server generates unique file ID to prevent naming collisions
- File metadata (original filename, upload timestamp, user ID) stored in Azure SQL Database

### User feedback
- Upload progress bar updates every 10% completion
- Success message displays upon completion: "Document uploaded successfully"
- Error messages display for: file too large, unsupported type, network error, server error

Функциональные требования предоставляют достаточно подробных сведений для ИИ для создания соответствующих реализаций без подготовки точной структуры кода.

Раздел нефункциональных требований

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

Рассмотрим пример.

## Non-Functional Requirements

### Performance
- File uploads under 5MB complete within 5 seconds on typical network
- Upload progress updates display with less than 100ms latency
- Document list refresh completes within 1 second after upload

### Security
- All uploads require valid Microsoft Entra ID authentication token
- HTTPS/TLS 1.2 enforced for all data transmission
- Files scanned for malware before storage (future enhancement)
- No sensitive data logged (filenames logged, content never logged)

### Scalability
- Support concurrent uploads (up to 5 simultaneous per user)
- Handle 1000 concurrent users uploading files

### Compliance
- Audit log records: user ID, filename, timestamp, file size, IP address
- Audit logs retained for 90 days minimum
- Support data deletion requests within the specified timeline

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

Раздел "Крайние случаи"

Необычные сценарии, условия ошибки и поведение границ. Явное документирование краевых случаев предотвращает предположения искусственного интеллекта.

Рассмотрим пример.

## Edge Cases

### Network interruption during upload
- If connection drops, display error: "Upload failed due to network error. Please retry."
- No partial files stored in Azure Blob Storage
- User can retry upload from beginning

### Duplicate filename
- System allows duplicate filenames by generating unique file IDs
- User sees original filename in document list
- Back end uses unique IDs to prevent overwrites

### Storage capacity limits
- If Azure Blob Storage quota exceeded, display error: "Upload failed due to storage limit. Contact support."
- Log storage errors for administrator notification

### Concurrent uploads by same user
- System supports up to 5 simultaneous uploads per user
- Sixth concurrent upload queued until one completes
- Progress bars update independently for each upload

### File type detection
- System validates file type by MIME type, not just extension
- File with .pdf extension but non-PDF content rejected
- Error message: "File appears corrupted or has incorrect type"

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

Создание спецификации с помощью набора спецификаций GitHub

Написание эффективных спецификаций проще с помощью команды GitHub Spec Kit /speckit.specify .

GitHub Spec Kit создает черновики спецификаций на основе описания естественного языка, ускоряя создание спецификаций при сохранении согласованной структуры.

Вызов команды специфицировать

Чтобы создать спецификацию, выполните следующее:

Откройте проект в Visual Studio Code.
Откройте GitHub Copilot Chat, а затем запустите /speckit.specify команду с помощью командной строки, описывающей функцию, которую вы хотите создать.

Рассмотрим пример.
```
/speckit.specify Create a new document upload feature. The feature should allow employees to upload PDF or DOCX documents through the web dashboard. Files are stored in Azure Blob Storage under the user's account folder. After upload, the file appears in the user's document list. Only users with 'Contributor' role can upload. Maximum file size is 50MB. Show error messages for oversized files or unsupported types. Display upload progress for files larger than 1MB.
```
В этом описании описано:
- Что: Отправка документов PDF/DOCX
- Где: интерфейс веб-панели мониторинга
- Способ хранения в хранилище BLOB-объектов Azure
- Кто: пользователи с ролью "Contributor"
- Ограничения: ограничение в 50 МБ, определенные типы файлов
- Взаимодействие с пользователем: отображение хода выполнения, сообщения об ошибках

GitHub Copilot создает структурированный spec.md файл на основе этих входных данных, создавая разделы для сводки, условий принятия, требований и пограничных вариантов.

Просмотр созданной спецификации

После создания спецификации GitHub Copilot откройте spec.md и проверьте следующее:

Полнота: распространяется ли спецификация на все упомянутые вами требования? Если вы указали "только PDF и DOCX", подтвердите, что в списке критериев приемки перечислены эти типы файлов.
Точность: правильно ли указаны сведения? Если вы указали ограничение в 50 МБ, убедитесь, что в спецификации указано 50 МБ, а не другое значение.
Согласованность: выравниваются ли разные разделы? Если в сводке упоминается отображение прогресса, критерии принятия должны включать его.
Отсутствующие элементы: что GitHub Copilot поймет или проигнорирует? Просмотрите созданные требования, чтобы узнать, были ли допущения ИИ, с которыми вы не согласны.

Начальная спецификация является сильной отправной точкой, но редко идеальной. Ожидается, что он будет доработан путём прояснения.

Уточнение спецификаций с помощью /speckit.clarify

Команда /speckit.clarify анализирует спецификацию и определяет неоднозначность, пробелы или предположения, требующие уточнения.

Обеспечение четкости спецификаций

Неоднозначность в спецификациях приводит к неправильной реализации. Используйте /speckit.clarify, чтобы выявить неясные области.

После создания начальной спецификации:

В GitHub Copilot Chat выполните следующую команду:
```
/speckit.clarify
```

GitHub Copilot анализирует spec.md и задает вопросы о неясных или отсутствующих деталях

Примеры вопросов об уточнении:

I've analyzed the specification and have some questions:

1. File retention: How long should uploaded documents be retained? Forever, or is there a retention policy?

2. Duplicate filenames: If a user uploads a file with the same name as an existing file, should the system:
    - Overwrite the existing file
    - Create a new version
    - Reject the upload with an error
    - Store both with unique identifiers

3. Virus scanning: Should uploaded files be scanned for malware? If so, when—before storage or asynchronously after upload?

4. Download capability: The spec describes upload but doesn't mention download. Should users be able to download their uploaded documents?

5. File sharing: Can users share documents with other employees, or are documents private to the uploader?

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

Ответы на вопросы о уточнении

Ответьте на каждый вопрос с определенными решениями:

1. File retention: Retain documents indefinitely until user deletes them. No automatic deletion.

2. Duplicate filenames: Option d - Store both with unique identifiers. Users can have multiple files with the same name. Display upload timestamp to distinguish them in the list.

3. Virus scanning: Not required for initial release. Mark as future enhancement in the spec.

4. Download capability: Yes, users should be able to download their documents. Add this to the spec.

5. File sharing: Documents are private to the uploader for this release. Sharing is a future feature.

После вашего ответа GitHub Copilot обновляет spec.md, чтобы учесть ваши решения:

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

Повторяйте до завершения

При необходимости запустите /speckit.clarify несколько раз. Каждая итерация дополнительно обновляет спецификацию:

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

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

Сводка

Написание эффективных спецификаций является основой для успешной разработки на основе спецификаций. Хорошо структурированная спецификация служит одним источником истины, руководствуясь созданием кода ИИ и обеспечением соответствия принципам проекта. Используя команды /speckit.specify и /speckit.clarify GitHub Spec Kit, вы можете быстро создавать и уточнять подробные спецификации, охватывающие функциональное поведение, атрибуты качества и крайние случаи. Следуя рекомендациям в написании спецификаций, улучшает ясность, уменьшает неоднозначность и приводит к реализации, которые соответствуют потребностям пользователей и корпоративным стандартам.

Обратная связь

Были ли сведения на этой странице полезными?

Создание четкой, точной и эффективной спецификации

Ознакомьтесь с основами спецификаций

Спецификация как единственный источник истины

Структура спецификации

Раздел "Сводка"

Раздел "Истории пользователей"

Раздел условий принятия

Раздел "Функциональные требования"

Раздел нефункциональных требований

Раздел "Крайние случаи"

Создание спецификации с помощью набора спецификаций GitHub

Вызов команды специфицировать

Просмотр созданной спецификации

Уточнение спецификаций с помощью /speckit.clarify

Обеспечение четкости спецификаций

Ответы на вопросы о уточнении

Повторяйте до завершения

Рекомендации по написанию спецификаций

Быть конкретным и измеримым

Использование согласованной терминологии

Явная обработка ошибок

Поддержание соответствующего объема

Детализируйте "что", а не "как"

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

Сводка

Обратная связь