9 min read • Guide 758 of 877
Technical Specifications for Development
Good specifications prevent rework. GitScrum helps teams create and track technical specs that guide implementation effectively.
When to Write Specs
Spec Decision Tree
DO YOU NEED A TECHNICAL SPEC?
┌─────────────────────────────────────────────────────────────┐
│ │
│ Is this work significant? │
│ (> 1 week of work, multiple components, risky) │
│ │
│ YES NO │
│ ↓ ↓ │
│ Is cross-team coordination Is it well-understood? │
│ needed? │
│ YES → Task description │
│ YES → FULL SPEC NO → Mini-spec or RFC │
│ NO → Is it architecturally │
│ significant? │
│ │
│ YES → DESIGN DOC / ADR │
│ NO → MINI-SPEC │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ FULL SPEC: New features, system redesigns, integrations │
│ MINI-SPEC: Smaller changes needing clarity │
│ ADR: Architecture decisions │
│ TASK DESC: Well-understood, small work │
│ │
│ WHEN IN DOUBT: │
│ If you'd need to explain it to someone for > 5 minutes, │
│ write it down. │
└─────────────────────────────────────────────────────────────┘
Spec Structure
Technical Spec Template
TECHNICAL SPECIFICATION TEMPLATE:
┌─────────────────────────────────────────────────────────────┐
│ SPEC: User Export Feature │
├─────────────────────────────────────────────────────────────┤
│ │
│ Author: @alex │
│ Status: Draft → Review → Approved │
│ Date: 2024-01-15 │
│ Related Task: PROJ-123 │
│ │
│ ═══════════════════════════════════════════════════════════ │
│ │
│ 1. OVERVIEW │
│ ─────────── │
│ Brief summary of what this feature does and why. │
│ │
│ 2. BACKGROUND │
│ ──────────── │
│ Context: Why are we building this? │
│ Current state: How does it work today? │
│ Requirements source: Link to product requirements │
│ │
│ 3. GOALS & NON-GOALS │
│ ─────────────────── │
│ Goals: │
│ • What we're solving │
│ │
│ Non-goals: │
│ • What we're explicitly NOT solving │
│ • Future considerations │
│ │
│ 4. PROPOSED SOLUTION │
│ ──────────────────── │
│ High-level approach and architecture │
│ │
│ 5. DETAILED DESIGN │
│ ───────────────── │
│ API changes, data models, component interactions │
│ │
│ 6. EDGE CASES │
│ ───────────── │
│ What happens when...? │
│ │
│ 7. TESTING STRATEGY │
│ ────────────────── │
│ How will this be tested? │
│ │
│ 8. ROLLOUT PLAN │
│ ────────────── │
│ How will this be deployed and monitored? │
│ │
│ 9. OPEN QUESTIONS │
│ ──────────────── │
│ Decisions still needed │
│ │
│ 10. APPENDIX │
│ ─────────── │
│ Diagrams, API examples, references │
└─────────────────────────────────────────────────────────────┘
Detailed Design Section
DETAILED DESIGN EXAMPLE:
┌─────────────────────────────────────────────────────────────┐
│ 5. DETAILED DESIGN │
│ │
│ 5.1 API DESIGN │
│ │
│ New endpoint: │
│ POST /api/v1/exports │
│ │
│ Request: │
│ { │
│ "type": "users", │
│ "format": "csv", │
│ "filters": { │
│ "created_after": "2024-01-01" │
│ } │
│ } │
│ │
│ Response (202 Accepted): │
│ { │
│ "export_id": "exp_abc123", │
│ "status": "processing", │
│ "estimated_time": 30 │
│ } │
│ │
│ 5.2 DATA MODEL │
│ │
│ New table: exports │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ id | UUID | Primary key ││
│ │ user_id | UUID | FK to users ││
│ │ type | VARCHAR(50) | Export type ││
│ │ format | VARCHAR(10) | csv, xlsx ││
│ │ status | VARCHAR(20) | pending, processing, done││
│ │ file_url | TEXT | S3 URL when complete ││
│ │ expires_at | TIMESTAMP | Auto-delete after 7 days ││
│ │ created_at | TIMESTAMP | ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ 5.3 COMPONENT FLOW │
│ │
│ User request │
│ ↓ │
│ API validates and queues job │
│ ↓ │
│ Background worker processes export │
│ ↓ │
│ Upload to S3, update status │
│ ↓ │
│ Email user with download link │
│ │
└─────────────────────────────────────────────────────────────┘
Edge Cases
Documenting What-Ifs
EDGE CASE DOCUMENTATION:
┌─────────────────────────────────────────────────────────────┐
│ 6. EDGE CASES │
│ │
│ LARGE DATASETS │
│ ───────────── │
│ Scenario: User has 100K+ records to export │
│ Handling: Streaming export, chunked processing │
│ Limit: Max 500K records per export │
│ If exceeded: Return error, suggest filtering │
│ │
│ CONCURRENT EXPORTS │
│ ────────────────── │
│ Scenario: User requests multiple exports simultaneously │
│ Handling: Queue all, process in order │
│ Limit: Max 5 pending exports per user │
│ If exceeded: Return 429 Too Many Requests │
│ │
│ EXPORT IN PROGRESS │
│ ────────────────── │
│ Scenario: User logs out while export is processing │
│ Handling: Export continues, email sent when done │
│ │
│ DATA CHANGES DURING EXPORT │
│ ─────────────────────────── │
│ Scenario: Data changes while export is processing │
│ Handling: Snapshot at start of export (eventual consistency)│
│ Note: Document that export represents point-in-time │
│ │
│ EMPTY RESULTS │
│ ───────────── │
│ Scenario: Filter returns zero records │
│ Handling: Return empty file with headers │
│ UI: Show "No records match your criteria" │
│ │
│ SPECIAL CHARACTERS │
│ ────────────────── │
│ Scenario: Data contains commas, quotes, newlines │
│ Handling: Proper CSV escaping per RFC 4180 │
│ Test: Include test cases for special characters │
└─────────────────────────────────────────────────────────────┘
Review Process
Spec Review Workflow
SPEC REVIEW PROCESS:
┌─────────────────────────────────────────────────────────────┐
│ │
│ LIFECYCLE: │
│ │
│ [Draft] → [Review] → [Approved] → [Implemented] │
│ │
│ DRAFT: │
│ Author writes initial spec │
│ Share early, get feedback on direction │
│ │
│ REVIEW: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Reviewers: ││
│ │ • Tech lead (architecture) ││
│ │ • Security (if relevant) ││
│ │ • PM (requirements alignment) ││
│ │ • Anyone who'll implement ││
│ │ ││
│ │ Review checklist: ││
│ │ ☐ Solves the right problem? ││
│ │ ☐ Approach makes sense? ││
│ │ ☐ Edge cases covered? ││
│ │ ☐ Security considered? ││
│ │ ☐ Scalability addressed? ││
│ │ ☐ Testing strategy adequate? ││
│ │ ☐ Rollout plan reasonable? ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ APPROVED: │
│ Major concerns addressed │
│ Minor issues can be fixed during implementation │
│ Approval recorded in spec document │
│ │
│ IMPLEMENTED: │
│ Spec becomes documentation │
│ Update if implementation differs significantly │
│ │
│ GITSCRUM: │
│ Link spec to implementation tasks │
│ Subtask: "Write technical spec" (done before coding) │
└─────────────────────────────────────────────────────────────┘
Linking to GitScrum
Specs and Tasks
SPEC → TASK RELATIONSHIP:
┌─────────────────────────────────────────────────────────────┐
│ │
│ EPIC: User Export Feature (PROJ-120) │
│ ├── PROJ-121: Write technical specification │
│ │ └── Link: docs/specs/user-export.md │
│ │ │
│ ├── PROJ-122: Implement export API │
│ │ └── See spec section 5.1 for API design │
│ │ │
│ ├── PROJ-123: Background worker for export │
│ │ └── See spec section 5.3 for component flow │
│ │ │
│ ├── PROJ-124: Email notification on complete │
│ │ └── See spec section 5.3 │
│ │ │
│ └── PROJ-125: Test edge cases │
│ └── See spec section 6 for test cases │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ TASK DESCRIPTION PATTERN: │
│ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ PROJ-122: Implement export API ││
│ │ ││
│ │ Spec: [link to spec section 5.1] ││
│ │ ││
│ │ Implementation notes: ││
│ │ • POST /api/v1/exports endpoint ││
│ │ • Validate request, queue background job ││
│ │ • Return 202 with export_id ││
│ │ ││
│ │ See spec for detailed API contract and error handling ││
│ │ ││
│ │ Acceptance: ││
│ │ ☐ API matches spec ││
│ │ ☐ Error cases handled ││
│ │ ☐ Tests written ││
│ └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
Living Documents
Keeping Specs Updated
SPEC MAINTENANCE:
┌─────────────────────────────────────────────────────────────┐
│ │
│ DURING IMPLEMENTATION: │
│ │
│ If implementation differs from spec: │
│ • Minor differences: Note in PR, update spec after merge │
│ • Major differences: Pause, discuss, update spec first │
│ │
│ Update spec when: │
│ • Design changed during implementation │
│ • Edge cases discovered │
│ • API contract modified │
│ • New constraints found │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ AFTER IMPLEMENTATION: │
│ │
│ Spec becomes documentation: │
│ • Mark status as "Implemented" │
│ • Note any deviations from original │
│ • Link to actual code/docs │
│ • Keep for historical context │
│ │
│ SPEC HEADER UPDATE: │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Status: Implemented ││
│ │ Implemented: 2024-02-01 ││
│ │ Implementation PRs: #456, #467, #478 ││
│ │ Notes: Removed XLSX support (deferred to v2) ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ Specs are valuable historical record of decisions │
│ Don't delete - they explain why things are the way they are│
└─────────────────────────────────────────────────────────────┘