Google standardized UI design with DESIGN.md. DevMD standardizes all of software development with .md files.
You fill in markdown. AI builds the product.
Every AI coding session starts the same way: explain your product, describe the schema, clarify the API patterns, define the error codes, specify the auth flow — over and over. Each session burns thousands of tokens re-establishing context that should already exist.
Meanwhile, teams scatter specs across Notion, Confluence, Figma, Slack threads, and developer brains. AI can't read any of it.
25 markdown files that define your entire software project.
One file per concern. YAML frontmatter for machines, markdown body for humans. Drop them in your repo root. Every AI tool — Claude, Cursor, Copilot, Codex — reads them instantly.
You don't write 25 files. AI does. npx devmd scan analyzes your codebase and generates all files. You review and correct. AI builds from them. More structured templates = fewer tokens per session = better output.
your-project/
│
│ ── Product ──
├── PRODUCT.md # Vision, users, value proposition
├── GLOSSARY.md # Domain terms (DDD ubiquitous language)
├── BRAND.md # Voice, tone, copy rules
│
│ ── Structure ──
├── ARCHITECTURE.md # System structure, layers, dependencies
├── SCHEMA.md # Database tables, relations, indexes
├── API.md # Endpoints, error format, versioning
├── ERRORS.md # Error codes, exception hierarchy, retry policy
├── LOGGING.md # Log levels, structured format, tracing
│
│ ── Interface ──
├── DESIGN.md # Visual tokens (Google standard)
├── UI.md # Frontend structure, layouts, components
├── SCREENS.md # Visual reference per screen and state
├── FLOWS.md # UX journeys + data flow chains
├── SEO.md # SEO + GEO strategy
│
│ ── Quality ──
├── TESTING.md # Test pyramid, coverage, scope
├── SECURITY.md # Auth, OWASP checklist, secrets
│
│ ── Operations ──
├── INFRA.md # Infrastructure intent (WHAT, not HOW)
├── CONFIG.md # Environment variables, provider matrix, feature flags
├── DEVOPS.md # CI/CD, build, deploy, backup pipelines
├── OPERATIONS.md # Incident runbooks, SLOs, on-call, escalation
├── CHANGELOG.md # Version history, breaking changes, migration paths
│
│ ── AI & Agents ──
├── CLAUDE.md # Coding conventions (Anthropic standard)
├── AGENTS.md # AI agent persona & instructions (AAIF standard)
├── HARNESS.md # Agent control: LLM, RAG, tools, guardrails, memory
├── RUNTIME.md # Job/process execution spec
│
│ ── Control ──
└── LIFECYCLE.md # State machines, phase transitions, conflict detection
An empty template asks "did you define this?" for every section. Items exist, so nothing gets missed. A blank ERRORS.md with 6 empty sections is more valuable than no file at all — it tells you what you haven't decided yet.
Write type: card-feed and AI already knows the grid, spacing, responsive behavior, empty state, and loading skeleton. One line replaces ~500 tokens of detailed specification. Across a project, this saves thousands of tokens per session.
@SCHEMA.md#users in your API.md points to the single source of truth. Change it once, every reference stays current.
The same concept will appear in multiple files — and that's by design. A "Recipient" shows up in GLOSSARY.md (definition), SCHEMA.md (table structure), API.md (endpoint parameters), FLOWS.md (signing journey), UI.md (component), and SCREENS.md (visual). Each file describes it from a different perspective:
| File | Perspective on "Recipient" |
|---|---|
| GLOSSARY.md | What it means in the domain |
| SCHEMA.md | How it's stored |
| API.md | How it's accessed |
| SECURITY.md | What permissions it requires |
| FLOWS.md | When it appears in the journey |
| UI.md | Where it's shown on screen |
| SCREENS.md | What it looks like |
This overlap is valuable. Each perspective serves a different reader (PM, backend dev, frontend dev, security engineer) and a different AI task (schema migration, API generation, UI rendering).
But contradiction is not. If GLOSSARY.md says a Recipient can have 5 roles and SCHEMA.md defines 4, that's a conflict — one of them is wrong, and AI will produce inconsistent code.
When authoring DevMD files, run conflict checks between overlapping sections. When a conflict is found:
- Identify — Flag the two (or more) sources that disagree
- Surface — Present both versions to the author with context
- Resolve — Author picks the canonical version; other files update to match
- Reference — The resolved fact lives in one primary file; others use
@FILE.md#section
The primary home for each type of fact:
| Fact Type | Primary Home | Other Files Reference It |
|---|---|---|
| Term definition | GLOSSARY.md | All files |
| Table structure | SCHEMA.md | API.md, ERRORS.md |
| Visual tokens | DESIGN.md | UI.md, SCREENS.md |
| Auth rules | SECURITY.md | API.md, INFRA.md |
| Error codes | ERRORS.md | API.md, LOGGING.md |
| User journey | FLOWS.md | UI.md, SCREENS.md |
| Env config | INFRA.md | RUNTIME.md, SECURITY.md |
Already established by industry leaders. DevMD adopts them as-is.
| File | Origin | Domain |
|---|---|---|
| CLAUDE.md | Anthropic | Coding conventions + project rules |
| AGENTS.md | AAIF (Linux Foundation) | AI agent instructions |
| DESIGN.md | Google Labs (2024) | UI design tokens |
Filling gaps no standard has addressed.
| File | Domain |
|---|---|
| PRODUCT.md | Product vision, target users, success criteria |
| GLOSSARY.md | Domain vocabulary (DDD ubiquitous language) |
| ARCHITECTURE.md | System structure, layers, ADRs |
| SCHEMA.md | Database tables, relations, migrations |
| API.md | Endpoints, error format, versioning |
| ERRORS.md | Error codes, retry policy, user messages |
| LOGGING.md | Log levels, structured format, tracing |
| TESTING.md | Test pyramid, coverage, scope |
| SECURITY.md | Auth, OWASP, secrets policy |
| BRAND.md | Voice, tone, copy rules |
| FLOWS.md | UX journeys + backend data chains |
| SCREENS.md | Visual reference per screen and state |
| CONFIG.md | Environment variables, provider matrix, feature flags |
| DEVOPS.md | CI/CD pipelines, build, deploy, backup |
| OPERATIONS.md | Incident runbooks, SLOs, on-call, escalation |
| CHANGELOG.md | Version history, breaking changes, migration paths |
Categories where no one has proposed a standard yet. DevMD is the first.
| File | Domain | Why It's Empty |
|---|---|---|
| UI.md | Frontend structure, layouts, component patterns | DESIGN.md covers visuals only; structure had no spec |
| SEO.md | SEO + GEO (AI search optimization) | SEO was tools and practices, never a declarative spec |
| INFRA.md | Infrastructure intent definition | Terraform is HOW (code); the WHAT (intent) had no spec |
| HARNESS.md | Agent control infrastructure | Agent definitions (AGENTS.md) exist; control plane spec didn't |
| LIFECYCLE.md | State-driven control and transitions | Static specs exist; dynamic state management didn't |
| RUNTIME.md | Agent/job execution specification | Agent definitions exist (BMAD); execution specs didn't |
PRODUCT.md ── GLOSSARY.md ── BRAND.md ──────────── Why we build + what we call things
ARCHITECTURE.md ── SCHEMA.md ── API.md ─────────── How it's structured
│ │ │
ERRORS.md ── LOGGING.md ── TESTING.md ──────────── How it behaves
│
SECURITY.md ── INFRA.md ── CONFIG.md ───────────── How it's secured + configured
│
DEVOPS.md ── OPERATIONS.md ── CHANGELOG.md ─────── How it's operated
DESIGN.md ── UI.md ── SCREENS.md ───────────────── How it looks (tokens → structure → result)
│ │ │
FLOWS.md ── SEO.md ─────────────────────────────── How it moves + speaks
CLAUDE.md ── AGENTS.md ── HARNESS.md ───────────── How AI works with it
│ │
RUNTIME.md ── LIFECYCLE.md ──────────────────────── How it runs + transitions
We documented two real open-source projects — Twenty CRM (44K stars, full-stack) and Documenso (9K stars, document signing) — using 17 files and performed a rigorous gap analysis.
106 gaps found. Adding 8 files resolved 93% of them.
| Gap Type | Count | Root Cause | Solved By |
|---|---|---|---|
| End-to-end flows fragmented | 25 | No file owned the full journey | FLOWS.md |
| State transitions undocumented | 12 | Static specs, no dynamic control | LIFECYCLE.md |
| Env vars / config matrix missing | 10 | No structured config spec | CONFIG.md |
| Deployment / operations gaps | 10 | No ops perspective | DEVOPS.md + OPERATIONS.md |
| Agent control plane missing | 8 | AGENTS.md = persona only | HARNESS.md |
| Visual reference missing | 5 | Tokens ≠ rendered result | SCREENS.md |
| Evolution history lost | 3 | Current-state snapshots only | CHANGELOG.md |
| Depth insufficient in existing | 34 | Files need more detail | Existing file expansion |
The remaining 7% are runtime-specific implementation details that belong in code, not specs. Full analysis →
Not you. AI does.
npx devmd scan → AI analyzes your codebase, generates 25 files
You → Review, correct, fill in business context
AI → Reads DevMD files, builds features with full context
This is exactly what we did with Twenty and Documenso: AI scanned the projects and generated 17 files (8,982 lines) automatically. The 25-file set gives AI more structure, which means fewer tokens per session and more accurate output.
You don't need all 25 files. Pick a tier:
| Tier | Files | Use When |
|---|---|---|
| Starter (8) | PRODUCT, DESIGN, UI, SEO, BRAND, CLAUDE, SCREENS, INFRA | Static sites, landing pages |
| App (16) | + SCHEMA, API, ERRORS, SECURITY, TESTING, LOGGING, FLOWS, ARCHITECTURE | SaaS, web apps |
| AI-Native (21) | + AGENTS, HARNESS, LIFECYCLE, RUNTIME, CONFIG | AI-powered products |
| Enterprise (25) | + DEVOPS, OPERATIONS, CHANGELOG, remaining | Full-stack teams at scale |
claude plugin install devmd@ww-w-ai/devmd-guide # Interactive walkthrough — pick tier, answer questions, generate files
/devmd-guide app # Start with App tier (16 files)
/devmd-guide SCHEMA.md # Write a single file
The guide walks you through 7 waves in dependency order, asking 3–5 questions per file. You answer, AI writes the spec.
/devmd-scan # Analyze codebase, generate all files for detected tier
/devmd-scan SCHEMA.md # Generate a single file
/devmd-gap-analysis # Full coverage + accuracy + consistency check
/devmd-gap-analysis SCHEMA.md # Single file
/devmd-gap-analysis --consistency-only # Cross-file conflict detection only
Real-world projects documented with DevMD:
| Project | Stars | Type | Files | Lines |
|---|---|---|---|---|
| Twenty CRM | ~44K | Full-stack CRM | 25 | ~6,000 |
| Documenso | ~9K | Document signing | 25 | ~5,500 |
Google DESIGN.md = One file for design tokens
BMAD-METHOD = Agent definition best practices
Kiro (AWS) = IDE-locked 3-file system ($20-200/mo)
specs.md (fabriqai) = Methodology framework
DevMD = Open standard covering all of software development
Free. Tool-agnostic. 25 files.
A typical AI coding session spends ~4,000 tokens per page re-establishing context. With DevMD:
type: card-feed→ AI knows grid + spacing + empty state + loading (~500 tokens saved)@SCHEMA.md#users→ No need to re-describe the table (~200 tokens saved)- 25 files loaded once → Every subsequent task starts with full context
For a 10-page app with 20 AI sessions: ~80,000 tokens saved. That's real money and real time.
DevMD is an open standard. We want every framework, every AI tool, and every team to adopt it — but only if it actually works.
The best way to contribute: pick a real project and document it with DevMD. Then tell us what was missing, what was redundant, and what you'd change.
MIT
DevMD is a ww-w.ai project. Mission: "Do it once, share with all."