Technical Spec Templates
A collection of technical specification templates covering RFCs, architecture decision records (ADRs), API specifications, system design documents, and review checklists. Built for PMs who work closely with engineering and need to participate in technical discussions effectively.
Key Features
- RFC Template — Request for Comments format for proposing technical changes
- Architecture Decision Records — Lightweight ADR format for documenting decisions
- API Specification Template — RESTful API spec with endpoint documentation
- System Design Document — Full system design template with diagrams guidance
- Technical Review Checklist — Pre-review checklist for completeness and quality
- Migration Spec Template — Data and system migration planning document
What's Included
| File | Purpose |
|---|---|
templates/rfc-template.md |
Request for Comments document |
templates/adr-template.md |
Architecture Decision Record |
templates/api-spec.md |
API specification with endpoints |
templates/system-design.md |
System design document |
templates/migration-spec.md |
Migration planning document |
templates/review-checklist.md |
Technical review checklist |
templates/runbook-template.md |
Operational runbook for new systems |
configs/development.yaml |
Development review workflow config |
configs/production.yaml |
Production review and approval config |
Quick Start
- Identify your document type — RFC for proposals, ADR for decisions, API spec for interfaces
- Copy the matching template from
templates/ - Fill in the metadata header (author, reviewers, status, date)
- Write the proposal or specification following the template structure
- Run through
templates/review-checklist.mdbefore requesting review
Template Examples
RFC Header and Structure
RFC-0042: Migrate Authentication to OAuth 2.0
Author: @engineer-name
Status: DRAFT | IN REVIEW | ACCEPTED | REJECTED | SUPERSEDED
Created: 2026-03-23
Reviewers: @security-lead, @platform-lead, @pm-name
Decision: [To be filled after review]
## Summary
One paragraph: what are you proposing and why?
## Motivation
Why is the current approach insufficient? What problem does this solve?
Include data: error rates, support tickets, performance metrics.
## Detailed Design
How will this work? Include:
- Architecture changes
- Data model changes
- API changes
- Migration path
## Alternatives Considered
| Approach | Pros | Cons | Effort |
|-----------------|-------------------|---------------------|----------|
| OAuth 2.0 | Industry standard | Migration complexity| 6 weeks |
| Custom JWT | Full control | Maintenance burden | 4 weeks |
| Keep current | No work | Scaling issues | 0 weeks |
## Rollout Plan
Phase 1: [scope] — [timeline]
Phase 2: [scope] — [timeline]
Rollback: [how to revert if needed]
## Open Questions
1. [Question that needs resolution before approval]
2. [Question that can be resolved during implementation]
Architecture Decision Record (ADR)
ADR-0015: Use PostgreSQL for Event Storage
Status: ACCEPTED
Date: 2026-03-23
Deciders: @eng-lead, @platform-lead, @pm-name
## Context
We need a storage solution for user event data. Current volume
is 50M events/day with 90-day retention. Query patterns are
primarily time-range scans with user-level filtering.
## Decision
We will use PostgreSQL with TimescaleDB extension for event storage.
## Consequences
Positive:
- Team has deep PostgreSQL expertise
- TimescaleDB handles time-series queries efficiently
- Existing backup and monitoring infrastructure applies
Negative:
- May need to revisit at 500M events/day
- Requires partition management for retention policy
- Higher storage cost than object storage alternatives
## Alternatives Rejected
- ClickHouse: Better performance but no team expertise
- S3 + Athena: Cheapest storage but query latency too high
- Kafka + Druid: Over-engineered for current scale
API Specification Entry
## POST /api/v2/users/{user_id}/preferences
Update user preferences.
Authentication: Bearer token (scope: user:write)
Rate Limit: 100 requests/minute per user
### Path Parameters
| Parameter | Type | Required | Description |
|-----------|--------|----------|----------------------|
| user_id | string | yes | UUID of the user |
### Request Body
{
"theme": "dark",
"notifications": {
"email": true,
"push": false,
"frequency": "daily"
},
"timezone": "America/New_York"
}
### Response — 200 OK
{
"user_id": "usr_abc123",
"preferences": { ... },
"updated_at": "2026-03-23T10:30:00Z"
}
### Error Responses
| Code | Meaning | When |
|------|----------------------|--------------------------------|
| 400 | Invalid request | Malformed body or invalid enum |
| 401 | Unauthorized | Missing or expired token |
| 404 | Not found | User ID does not exist |
| 429 | Rate limited | Exceeded 100 req/min |
Usage Guide
- RFCs for Proposals: Use when proposing a change that affects multiple teams or has significant risk. The RFC process creates a written record of reasoning and alternatives.
- ADRs for Decisions: Use after a decision is made. ADRs are short (1 page max) and explain context, decision, and consequences. Your future self will thank you.
- API Specs Before Code: Write the API spec before implementing. Share with consumers for feedback. This prevents expensive redesigns.
- Review Checklists: Run through the checklist before requesting review. Reviewers should focus on design, not formatting.
Best Practices
- Write for the reader who joins in 6 months — they need context you take for granted today
- ADRs are immutable — if a decision changes, write a new ADR that supersedes the old one
- Include "Alternatives Considered" — this is the most valuable section; it shows WHY you chose this path
- API specs are contracts — breaking changes need versioning; document what is stable vs. experimental
- Keep RFCs focused — one RFC per proposal; don't bundle unrelated changes
- Link to related documents — PRDs, design docs, and previous ADRs provide essential context
This is 1 of 11 resources in the PM Toolkit Pro toolkit. Get the complete [Technical Spec Templates] with all files, templates, and documentation for $25.
Or grab the entire PM Toolkit Pro bundle (11 products) for $129 — save 30%.
Top comments (0)