DESIGN.md: Wetin AGENTS.md No Tell Coding Agent

Wetín DESIGN.md be, and wetín AGENTS.md no cover

DESIGN.md na markdown file wey dey for the root of your repository. E tell AI coding agent why dem shape the code that way. AGENTS.md dey answer different question: how to work for here. This one include the build command, test command, lint wey must pass, and paths wey agent no suppose touch. DESIGN.md dey record decisions wey don already settle, plus wetín 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 assume say e fit act unless person stop am. 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 plenty code wey the model don read. AGENTS.md no stop this, because make test go still pass either way. The rule wey break never write down for anywhere wey agent fit read.

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. Wetín follow na the chapter after that one.

Wetin really dey 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. Its inclusion rule na one line, 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 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 with 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 long pass am, around 6,500 words for August 2026, and e go one step further. One of its headings na Reject generated-design reflexes. Under am, one list dey show the things wey 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 kind list for one domain.

Why companies dey publish their own DESIGN.md?

Community don reach there first. awesome-design-md get 73 files wey dem reverse-engineer from public websites. Each file follow the same nine-section format, so you fit point agent to one and make e produce something close to that design. Those files useful, but dem still be guesses. Nobody from the companies review dem.

First-party file different because na the source e be, not 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 still dey 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. E be open source agent framework wey publish its own file too, so read the list as tracker, not 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 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, and Agentic AI Foundation under the Linux Foundation dey handle the stewardship. 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 to specify. The file still dey useful, because the mechanism no concern colour. Na to write down the constraints wey confident editor fit otherwise break without noticing.

Invariants. Write one sentence for each one, and state something wey must remain true after any edit. "Every write must pass through queue.enqueue(). Direct database write dey skip audit log, and na audit log compliance export dey read." Invariant wey include the reason fit survive task wey you never expect. Invariant without reason dey look like preference, and people fit optimise preference comot.

Rejected alternatives. Write the obvious option and explain why una no choose am. "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." Without this paragraph, if agent dey asked to make cache faster, e go add Redis, and e correct to do so: you never tell am the constraint. Na this section dey justify the whole file.

Boundaries. Na the places where small edit fit affect plenty things. Database schema. Public route prefix wey customers don already script against. Config file wey deploy reads before application starts. Cron entry wey assume say only one copy dey run. Name dem, and explain wetin change to each one go cost. If agent fit also reach open web, through self-hosted SearXNG instance wey you connect as search backend, that one na boundary wey you suppose write down too, because the file need state which fetched text fit influence code and which one agent fit only 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 reads well but models the wrong thing. Na the hardest type of 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 dey work.

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

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

The bad pattern: DESIGN.md wey just repeat the README

The common bad version dey read well but e teach nothing. E 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 things dey that way.

That one cost you two times. The first cost na context. The agent dey read this file for the beginning of every task, so every task dey pay for am, and duplicated install section na pure extra load against fixed time window. To budget that window na skill by itself, and managing the context window for Claude Code cover am. The short version be say: anything wey load automatically suppose be the highest-value text for the repository.

The second cost worse. Two copies of the same statement fit drift apart. README say the service dey listen on 8080, DESIGN.md still say 3000, and the agent no get way to know which one carry more weight, so e pick one and write code around am. File wey sometimes dey wrong go get the same confidence when person consult am as file wey always dey correct.

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

File dey work how you go know?

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

Give the agent one task wey go enter one invariant directly. "Add a background job that marks stale rows as expired." File wey dey work go show for the answer before any code appear: agent suppose tell you say job dey write through queue.enqueue(), because direct write go skip audit log. If e open database connection and write, one of two things dey true. Either file no dey read at all, or invariant no clear enough and person fit argue with am.

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

This one matter pass when 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 go disappear before next session, and na DESIGN.md be the place to put that explanation so e fit survive.

Start na the decisions wey dey cause argument

The first version dey take twenty minutes. Open the last several pull requests where reviewer write say, "no, na different way we dey do am here". Every one of those comments na invariant wey nobody write down before. Every one na place where agent go make the same mistake, faster and more often than person fit. Add to the file when 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 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 as part of 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 surely go read better pass two files wey e fit ignore one. 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 change. DESIGN.md dey change when decision change, and this 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 gather 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 true. DESIGN.md na the current state, and dem write am so agent fit read the whole thing for every task. Keep both if you already dey write ADRs. ADR dey talk wetin dem decide and when. DESIGN.md dey talk wetin 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: Nuxt file get about 2,100 words and 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 be something wey agent for otherwise get wrong.