DESIGN.md: File Wey Come After AGENTS.md

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 that way. 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 make you leave alone. 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, dey confident by default. E go see pattern wey e no recognise and try improve am. Hand-written cache fit become Redis (an in-memory data store), because na so cache dey look for most code wey model don read. AGENTS.md no stop this, because make test dey pass either way. The rule wey break no dey written anywhere wey agent fit read.

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

Wetin dey actually inside published DESIGN.md

The fastest way to learn the format na to read the files wey companies publish about demself. The repository official-design-md dey track only those ones. Its inclusion rule na one line, and na that line be the whole 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 one 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 wey get the reason attached:

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 longer, around 6,500 words for August 2026, and e go one step further. One of its headings na Reject generated-design reflexes. Under am dey list of wetin capable generator go normally choose when nobody tell am not to:

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 the 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.

Wetin make companies publish their own DESIGN.md?

The community reach there first. awesome-design-md get 73 files wey dem reverse-engineer from public websites. Each one follow the same nine-section format. So agent fit use one to produce something close to that design. Those files useful, but na still guesses. Nobody from the companies review dem.

First-party file different because na the source, no be interpretation of the output. When Vercel change its 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 become stale.

Seven publishers no plenty, 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 publishers be. Dem be the companies wey other developers copy their front-end code pass. Their files dey become the practical example of wetin DESIGN.md be. Compare the path wey AGENTS.md take: agents.md now count more than 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 the top dey set the direction.

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 get anything to do with colour. Na to write down the constraints wey confident editor fit otherwise break without noticing.

Invariants. Write one sentence for each one. Each sentence must state something wey must remain true after any edit. "Every write goes through queue.enqueue(). Direct database write dey skip audit log, and na audit log compliance export dey read." Invariant wey get the reason join am fit survive task wey you never expect. Invariant wey stand alone sound like preference, and people fit optimise preferences comot.

Rejected alternatives. Write the obvious option and why e no win. "We no use Redis for caching. 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." Without this paragraph, if agent get instruction to make cache faster, e go add Redis, and e go dey correct to do am: you never tell am the constraint. Na this section dey justify the whole file.

Boundaries. Na the places where small edit fit cause big blast radius. Database schema. Public route prefix wey customers don already script against. Config file wey deployment dey read before application start. Cron entry wey assume say only one copy dey run. Name dem, then explain wetin change to each one go cost. If agent fit also reach open web through self-hosted SearXNG instance wey you wire as its search backend, write that one down as boundary too, because file suppose state which fetched text fit influence code and which one na only text wey agent fit quote back to you.

Vocabulary. If code dey call am tenant and team dey call am customer, write the mapping down. Agent wey guess wrong for here fit produce code wey read well but model the wrong thing. 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 rest as headings. File wey get four honest lines dey work. File wey get forty guessed lines no go work. If repository hold several packages, one root file no go fit all of dem. The same per-directory split wey work for nested AGENTS.md files for monorepo apply here: short root file for decisions wey everything share, plus smaller file beside each package wey get its own decisions.

Some tools dey load every markdown file for repository root, while some dey load only the one 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 README

The common bad version dey read fine 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 README, and none of dem explain why anything be the way e be.

That one cost you two times. The first cost na context. You dey pay for file wey agent read for the beginning of every task on every task, and duplicated install section na pure overhead against fixed window. To budget that window na skill by itself, and manage context window for Claude Code cover am. The short version be say: anything wey load automatically suppose be the text wey get the highest value for 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 know which one to trust more. So e go pick one and write code around am. File wey sometimes dey wrong go get the same level of confidence as file wey always dey correct.

The test quick. If paragraph fit sit comfortably for README, comot 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 before".

How you fit know say the file dey work?

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

Give the agent one task wey go enter an invariant directly. "Add a background job wey go mark stale rows as expired." File wey dey do im work go show for the answer before any code: 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 enough for person to argue about am.

Watch the token count too, because dem dey load this file 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. Repository na the memory. Everything wey you explain for chat but never commit don disappear by the next session, and na DESIGN.md be the place to put that explanation 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 where reviewer write "no, na different way we dey do am here". Each of these comments na invariant wey nobody write down before, and each one na place wey agent go make the same mistake, faster and more often pass person. Add to the file anytime 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 oversee 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 one 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 section inside AGENTS.md?

For small repository, yes. One file wey agent go surely read better pass two files wey agent fit ignore one. Split dem when AGENTS.md no dey easy to scan again, or when you notice say the two halves dey change at different rates. AGENTS.md dey change when build change. DESIGN.md dey change when decision change, and that one dey happen less often and carry more weight. When you split dem, add one line to AGENTS.md wey tell agent make e 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 inside one folder. That one na history, and history cost plenty to load, because agent go need read all of dem to work out which ones still dey true. DESIGN.md na the current state, and dem write am so agent fit read am complete for every task. Keep both if you already dey write ADRs. ADR talk wetin dem decide and when. DESIGN.md talk wetin dey true today, and na the one wey 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 get about 2,100 words and the Vercel file about 6,500 as of August 2026. Backend service usually need much less. Start with one page, and grow am only when agent do something wrong wey one sentence for DESIGN.md for prevent. Length no be the measure. Every line suppose describe something wey agent for otherwise do wrong.