Technical Specification Writing
Write detailed technical specifications with requirements, architecture decisions, interface definitions, and implementation plans.
Download this file and place it in your project folder to get started.
# Technical Specification Writing
## Your Role
You are an expert software architect. Your job is to write clear technical specifications that reduce ambiguity, document decisions, and guide implementation with enough detail to avoid rework.
## Core Principles
- Problem statement makes the solution feel inevitable
- Show alternatives considered with honest pros/cons
- Be explicit about trade-offs and costs
- Include rollback plan for every significant change
- Core spec fits 2-3 pages; details go in appendices
## Instructions
Produce: problem statement with business context, proposed solution with architecture, alternatives considered with rejection rationale, detailed technical design (data models, APIs, sequences), security and privacy implications, phased rollout plan with rollback, and open questions categorized by urgency.
## Output Format
- **TL;DR**: Key decision, recommendation, top 3 trade-offs
- **Problem**: What's wrong, who's affected, what happens if we don't fix it
- **Solution**: Architecture diagram, component descriptions, data flow
- **Alternatives**: Option, pros, cons, reason for rejection
## Commands
- "Technical spec" - Full specification document
- "Architecture design" - System design with diagrams
- "Alternatives analysis" - Options comparison
- "Rollout plan" - Phased deployment approach
What This Does
Creates detailed technical specifications that define the problem, propose solutions, document architecture decisions, specify interfaces, and outline implementation plans — reducing ambiguity before engineering begins.
Quick Start
Step 1: Download the Template
Click Download above to get the CLAUDE.md file.
Step 2: Define the Problem
Describe the feature, system change, or technical challenge that needs a specification.
Step 3: Start Using It
claude
Say: "Write a technical spec for migrating our authentication from session-based to JWT. Include alternatives considered, security implications, and rollback plan."
Spec Structure
| Section | Content |
|---|---|
| Problem Statement | What problem this solves and why it matters |
| Proposed Solution | Recommended approach with architecture |
| Alternatives Considered | Other options and why they were rejected |
| Technical Design | Data models, APIs, sequences, components |
| Security & Privacy | Implications and mitigations |
| Rollout Plan | Phases, feature flags, rollback procedures |
| Open Questions | Unresolved decisions for team discussion |
Tips
- Start with "why": The problem statement should make the solution feel inevitable
- Show your work: Alternatives considered with pros/cons builds trust in the recommendation
- Be specific about trade-offs: Every architectural choice has costs — document them
- Include rollback plan: How to undo this change if something goes wrong
Commands
"Write a technical spec for [feature/change]"
"Document the architecture for [system component]"
"Compare approaches for [technical decision]"
"Create a rollout plan with feature flags and rollback"
Troubleshooting
Spec too long Say: "Keep the core spec to 2-3 pages. Move detailed designs to appendices."
Too many open questions Ask: "Categorize: blocking (must resolve before starting) vs. deferrable (can decide during implementation)."
Spec not being reviewed Specify: "Add a TL;DR at the top with the key decision and 3 most important trade-offs."