How to Write a Technical Spec for an App (AI-Ready)

TL;DR: A technical spec defines HOW your app works. It's different from a PRD (WHAT it does). AI coding tools need both to avoid hallucinations.

Table of Contents

1. What is a Technical Spec?
2. Technical Spec vs PRD
3. What to Include
4. The Structure
5. Writing Tips
6. Example Spec
7. Templates

---

What is a Technical Spec?

A technical specification documents the implementation details of your app:

• How the system is architected
• What technologies are used
• How components communicate
• What the data structures look like

It's the "how" to the PRD's "what."

---

Technical Spec vs PRD

Aspect	PRD	Technical Spec
Question	What to build?	How to build it?
Audience	Stakeholders, PMs	Developers, AI tools
Content	Features, user stories	Architecture, schemas, APIs
Changes	Rarely (scope lock)	More frequently

Why Both Matter for AI

AI tools need:

• PRD: To know what features to implement
• Tech Spec: To know how to implement them correctly

---

What to Include

Essential Sections

Section	Purpose
Architecture Overview	System components and connections
Tech Stack	Frameworks, libraries, versions
Database Schema	Tables, columns, relationships
API Specification	Endpoints, payloads, errors
Component Inventory	UI components and props
Integration Points	External services, webhooks

Optional Sections

• Performance requirements
• Security considerations
• Deployment topology
• Monitoring and logging

---

The Structure

# [Project Name] — Technical Specification

## 1. Overview

Brief description of the system.

## 2. Architecture

- System diagram
- Component descriptions
- Data flow

## 3. Tech Stack

| Category | Technology | Version |
| -------- | ---------- | ------- |
| Frontend | Next.js    | 14.x    |
| Database | PostgreSQL | 15      |

| ...

## 4. Database Schema

Tables, columns, relationships, DDL.

## 5. API Specification

Endpoints, request/response schemas, errors.

## 6. Component Inventory

UI components with props and states.

## 7. Security

Auth, authorization, data protection.

## 8. Deployment

Environments, CI/CD, infrastructure.

---

Writing Tips

1. Be Specific

❌ "The app should be fast" ✅ "API responses < 200ms p95"

2. Use Diagrams

graph LR
    A[Client] --> B[API]
    B --> C[Database]
    B --> D[External API]

3. Include Examples

Show request/response examples for APIs:

// POST /api/projects
{
  "name": "My Project",
  "description": "Optional description"
}

// Response
{
  "id": "uuid",
  "name": "My Project",
  "created_at": "2026-01-01T00:00:00Z"
}

4. Document Constraints

## Constraints

- Maximum 100 projects per user
- File uploads limited to 10MB
- API rate limit: 100 req/min

---

Example Spec

Abbreviated Example: Task Manager

# TaskFlow — Technical Specification

## Architecture

┌──────────────┐ ┌──────────────┐ │ Next.js │────▶│ Supabase │ │ Frontend │ │ Database │ └──────────────┘ └──────────────┘

## Tech Stack

| Category | Technology |
|----------|------------|
| Frontend | Next.js 14 |
| Database | Supabase (Postgres) |
| Auth | Supabase Auth |
| Styling | Tailwind + shadcn/ui |

## Database Schema

### tasks
| Column | Type | Notes |
|--------|------|-------|
| id | UUID | PK |
| title | TEXT | NOT NULL |
| completed | BOOLEAN | DEFAULT false |
| user_id | UUID | FK → users |

## API Endpoints

### POST /api/tasks
Create a new task.

Request:
```json
{ "title": "string" }

Response (201):

{ "id": "uuid", "title": "string", "completed": false }

Security

• All endpoints require authentication
• Users can only access their own tasks
• RLS policies enforce row-level security

---

## Templates 

### Get Started

- [Architecture Doc Template](/templates/architecture-doc-template)
- [Database Schema Template](/templates/database-schema-spec-template)
- [API Spec Template](/templates/api-spec-template-openapi-ai)
- [Full SDD Pack](/templates/spec-driven-development-template)

### Related Guides

- [Spec-Driven Development](/blog/spec-driven-development-for-ai-coding)
- [How to Stop Hallucinations](/blog/how-to-stop-ai-hallucinating-code)

---

> **Generate your tech spec automatically.** [Start with a brain dump →](/)

---

*Last updated: January 2026*