DESIGN.md: Why Your Code Be Like This

Wetin DESIGN.md be, and wetin AGENTS.md no cover

DESIGN.md na markdown file for your repository root wey dey tell AI coding agent why dem shape the code the way e be. AGENTS.md dey answer another question: how to work for here. This one include the build command, the test command, the lint wey must pass, and the paths wey you no suppose touch. DESIGN.md dey record decisions wey don already settle, and wetin go break if person undo any of dem.

Coding agent, meaning tool like Claude Code or Cursor wey dey read and edit your repository by itself, normally get confidence. E fit see pattern wey e no recognise and try improve am. Hand-written cache fit turn to Redis (in-memory data store), because na so cache dey look for most of the code wey the model don read. AGENTS.md no stop this, because make test go pass either way. The rule wey break never dey written for anywhere wey the agent fit read am.

If you never write the first file, start from there. AGENTS.md and the HUMAN.md wey dey beside am explain the format and where each tool dey look for am. Wetin follow na the chapter after that one.

Wetin dey actually inside one published DESIGN.md

The fastest way to learn the format na to read files wey companies publish about themselves. The official-design-md repository dey track only those ones. E get one-line inclusion rule, and na that line be the main point of the collection:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

As of August 2026, e list seven: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel and VoltAgent. Each file dey for stable public URL, so you fit read one for terminal right now.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Both of dem na design system documents. Dem describe how product suppose look: colour, type, spacing, motion. Read beyond the subject matter, because the useful part na the shape of the writing, not the topic.

The Nuxt file get roughly 2,100 words, and most of am na rule plus the reason for the rule:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

The Vercel file long pass am, around 6,500 words for August 2026, and e go one step further. One of the headings na Reject generated-design reflexes. Under am, one list dey show wetin capable generator go normally choose when nobody tell am make e no do so:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

That sentence define the file type. Na written list of defaults wey confident model dey produce, published so the model go stop producing dem. Every DESIGN.md wey worth committing na that list for one domain.

Why companies dey publish their own DESIGN.md?

Community don start am first. awesome-design-md get 73 files wey dem reverse-engineer from public websites. Dem write each one with the same nine-section format, so you fit point agent to one and make e produce something wey resemble that design. Those files useful, but dem still na guesses. Nobody from the companies review dem.

First-party file different because na the source e be, instead of interpretation of the output. When Vercel change im type scale, vercel.com/design.md change with am. Copy wey dem scrape for March go still teach your agent the old scale. Nothing for your repository go tell you say the copy don stale.

Seven publishers na small number, and the repository talk am clearly: the standard new and official adoption dey grow. VoltAgent maintain both collections. VoltAgent na open source agent framework wey publish its own file too. So read the list as tracker, no be neutral census. E still worth monitoring because of who the seven be. Dem na the companies wey other developers copy their front-end code pass. Their files dey become worked example of wetin DESIGN.md be. Compare the path wey AGENTS.md take: agents.md now count over 60,000 open source projects wey dey use the format. Stewardship dey with the Agentic AI Foundation under the Linux Foundation. Conventions for agent-readable files dey settle quickly, and na top companies dey drive how dem settle.

Wetin go enter DESIGN.md when project no get user interface

Most software wey dey run for VPS no get visual language wey person need specify. The file still get value, because the mechanism no concern colour. Na to write down the constraints wey confident editor for otherwise break without noticing.

Invariants. Write one sentence for each one, to state wetin must remain true after any edit. "Every write dey pass through queue.enqueue(). Direct database write dey skip audit log, and na audit log compliance export dey read." Invariant wey include the reason go survive task wey you no anticipate. Invariant without reason dey look like preference, and dem fit optimise preferences away.

Rejected alternatives. The obvious option, plus why e no win. "We no use Redis for caching. The service dey run for one VPS, so in-process map dey faster and na one daemon less to keep alive. Revisit this when second application server dey available." Without that paragraph, if agent suppose make cache faster, e go add Redis, and e correct to do so: you never tell am about the constraint. Na this section dey justify the whole file.

Boundaries. These na places wey small edit fit affect plenty things. The database schema. The public route prefix wey customers don already script against. The config file wey deploy reads before application starts. The cron entry wey assume say na only one copy dey run. Name dem, and explain wetin change to each one go cost.

Vocabulary. If code talk tenant and team talk customer, write the mapping down. Agent wey guess wrong for here fit produce code wey reads well but models the wrong thing, and na the hardest kind mistake to notice during review.

A DESIGN.md wey you fit copy today

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Fill the two sections wey you fit write from memory today: invariants and rejected alternatives. Leave the remaining sections as headings. File wey get four honest lines dey work. File wey get forty guessed lines no dey work.

