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 inside one published DESIGN.md

The fastest way to learn the format na to read the files wey companies publish about themselves. The repository official-design-md dey track only those ones. Its inclusion rule na one line, and that line na 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 October 2026, e lists eleven: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel and VoltAgent. Each file dey for public URL, most of dem for the publisher's own domain and the rest for public GitHub repository, 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, no be the topic.

The Nuxt file get roughly 2,000 words as of October 27, 2026, and most of am na rule with the reason attached. E start by stating say dark mode na the default theme. E list the brand green #00DC82 with note say the brand colours na "For logos, social images, and print. Do not use them as raw values in UI code." Near the end, one section wey get heading Reject these include:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

The Vercel file long pass am, roughly 6,000 words as of October 2026, and e go one step further. One of its headings na Reject generated-design reflexes. Under am, one list dey show wetin capable generator go reach for when nobody tell am make e no use dem:

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. E na written list of the defaults wey confident model dey produce, wey dem publish 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 reach there first. awesome-design-md get 84 files wey dem extract from public websites, according to the count for its README as of October 27, 2026. Each one follow the same nine-section format, so agent fit point to one and produce something close to that look. Those files useful, but na still guesses. Nobody from the companies review dem.

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

Eleven publishers still be 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 make you read the list as tracker, no be neutral census. E still worth monitoring because of the companies wey dey inside am. Several na companies wey other developers copy their front-end code pass, and the newer entries, Ant Design, Microsoft FAST, Juspay and Oxide Computer, na design systems wey other teams build on. Their files dey become the worked example of wetin DESIGN.md be. Compare the road wey AGENTS.md take: agents.md now count over 60,000 open source projects wey use the format, and Agentic AI Foundation under the Linux Foundation dey handle the stewardship. DESIGN.md don start to follow the same road. On April 21, 2026, Google make draft specification for the format open source, and publish am as google-labs-code/design.md, with token schema and CLI under Apache-2.0 licence. As of October 2026, the format dey for version alpha and development still active. Google Labs maintain am instead of neutral foundation, and e describe visual identity, so e no talk anything about the invariants wey backend file need. Conventions for files wey agents fit read dey settle quickly, and na people for 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 the way AGENTS.md be. AGENTS.md get home for agents.md, over 60,000 open source projects dey use am, and Agentic AI Foundation dey oversee am under Linux Foundation. DESIGN.md get published specification, but e no get neutral steward. Google make draft specification open source on April 21, 2026, and e dey for google-labs-code/design.md repository under Apache-2.0 licence. As of October 2026, e dey version alpha and development still dey active. E describe visual identity: colours, typography, layout and components. DESIGN.md also get first-party adoption: eleven companies and projects, including Vercel, Nuxt, Atlassian and Resend, publish one. Community collection don gather 84 more wey dem extract from public sites as of October 27, 2026. For backend file wey contain invariants and rejected alternatives, treat am as convention wey you fit adopt now and extend freely, because no specification cover those section names.

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

For small repository, yes. One file wey agent surely go read better pass two files wey one fit ignore. Split dem when AGENTS.md no dey easy to scan again, or when you notice say both halves 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 and get 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?

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

How long DESIGN.md suppose be?

E suppose short enough to load for every turn without regret. The published examples long because dem specify complete visual language: Nuxt file get roughly 2,000 words and Vercel file roughly 6,000 as of October 2026. Backend service usually need far less. Start with one page, then make am grow only when agent do something wrong wey one sentence for prevent. Length no be the measure. Every line suppose describe something wey agent for otherwise get wrong.