明確で正確で効果的な仕様を生成する
仕様ファイル (spec.md) は、ソフトウェアの実行に関する単一の信頼のソースです。 このユニットでは、エンタープライズ レベルの仕様を記述するための高度な手法について説明します。
仕様の基礎を確認する
仕様駆動型の開発では、仕様によってソフトウェアの実行内容が正確に定義され、すべての実装決定がそれに戻ってトレースされます。 適切に構造化された仕様には、次のものが含まれます。
- 概要: エンドユーザーの観点から見たアプリケーション (または新機能) の簡潔な説明。
- ユーザー ストーリー: ユーザーがアプリケーションを操作する方法の簡単な説明。
- 受け入れ条件: 完了するためには満たされる必要がある、特定のテスト可能な条件。
- 機能要件: システム動作の詳細な説明。
- 機能以外の要件: パフォーマンス、セキュリティ、スケーラビリティなどの品質属性。
- エッジ ケース: 異常なシナリオ、エラー状態、境界動作。
唯一信頼でできる情報源としての仕様
仕様駆動型の開発では、仕様によってソフトウェアの実行内容が正確に定義され、すべての実装決定がそれに戻ってトレースされます。 機能がスペックに表示されない場合、他のユーザーがスペックを更新して成果物を再生成しない限り、最終的な製品には表示されません。
このアプローチは、考え方の変化を表しています。仕様の記述は、コードの記述と同じくらい重要です。 この仕様は、プロジェクト管理を満たすための形式ではありません。AI コードの生成を促進するのは成果物です。 手動で機能を実装する場合と同じように、スペックの作成にも同じ注意を払います。
仕様は実行可能なドキュメントと考えてください。 要件を変更する場合は、スペックを更新し、プランとタスクを再生成します。 Git でバージョン管理されている仕様は、各機能で実行する必要がある内容の権限のあるレコードになります。
アジャイル ワークフローに慣れているエンタープライズ開発者の場合、この仕様は詳細なユーザー ストーリーや受け入れ基準と同じ目的を果たしますが、AI アシスタントが直接使用できる機械読み取り可能な構造を備えます。
仕様の構造
GitHub Spec Kit では、機能動作、品質要件、エッジ ケースをカバーする標準化されたセクションに仕様が整理されています。
[Summary]\(概要\) セクション
エンドユーザーの観点からの機能の簡潔な説明。 このセクションでは、1 つまたは 2 つの文で "この機能の機能について" と答える必要があります。
例えば次が挙げられます。
## 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]\(ユーザー ストーリー\) セクション
ユーザーが機能を操作する方法の簡単な説明。 ユーザー ストーリーは、技術的な実装ではなく、意図と価値をキャプチャします。
例えば次が挙げられます。
## 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.
ユーザー ストーリーは、AI アシスタントが機能の背後にある人間の動機を理解し、より直感的な実装を実現するのに役立ちます。
[同意条件] セクション
機能が完了したと見なされるためには真である必要がある、特定のテスト可能な条件。 受け入れ基準は、実装を検証するためのチェックリストを形成します。
例えば次が挙げられます。
## 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
受け入れ基準を観測可能な事実として記述します。 "system is responsive" のようなあいまいなステートメントは避けてください。代わりに、"API responds within 200 ms" を指定します。
機能要件セクション
システム動作の詳細な説明。 機能要件では、機能のしくみについて詳しく説明します。
例えば次が挙げられます。
## 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
機能要件は、正確なコード構造を規定することなく、AI が適切な実装を生成するのに十分な詳細を提供します。
非機能要件セクション
パフォーマンス、セキュリティ、スケーラビリティ、コンプライアンスなどの品質属性。 これらの要件は、多くの場合、憲法を参照します。
例えば次が挙げられます。
## 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
非機能要件により、AI によって生成されたコードが、機能的な正確性だけでなく、エンタープライズ品質標準を満たしていることを確認します。
エッジ ケース セクション
通常とは異なるシナリオ、エラー条件、境界動作。 エッジ ケースを明示的に文書化すると、AI が想定を立てなくなります。
例えば次が挙げられます。
## 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 Spec Kit を使用して仕様を作成する
GitHub Spec Kit の /speckit.specify コマンドを使用すると、効果的な仕様を簡単に記述できます。
GitHub Spec Kit では、自然言語の説明に基づいて仕様のドラフトが生成され、一貫性のある構造を維持しながらスペックの作成が高速化されます。
specify コマンドを呼び出す
仕様を作成するには:
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 ドキュメントをアップロードする
- 場所: Web ダッシュボード インターフェイス
- 方法: Azure Blob Storage に格納する
- Who: 共同作成者ロールを持つユーザー
- 制約: 50 MB の制限、特定のファイルの種類
- ユーザー エクスペリエンス: 進行状況の表示、エラー メッセージ
GitHub Copilot は、この入力に基づいて構造化された spec.md ファイルを生成し、概要、受け入れ条件、要件、エッジ ケースのセクションを作成します。
生成された仕様を確認する
GitHub Copilot で仕様が生成されたら、 spec.md を開き、次のことを確認します。
完全性:仕様は、あなたが言及したすべての要件をカバーしていますか? "PDF と DOCX のみ" を指定した場合は、それらのファイルの種類の同意条件の一覧を確認します。
精度: 詳細は正しいですか? 50 MB の制限を指定した場合は、仕様の状態が 50 MB で、別の値ではないことを確認します。
整合性: 異なるセクションが一致しますか? 概要に進捗状況の表示が記載されている場合、受け入れ条件に含める必要があります。
不足している要素: GitHub Copilot は何を推論または省略しましたか? 生成された要件を確認して、AI が同意しない仮定を行ったかどうかを確認します。
初期仕様は強力な出発点ですが、完璧であることはめったにありません。 明確化を通じてそれを改善することを期待してください。
/speckit.clarify を使用して仕様を明確にする
/speckit.clarify コマンドは、仕様を分析し、明確にする必要があるあいまいさ、ギャップ、または前提条件を識別します。
仕様の明確さを確保する
仕様があいまいな場合、実装が正しくありません。
/speckit.clarifyを使用して、不明確な領域を表面に表示します。
初期仕様を生成した後:
GitHub Copilot Chat で、次のコマンドを実行します。
/speckit.clarifyGitHub 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 複数回実行します。 各イテレーションでは、仕様がさらに調整されます。
- 初回の評価: 主要な機能の不足。
- 2 番目のパス: エッジ ケースの詳細。
- 3 番目のパス: 非機能要件の微調整。
GitHub Copilot にこれ以上質問がない場合や、延期する機能についてのみ質問する場合は停止します。
仕様記述のベスト プラクティス
明確で明確な仕様を書くことは、スペック駆動型の開発を成功させるために重要です。
具体的で測定可能
あいまいな用語を正確な値に置き換えます。
「大きなファイルをサポートしません。」
代わりに、"最大 50 MB のファイルをサポートします。"
「高速なアップロード性能」ではありません。
代わりに、"5 MB 未満のアップロードは 10 Mbps 接続で 5 秒以内に完了します。"
特定の要件により、AI は実際のニーズを満たす実装を生成できます。
一貫性のある用語を使用する
用語を 1 回定義し、仕様全体で再利用します。概要で "ドキュメント" と呼ぶ場合は、後で "ファイル" または "添付ファイル" に切り替えないでください。 一貫性のない用語は、人間と AI の両方を混乱させる。
エンタープライズ内部プロジェクトの場合は、組織の標準の正式な製品名と用語を使用します。
エラー処理を明示的にカバーする
AI がエラーを適切に処理するとは想定しないでください。 操作が失敗した場合の動作を指定します。
- "Azure Blob Storage に到達できない場合は、"ストレージ サービスに接続できません" というエラーが表示されます。 後でもう一度やり直してください。'"
- "ユーザーに必要なロールがない場合は、HTTP 403 を返します。"ドキュメントをアップロードするアクセス許可がありません。" というメッセージが表示されます。
明示的なエラー処理により、ユーザーに役立たない一般的なエラー メッセージを AI が実装できなくなります。
適切なスコープを維持する
フィーチャーで指定する必要がある行が 300 行を超える場合は、複数の仕様に分割することを検討してください。
- 1 つの "ドキュメント管理システム" 仕様の代わりに。
- "ドキュメントのアップロード"、"ドキュメントのダウンロード"、"ドキュメント共有"、"ドキュメント検索" という個別の仕様を作成します。
より小さいスペックは、レビュー、明確化、実装が容易になります。 また、増分配信のプラクティスと一致します。
"how" ではなく "what" を詳しく説明する
仕様では、実装ではなく要件が定義されます。 コードを記述する方法ではなく、システムで実行する必要があることを示します。
- 仕様: "アップロードしたファイルを Azure Blob Storage に格納する"
- 仕様にありません: "BlobContainerClient クラスで Azure.Storage.Blobs NuGet パッケージを使用する"
実装の決定は、計画フェーズに属します。 ただし、憲法で特定のテクノロジが義務付けられている場合は、仕様で参照することが適切です。
憲法に対して検証する
スペックを完成させる前に、プロジェクトの原則と競合していないことを確認します。
- 構成には Microsoft Entra ID 認証が必要です → 仕様にはカスタム認証ではなく、Microsoft Entra ID を指定する必要があります。
- 憲法により、90日間の監査保持期間が義務付けられています。そのため、仕様には監査ログ要件を含める必要があります。
- 構成では、最大ファイル サイズが 50 MB に制限→ Spec では 1 GB のファイルサポートを必要としません。
仕様中にキャッチされた不整合は、実装後よりもはるかに安価に修正できます。
完成した仕様は、GitHub Copilot との契約になります。 計画フェーズに進むと、GitHub Copilot はこの仕様を参照して、要件に正確に一致する技術的な実装を設計します。 徹底的な仕様に投資された時間は、開発全体を通じて配当を支払います。
概要
効果的な仕様を記述することは、スペック駆動型開発を成功させるために基礎となります。 適切に構造化された仕様は、単一の信頼のソースとして機能し、AI コードの生成を導き、プロジェクトの原則との整合性を確保します。 GitHub Spec Kit の /speckit.specify コマンドと /speckit.clarify コマンドを使用すると、機能動作、品質属性、エッジ ケースに対応する詳細な仕様を迅速に作成および調整できます。 仕様記述のベスト プラクティスに従うと、明確さが向上し、あいまいさが軽減され、ユーザーのニーズとエンタープライズ標準の両方を満たす実装が実現します。