DESIGN.md explained
What is DESIGN.md?
DESIGN.md is a Markdown design document that records product, UI, architecture, or technical decisions before implementation.
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
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.
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.
FAQ
Is DESIGN.md a required file?
No. DESIGN.md is a convention, not a requirement. It is useful when a project needs persistent design or architecture context.
Should DESIGN.md include diagrams?
Yes, if they help. You can link images, use Mermaid where supported, or describe flows in tables and lists.
Can AI tools write DESIGN.md?
AI tools can draft design docs, but humans should review goals, trade-offs, constraints, and product decisions before implementation.