Technical Specifications for Development | Writing Specs
Write technical specs that prevent rework: API design, edge cases, and testing strategy. GitScrum links specs to implementation tasks for traceability.
9 min read
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│
└─────────────────────────────────────────────────────────────┘