Technical Specification
Create comprehensive technical specifications for software projects.
Specification Template
# Technical Specification: [Feature Name]
## Metadata
- **Status**: Draft | In Review | Approved
- **Author**: [Name]
- **Reviewers**: [Names]
- **Last Updated**: [Date]
## Executive Summary
[2-3 sentences: What problem does this solve? What's the proposed solution?]
Background & Context
- Current pain points
- Why now?
- Related work
Goals
Primary Goals
- [Measurable goal]
Non-Goals
- [What this spec explicitly does NOT cover]
Functional Requirements
| ID |
Requirement |
Priority |
| FR-1 |
[Description] |
P0 |
| FR-2 |
[Description] |
P1 |
Non-Functional Requirements
- Performance: Response time < 200ms
- Scalability: Support 10K concurrent users
- Availability: 99.9% uptime
- Security: [Requirements]
Technical Design
Architecture
[Diagram or description]
API Design
POST /api/v1/resource
Request: { "field": "value" }
Response: { "id": "123", "field": "value" }
Database Schema
CREATE TABLE resources (
id UUID PRIMARY KEY,
field VARCHAR(255)
);
Implementation Plan
| Phase |
Timeline |
Deliverables |
| 1 |
Week 1-2 |
Core functionality |
| 2 |
Week 3 |
API endpoints |
| 3 |
Week 4 |
Testing & docs |
Testing Strategy
- Unit tests: 80% coverage
- Integration tests: API endpoints
- E2E tests: Critical flows
Risks & Mitigations
| Risk |
Probability |
Impact |
Mitigation |
| [Risk] |
Medium |
High |
[Plan] |
Success Criteria
- All P0 requirements implemented
- Tests passing
- Performance targets met
- Documentation complete
## Full Template
See [references/template.md](references/template.md) for a comprehensive copy-paste template including:
- Complete metadata section
- Success metrics tables
- Architecture diagrams
- Detailed API design sections
- Security threat analysis
- Monitoring & observability
- Risk assessment matrix
- Rollout and rollback plans
- Dependencies tracking
- Open questions section
## Best Practices
**Do:**
- Include measurable acceptance criteria
- Add architecture diagrams
- Define explicit API contracts
- Quantify performance targets
- Document risks and mitigations
- Get stakeholder review before implementation
- Include security considerations
- Define rollback procedures
**Don't:**
- Use vague requirements ("fast", "scalable")
- Skip non-functional requirements
- Ignore security considerations
- Leave alternatives unexplored
- Omit testing strategy
- Forget dependencies and risks
