명확하고 정확하며 효과적인 사양 생성
사양 파일(spec.md)은 소프트웨어에서 수행해야 하는 작업에 대한 단일 정보 소스입니다. 이 단원에서는 엔터프라이즈급 사양을 작성하기 위한 고급 기술을 다룹니다.
사양 기본 사항 검토
사양 기반 개발에서 사양은 소프트웨어가 수행해야 하는 작업을 정확하게 정의하고 모든 구현 결정은 이를 추적합니다. 잘 구성된 사양에는 다음이 포함됩니다.
- 요약: 최종 사용자 관점에서 애플리케이션(또는 새로운 기능)에 대한 간결한 설명입니다.
- 사용자 스토리: 사용자가 애플리케이션과 상호 작용하는 방법에 대한 간략한 설명입니다.
- 승인 기준: 특정, 테스트 가능한 조건으로, 완료 조건으로 참이어야 합니다.
- 기능 요구 사항: 시스템 동작에 대한 자세한 설명입니다.
- 비기능 요구 사항: 성능, 보안 및 확장성과 같은 품질 특성입니다.
- 에지 케이스: 특이한 시나리오, 오류 조건 및 경계 동작.
진실의 단일 소스로서의 사양
사양 기반 개발에서 사양은 소프트웨어가 수행해야 하는 작업을 정확하게 정의하고 모든 구현 결정은 이를 추적합니다. 사양에 기능이 표시되지 않으면 다른 사용자가 사양을 업데이트하고 아티팩트 다시 생성하지 않는 한 최종 제품에 표시되지 않습니다.
이 방법은 사고 방식의 변화를 나타냅니다. 사양을 작성하는 것은 코드 작성만큼 중요합니다. 사양은 프로젝트 관리를 만족시키는 형식이 아니라 AI 코드 생성을 구동하는 아티팩트입니다. 기능을 수동으로 구현할 때와 마찬가지로 사양을 만드는 데 동일한 주의를 기울여야 합니다.
사양을 실행 문서로 간주합니다. 요구 사항을 수정할 때 사양을 업데이트하고 계획 및 작업을 다시 생성합니다. Git에서 버전 제어되는 사양은 각 기능이 수행해야 하는 작업의 신뢰할 수 있는 레코드가 됩니다.
민첩한 워크플로에 익숙한 엔터프라이즈 개발자의 경우 사양은 자세한 사용자 스토리 및 수용 기준과 동일한 용도로 사용되지만 AI 도우미가 직접 사용할 수 있는 기계 읽기 가능한 구조를 사용합니다.
사양 구조
GitHub 사양 키트는 기능 동작, 품질 요구 사항 및 에지 사례를 다루는 표준화된 섹션으로 사양을 구성합니다.
요약 섹션
최종 사용자 관점에서 기능에 대한 간결한 설명입니다. 이 섹션에서는 한두 문장에서 "이 기능은 어떻게 합니까?"라고 대답해야 합니다.
다음은 그 예입니다.
## 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.
사용자 스토리는 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
수용 조건을 관찰 가능한 사실로 작성합니다. "시스템이 응답성이 있습니다."와 같은 모호한 문을 사용하지 말고 대신 "200ms 내에서 API 응답"을 지정합니다.
기능 요구 사항 섹션
시스템 동작에 대한 자세한 설명입니다. 기능 요구 사항은 기능 작동 방식을 자세히 설명합니다.
다음은 그 예입니다.
## 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 사양 키트를 사용하여 사양 만들기
GitHub 사양 키트의 /speckit.specify 명령을 사용하면 효과적인 사양을 쉽게 작성할 수 있습니다.
GitHub 사양 키트는 자연어 설명을 기반으로 사양 초안을 생성하여 일관된 구조를 유지하면서 사양 생성을 가속화합니다.
지정 명령 호출
사양을 만들려면 다음을 수행합니다.
Visual Studio Code에서 프로젝트를 엽니다.
GitHub Copilot 채팅을 연 다음 만들려는 기능을 설명하는 프롬프트를 사용하여 명령을 실행
/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 문서 업로드
- 위치: 웹 대시보드 인터페이스
- 방법: Azure Blob Storage에 저장
- 사용자: 기여자 역할이 있는 사용자
- 제약 조건: 50MB 제한, 특정 파일 형식
- 사용자 환경: 진행률 표시, 오류 메시지
GitHub Copilot는 이 입력을 기반으로 구조화된 spec.md 파일을 생성하여 요약, 수용 조건, 요구 사항 및 에지 사례에 대한 섹션을 만듭니다.
생성된 사양 검토
GitHub Copilot에서 사양을 생성한 후 spec.md을 열고 확인합니다.
완전성: 사양에서 언급한 모든 요구 사항을 충족하나요? "PDF 및 DOCX만"을 지정한 경우 승인 조건에 해당 파일 형식이 나열되는지 확인합니다.
정확도: 세부 정보가 올바른가요? 50MB 제한을 말한 경우 사양이 다른 값이 아니라 50MB 상태인지 확인합니다.
일관성: 다른 섹션이 정렬되어 있나요? 요약에 진행률이 표시되면 승인 조건에 포함해야 합니다.
누락된 요소: GitHub 코필로트는 무엇을 유추하거나 생략했나요? 생성된 요구 사항을 검토하여 AI가 동의하지 않는 가정을 했는지 확인합니다.
초기 사양은 강력한 시작점이지만 거의 완벽하지 않습니다. 설명을 통해 구체화할 것을 기대합니다.
/speckit.clarify를 사용하여 사양 구체화
이 /speckit.clarify 명령은 사양을 분석하고 설명이 필요한 모호성, 간격 또는 가정을 식별합니다.
사양 명확성 보장
사양의 모호성으로 인해 잘못된 구현이 발생합니다. 불분명한 영역을 노출하는 데 사용합니다 /speckit.clarify .
초기 사양을 생성한 후:
GitHub Copilot 채팅에서 다음을 실행합니다.
/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 합니다. 각 반복은 사양을 추가로 구체화합니다.
- 첫 번째 단계: 주요 기능 격차.
- 두 번째 패스: 에지 사례 세부 정보입니다.
- 세 번째 패스: 비기능적 요구 사항 미세 조정
GitHub Copilot에 더 이상 질문이 없거나 연기하려는 기능에 대해서만 묻는 경우 중지합니다.
사양 작성 모범 사례
명확하고 명확한 사양을 작성하는 것은 성공적인 사양 기반 개발의 핵심입니다.
구체적이고 측정 가능
모호한 용어를 정확한 값으로 바꿉니다.
아님: "대용량 파일을 지원합니다."
대신 " 최대 50MB의 파일을 지원합니다."
아님: "빠른 업로드 성능."
대신 : "5MB 미만의 업로드는 10Mbps 연결에서 5초 이내에 완료됩니다."
특정 요구 사항을 통해 AI는 실제 요구 사항을 충족하는 구현을 생성할 수 있습니다.
일관된 용어 사용
용어를 한 번 정의하고 사양 전체에서 다시 사용합니다. 요약에서 "문서"를 호출하는 경우 나중에 "파일" 또는 "첨부 파일"로 전환하지 마세요. 일관되지 않은 용어는 인간과 AI를 혼동합니다.
엔터프라이즈 내부 프로젝트의 경우 조직의 표준에서 공식 제품 이름 및 용어를 사용합니다.
명시적으로 오류 처리를 다룹니다.
AI가 오류를 적절하게 처리하고 있다고 가정하지 마세요. 작업이 실패할 때 수행되는 작업을 지정합니다.
- "Azure Blob Storage에 연결할 수 없는 경우, 오류를 표시합니다: '스토리지 서비스에 연결할 수 없습니다.'" 나중에 다시 시도하세요.'"
- "사용자에게 필요한 역할이 없는 경우 '문서를 업로드할 수 있는 권한이 없습니다.'라는 메시지와 함께 HTTP 403을 반환합니다."
명시적 오류 처리는 AI가 사용자에게 도움이 되지 않는 일반 오류 메시지를 구현하지 못하게 합니다.
적절한 범위 유지 관리
기능을 지정하는 데 300줄 이상이 필요한 경우 여러 사양으로 분할하는 것이 좋습니다.
- 하나의 "문서 관리 시스템" 사양 대신에,
- "문서 업로드", "문서 다운로드", "문서 공유" 및 "문서 검색"과 같은 별도의 사양을 만듭니다.
더 작은 사양은 더 쉽게 검토하고, 명확히 하고, 구현할 수 있습니다. 또한 증분 전달 사례에 부합합니다.
"세부 사항을 '무엇'에 집중하고 '방법'은 피하십시오."
사양은 구현이 아닌 요구 사항을 정의합니다. 코드를 코딩하는 방법이 아니라 시스템에서 수행해야 하는 작업을 명시합니다.
- 사양: "Azure Blob Storage에 업로드된 파일 저장."
- 사양이 아닙니다. "BlobContainerClient 클래스와 함께 Azure.Storage.Blobs NuGet 패키지를 사용합니다."
구현 결정은 계획 단계에 속합니다. 그러나 헌법이 특정 기술을 의무화하는 경우 사양에서 이를 참조하는 것이 적절합니다.
헌법에 따라 유효성을 검사하다
사양을 완료하기 전에 프로젝트 원칙과 충돌하지 않는지 확인합니다.
- 헌법은 Microsoft Entra ID 인증을 요구 → 사양은 사용자 지정 인증이 아닌 Microsoft Entra ID를 지정해야 합니다.
- 헌법은 90일 감사 보존을 의무화하고 → 사양에는 감사 로깅 요구 사항이 포함되어야 합니다.
- 헌법은 최대 파일 크기를 50MB로 제한합니다→ 사양에는 1GB 파일 지원이 필요하지 않습니다.
사양 단계에서 발견된 불일치는 구현 후에 수정하는 것보다 훨씬 저렴합니다.
완성된 사양은 GitHub Copilot와의 계약이 됩니다. 계획 단계를 진행하는 경우 GitHub Copilot는 이 사양을 참조하여 요구 사항과 정확하게 일치하는 기술 구현을 디자인합니다. 철저한 사양에 투자하는 시간은 개발 전반에 걸쳐 배당금을 지불합니다.
요약
효과적인 사양 작성은 성공적인 사양 기반 개발의 기초입니다. 체계적으로 구성된 사양서는 AI 코드 생성을 안내하고 프로젝트 원칙과 일치하는 단일 진리의 출처 역할을 합니다. GitHub 사양 키트 /speckit.specify 및 /speckit.clarify 명령을 사용하여 기능 동작, 품질 특성 및 에지 사례를 다루는 세부 사양을 빠르게 만들고 구체화할 수 있습니다. 사양 작성의 모범 사례를 따르면 명확성이 향상되고 모호성이 감소하며 사용자 요구 사항과 엔터프라이즈 표준을 모두 충족하는 구현으로 이어집니다.