12 KiB
12 KiB
How to Create a Technical Requirement Specification
Technical Requirements (PRD or TRQ) translate business needs into specific, implementation-ready technical requirements. They bridge the gap between "what we want to build" (business requirements) and "how we'll build it" (design documents).
Quick Start
# 1. Create a new technical requirement
scripts/generate-spec.sh technical-requirement prd-001-descriptive-slug
# 2. Open and fill in the file
# (The file will be created at: docs/specs/technical-requirement/prd-001-descriptive-slug.md)
# 3. Fill in the sections, then validate:
scripts/validate-spec.sh docs/specs/technical-requirement/prd-001-descriptive-slug.md
# 4. Fix any issues, then check completeness:
scripts/check-completeness.sh docs/specs/technical-requirement/prd-001-descriptive-slug.md
When to Write a Technical Requirement
Use a Technical Requirement when you need to:
- Define specific technical implementation details for a feature
- Map business requirements to technical solutions
- Document design decisions and their rationale
- Create acceptance criteria that engineers can test against
- Specify external dependencies and constraints
Research Phase
Before writing, do your homework:
1. Research Related Specifications
Look for upstream and downstream specs:
# Find the business requirement this fulfills
grep -r "brd\|business" docs/specs/ --include="*.md" | head -20
# Find any existing technical requirements in this domain
grep -r "prd\|technical" docs/specs/ --include="*.md" | head -20
# Find design documents that might inform this
grep -r "design\|architecture" docs/specs/ --include="*.md" | head -20
2. Research External Documentation
Research relevant technologies and patterns:
# For external libraries/frameworks:
# Use the doc tools to get latest official documentation
# Example: research React hooks if implementing a frontend component
# Example: research database indexing strategies if working with large datasets
Ask yourself:
- What technologies are most suitable for this?
- Are there industry standards we should follow?
- What does the existing codebase use for similar features?
- Are there performance benchmarks or best practices we should know about?
3. Review the Codebase
- How have similar features been implemented?
- What patterns does the team follow?
- What libraries/frameworks are already in use?
- Are there existing utilities or services we can reuse?
Structure & Content Guide
Title & Metadata
- Title: Clear, specific requirement (e.g., "Implement Real-Time Notification System")
- Priority: critical | high | medium | low
- Document ID: Use format
PRD-XXX-slug(e.g.,PRD-001-export-api)
Description Section
Answer: "What technical problem are we solving?"
Describe:
- The technical challenge you're addressing
- Why this particular approach matters
- Current technical gaps
- How this impacts system architecture or performance
Example:
Currently, bulk exports run synchronously, blocking requests for up to 30 seconds.
This causes timeout errors for exports > 100MB. We need an asynchronous export
system that handles large datasets efficiently.
Business Requirements Addressed Section
Reference the business requirements this fulfills:
- [BRD-001] Bulk User Data Export - This implementation enables the export feature
- [BRD-002] Enterprise Data Audit - This provides the data integrity requirements
Link each BRD to how your technical solution addresses it.
Technical Requirements Section
List specific, measurable technical requirements:
1. **[TR-001] Asynchronous Export Processing**
- Exports must complete within 5 minutes for datasets up to 500MB
- Must not block HTTP request threads
- Must handle job queue with at least 100 concurrent exports
2. **[TR-002] Data Format Support**
- Support CSV, JSON, and Parquet formats
- All formats must preserve data types accurately
- Handle special characters and encodings (UTF-8, etc.)
3. **[TR-003] Resilience & Retries**
- Failed exports must retry up to 3 times with exponential backoff
- Incomplete exports must be resumable or cleanly failed
Tips:
- Be specific: Use numbers, formats, standards
- Make it testable: Each requirement should be verifiable
- Reference technical specs: Link to API contracts, data models, etc.
- Include edge cases: What about edge cases or error conditions?
Implementation Approach Section
Describe the high-level technical strategy:
**Architecture Pattern**
We'll use a job queue pattern with async workers. HTTP requests will create
an export job and return immediately. Workers process jobs asynchronously
and notify users when complete.
**Key Technologies**
- Job Queue: Redis with Bull library
- Export Service: Node.js worker process
- Storage: S3 for export files
- Notifications: Email service
**Integration Points**
- Integrates with existing User Service API
- Uses auth middleware for permission checking
- Publishes completion events to event bus
Key Design Decisions Section
Document important choices:
**Decision 1: Asynchronous Export vs. Synchronous**
- **Decision**: Use async job queue instead of blocking requests
- **Rationale**: Synchronous approach causes timeouts for large exports;
async improves reliability and user experience
- **Tradeoffs**: Adds complexity (job queue, worker processes, status tracking)
but enables exports for datasets up to 500MB vs. 50MB limit
Why this matters:
- Explains the "why" behind technical choices
- Helps future developers understand constraints
- Documents tradeoffs explicitly
Technical Acceptance Criteria Section
Define how you'll know this is implemented correctly:
### [TAC-001] Export Job Creation
**Description**: When a user requests an export, a job is created and queued
**Verification**: Unit test verifies job is created with correct parameters;
integration test verifies job appears in queue
### [TAC-002] Async Processing
**Description**: Export job completes without blocking HTTP request
**Verification**: Load test shows HTTP response time < 100ms regardless of
export size; export job completes within target time
### [TAC-003] Export Format Accuracy
**Description**: Exported data matches source data exactly (no data loss)
**Verification**: Property-based tests verify format accuracy for various
data types and edge cases
Tips for Acceptance Criteria:
- Each should be testable (unit test, integration test, or manual test)
- Include both happy path and edge cases
- Reference specific metrics or standards
Dependencies Section
Technical Dependencies
- What libraries, services, or systems must be in place?
- What versions are required?
- What's the risk if a dependency is unavailable?
- **Redis** (v6.0+) - Job queue | Risk: Medium
- **Bull** (v3.0+) - Queue library | Risk: Low
- **S3** - Export file storage | Risk: Low
- **Email Service API** - User notifications | Risk: Medium
Specification Dependencies
- What other specs must be completed first?
- Why is this a blocker?
- [API-001] Export Endpoints - Must be designed before implementation
- [DATA-001] User Data Model - Need schema for understanding export structure
Constraints Section
Document technical limitations:
**Performance**
- Exports must complete within 5 minutes
- p95 latency for export requests must be < 100ms
- System must handle 100 concurrent exports
**Scalability**
- Support up to 500MB export files
- Handle 1000+ daily exports
**Security**
- Only export user's own data (auth-based filtering)
- Encryption for files in transit and at rest
- Audit logs for all exports
**Compatibility**
- Support all major browsers (Chrome, Firefox, Safari, Edge)
- Works with existing authentication system
Implementation Notes Section
Key Considerations What should the implementation team watch out for?
**Error Handling**
- Handle network interruptions during export
- Gracefully fail if S3 becomes unavailable
- Provide clear error messages to users
**Testing Strategy**
- Unit tests for export formatting logic
- Integration tests for job queue and workers
- Load tests for concurrent export handling
- Property-based tests for data accuracy
Migration Strategy (if applicable)
- How do we transition from old to new system?
- What about existing data or users?
Writing Tips
Make Requirements Testable
- ❌ Bad: "Export should be fast"
- ✅ Good: "Export must complete within 5 minutes for datasets up to 500MB, with p95 latency under 100ms"
Be Specific About Trade-offs
- Don't just say "we chose Redis"
- Explain: "We chose Redis over RabbitMQ because it's already in our stack and provides the job persistence we need"
Link to Other Specs
- Reference business requirements this fulfills:
[BRD-001] - Reference data models:
[DATA-001] - Reference API contracts:
[API-001] - Reference design documents:
[DES-001]
Document Constraints Clearly
- Performance targets with specific numbers
- Scalability limits and assumptions
- Security and compliance requirements
- Browser/platform support
Include Edge Cases
- What happens with extremely large datasets?
- How do we handle special characters, encoding issues, missing data?
- What about rate limiting and concurrent requests?
Complete All TODOs
- Replace placeholder text with actual decisions
- If something is still undecided, explain what needs to happen to decide
Validation & Fixing Issues
Run the Validator
scripts/validate-spec.sh docs/specs/technical-requirement/prd-001-your-spec.md
Common Issues & Fixes
Issue: "Missing Technical Acceptance Criteria"
- Fix: Add 3-5 criteria describing how you'll verify implementation correctness
Issue: "TODO items in Implementation Approach (2 items)"
- Fix: Complete the architecture pattern, technologies, and integration points
Issue: "No Performance constraints specified"
- Fix: Add specific latency, throughput, and availability targets
Issue: "Dependencies section incomplete"
- Fix: List all required libraries, services, and other specifications this depends on
Check Completeness
scripts/check-completeness.sh docs/specs/technical-requirement/prd-001-your-spec.md
Decision-Making Framework
As you write the technical requirement, reason through:
-
Problem: What technical problem are we solving?
- Is this a performance issue, reliability issue, or capability gap?
- What's the current cost of not solving this?
-
Approach: What are the viable technical approaches?
- Pros and cons of each?
- What's the simplest approach that solves the problem?
- What does the team have experience with?
-
Trade-offs: What are we accepting with this approach?
- Complexity vs. flexibility?
- Performance vs. maintainability?
- Immediate need vs. future extensibility?
-
Measurability: How will we know this works?
- What specific metrics define success?
- What's the threshold for "passing"?
-
Dependencies: What must happen first?
- Are there blockers we need to resolve?
- Can parts be parallelized?
Example: Complete Technical Requirement
# [PRD-001] Asynchronous Export Service
**Priority:** High
## Description
Currently, bulk exports run synchronously, blocking HTTP requests for up to
30 seconds, causing timeouts for exports > 100MB. We need an asynchronous
export system that handles large datasets efficiently and provides job status
tracking to users.
## Business Requirements Addressed
- [BRD-001] Bulk User Data Export - Enables the core export feature
- [BRD-002] Enterprise Audit Requirements - Provides reliable data export
## Technical Requirements
1. **[TR-001] Asynchronous Processing**
- Export jobs must not block HTTP requests
- Jobs complete within 5 minutes for datasets up to 500MB
- System handles 100 concurrent exports
2. **[TR-002] Format Support**
- Support CSV, JSON formats
- Preserve data types and handle special characters
3. **[TR-003] Job Status Tracking**
- Users can check export job status via API
- Job history retained for 30 days
... [rest of sections follow] ...
Next Steps
- Create the spec:
scripts/generate-spec.sh technical-requirement prd-XXX-slug - Research: Find related BRD and understand the context
- Fill in sections using this guide
- Validate:
scripts/validate-spec.sh docs/specs/technical-requirement/prd-XXX-slug.md - Fix issues identified by validator
- Share with architecture/design team for design document creation