What is DESIGN.md?

DESIGN.md meaning

`DESIGN.md` is not a single official standard, but it is a useful convention. Teams use it to capture design intent, constraints, trade-offs, diagrams, user flows, data models, and architecture decisions in a plain-text file that can live beside the code.

What to include in DESIGN.md

• Problem statement
• Goals and non-goals
• User flows or system flows
• Architecture choices
• UI rules and component behavior
• Risks, trade-offs, and open questions
• Links to README.md, AGENTS.md, and implementation tasks

A simple DESIGN.md outline

# DESIGN.md

## Problem
What we are solving and for whom.

## Goals / Non-goals
- Goal: fast offline editing
- Non-goal: real-time collaboration

## Approach
Chosen architecture and why.

## Trade-offs
What we gave up and the risks.

## Open questions
Decisions still pending.

This outline keeps a design doc skimmable. Each heading answers one question, which makes it easy for reviewers and AI tools to follow the reasoning.

Why DESIGN.md helps AI agents

AI coding agents need intent, not just code. DESIGN.md explains why a feature should work a certain way. That helps an assistant make changes that match the product direction instead of only matching local syntax. Paired with an AGENTS.md file for operational rules and a CLAUDE.md file for session memory, DESIGN.md supplies the missing layer: the reasoning behind the build.

DESIGN.md vs ADR and RFC

Some teams record decisions as ADRs (Architecture Decision Records) or RFCs. DESIGN.md is lighter and more flexible: a single living document for the current design rather than a numbered log of past choices. For small projects, one DESIGN.md is often enough; larger teams may keep DESIGN.md for the big picture and ADRs for individual decisions.

DESIGN.md vs README.md

README.md introduces the finished project. DESIGN.md explains the decisions behind it. README is for usage; DESIGN is for reasoning and implementation guidance.

Preview design docs before sharing

Design docs often include tables, checklists, code snippets, and links. Use the online Markdown editor to preview them, then save as `DESIGN.md` with the desktop app if you work locally.

Related references

• GitHub Markdown syntax for Markdown formatting patterns.