// design.md
Generate technical design docs for your AI.
Fill the form. Get a structured design.md covering context, problem, solution, decisions, and data model — ready to paste into your LLM before it starts coding.
▶Optional sections (data model, API, UI, risks, metrics)
Preview updates as you type
// what is design.md
Brief your LLM before it starts coding.
A design.md is a structured design document you drop into your repo before asking an LLM to implement a feature. It answers the questions the model would otherwise guess at — what problem this solves, what decisions were already made, what the data model looks like.
Without a design doc, your LLM invents the architecture. With one, it implements the architecture you chose. That gap is the difference between a PR that needs a full rewrite and one that ships.
# user-auth-v2 — Design Doc
> Replace password auth with magic link
## Problem
Password resets account for 34% of support tickets.
Users forget passwords and churn rather than reset.
## Proposed Solution
Replace the password field with email-only login.
Send a time-limited magic link to the email address.
## Key Design Decisions
1. Tokens expire after 15 minutes (security)
2. One active token per user (invalidate on new request)
3. Email via Resend, not SMTP directly
## Data Model
```
User {
magicToken: string | null
magicTokenExpiry: Date | null
}
```// use cases
When do you need a design.md?
Before implementing a new feature
New featuresDrop design.md in your repo and reference it in your first prompt. Claude implements the architecture you chose — not one it invented from the function signature.
Explaining non-obvious decisions
ConstraintsLLMs optimise for common patterns. When your design deviates from the default (for good reasons), a design.md explains the constraint before the model 'fixes' your intentional choice.
Multi-session work
Long projectsContext windows reset. A design.md persists your decisions across every session — the model always knows what was decided without re-explaining it in every prompt.
Team collaboration with AI
TeamsWhen multiple engineers use the same LLM on the same feature, design.md makes sure all sessions start from the same design intent. No diverging implementations.
// faq
Frequently asked questions
How is design.md different from CLAUDE.md?
CLAUDE.md gives Claude context about your entire codebase — framework, commands, conventions. design.md is feature-specific: it documents the intent, decisions, and constraints for a single feature or implementation task.
How long should a design.md be?
Short enough to fit comfortably in context. 200–400 tokens is ideal. A design.md that fills the context window crowds out the actual code you're asking about. The generator intentionally keeps sections concise.
Where should I put the file?
Either in your repo root alongside CLAUDE.md, or in the relevant feature directory. Reference it in your first prompt: 'See user-auth-v2.md for the design context before implementing this.'
Do I need to fill in every section?
No. Name and Problem are the most important. The optional sections (data model, API design, risks) are only worth filling in when they capture a non-obvious decision the LLM would otherwise guess at incorrectly.