Some tools dey load every markdown file for repository root, while some dey load only the file wey dem tell am about, so no assume. Add pointer to AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

The anti-pattern: DESIGN.md wey dey repeat the README

The commonest bad version dey read well but e no teach anything. E dey start with wetin the project dey do, list the features, explain how to install am, then end with the licence. Every line for there don already dey inside README, and none of am talk why anything take be that way.

That one cost you two times. The first cost na context. You dey pay for file wey agent dey read at the beginning of every task for every task, and duplicated install section na pure overhead against fixed window. How you go budget that window na skill by itself, and how to manage the context window for Claude Code cover am. Short version be say: anything wey load automatically suppose be the text wey get the highest value for the repository.

The second cost worse. Two copies of the same statement fit drift apart. README talk say service dey listen on 8080, but DESIGN.md still talk say na 3000, and agent no get way to decide which one rank higher, so e pick one and write code around am. File wey sometimes dey wrong go dey consulted with the same confidence as file wey always dey correct.

The test quick. If paragraph fit sit comfortably inside README, cut am from DESIGN.md. Wetin remain suppose be the part wey you go talk out loud for code review, the part wey start with "we don try that one already".

How you fit know say the file dey work?

No linter dey for this. But one check dey wey you fit run within one minute.

Give the agent one task wey go directly touch an invariant. “Add one background job wey dey mark stale rows as expired.” File wey dey do im work go show for the answer before any code appear: the agent suppose tell you say the job dey write through queue.enqueue(), because direct write go skip the audit log. If e open database connection and write, one of two things dey true. Either the file no dey read at all, or the invariant wording loose reach so person fit argue with am.

Watch the token count too, because this file dey load for every turn. If context usage jump after you add DESIGN.md and the answers no improve, the file dey carry prose wey the agent already know. How to read token counters for Claude Code show where that budget dey go.

This one matter pass when the agent dey live for server instead of your laptop. Agent wey dey work for long-running session, like the setup for Claude Code workspace for VPS with tmux, no get memory of yesterday conversation. Na repository be the memory. Everything wey you explain for chat but never commit go disappear by the next session, and na DESIGN.md be the place wey that explanation go enter so e fit survive.

Start with the decisions wey una dey argue about

The first version go take twenty minutes. Open the last several pull requests wey reviewer write say, "no, na another way we dey do am here". Each of those comments na invariant wey nobody write down before, and each one na place wey agent go make the same mistake, faster and more often than person go. Add to the file whenever e fail you, no be according to schedule. If you still dey figure out where agents fit enter normal development workflow, the 2026 guide to learning AI agents na reasonable next step.

FAQ

DESIGN.md na official standard?

No be in the same way AGENTS.md be. AGENTS.md get home for agents.md, more than 60,000 open source projects dey use am, and Agentic AI Foundation dey manage am under Linux Foundation. As of August 2026, DESIGN.md no get governing body and no published specification. Wetin e get na first-party adoption: seven companies, including Vercel, Nuxt, Atlassian and Resend, publish one for public URL, and community collection get 73 more wey dem reverse-engineer from public sites. Treat am as convention wey you fit adopt now and extend freely, because nothing dey validate your section names.

DESIGN.md suppose just be one section inside AGENTS.md?

For small repository, yes. One file wey agent go surely read better pass two files where e fit ignore one. Split dem when AGENTS.md no longer easy to scan, or when you notice say the two parts dey change at different rates. AGENTS.md dey change when build dey change. DESIGN.md dey change when decision dey change, and that one dey happen less often but e carry more weight. When you split dem, add one line to AGENTS.md wey tell agent to read DESIGN.md before e edit code, because no be every tool dey load every markdown file for root.

How DESIGN.md different from architecture decision record?

ADR (architecture decision record) na dated record of one decision, and healthy project dey collect dozens of dem for one folder. That one na history, and history dey expensive to load, because agent go need read all of dem to know which ones still dey true. DESIGN.md na current state, and dem write am so agent fit read am complete for every task. Keep both if you already dey write ADRs. ADR dey talk wetin dem decide and when. DESIGN.md dey talk wetin dey true today, and na the one you point agent to.

How long DESIGN.md suppose be?

Make e short enough to load for every turn without regret. The published examples long because dem specify complete visual language: the Nuxt file na about 2,100 words and the Vercel file na about 6,500 as of August 2026. Backend service usually need much less. Start with one page, then grow am only when agent make mistake wey one sentence for prevent. Length no be the measure. Every line suppose be something wey agent for otherwise get wrong.