AGENTS.md is where coding agents look for a project's rules. What a design system should put there, what to leave out, and what npx once-ui-init-agent writes for you.
Most coding agents read a file at the root of your project before they touch it. Codex, Cursor, Copilot, Gemini CLI and Zed read AGENTS.md. Claude Code reads CLAUDE.md. Whatever is in that file is the first thing the agent knows about your project, every session.For a design system that is the most valuable spot in the repository. It is also easy to waste.
Why the file matters for UI
An agent without design rules writes UI the way the average of its training data writes UI: utility classes, a div with a border, a hex colour that looks close enough. Every screen is plausible and none of them match.The rules that prevent that are short. Use these components, not raw HTML. Use these spacing tokens, not pixel values. Pair a background with its matching foreground. Import the provider from here, not there. They fit on one screen, and an agent that has read them makes far fewer of the mistakes a reviewer would otherwise catch by hand.
What to put in it
A pointer, not the manual. Every file an agent reads is sent again on every later turn of the conversation, so a long AGENTS.md costs you on every message. Keep the section short and point at the detailed files the agent should open for the task at hand.The task routes. "Building a pricing page? Read this bundle." An agent that goes straight to the right reference reads less and guesses less.The two or three rules that break silently. In Once UI, the clearest one is that a Next.js app must import LayoutProvider from @once-ui-system/core/next. Nothing errors without it, but internal links reload the page. Rules like that belong in the file itself, because an agent will never find them by trial.How to check the work. The command that validates a file, so the agent runs it before it says it is done.
What to leave out
The full component reference, the props of every component, and anything the agent can read from the types. Those belong in files the agent opens when it needs them, not in the one it reads every time.
What once-ui-init-agent writes
npx once-ui-init-agent
It writes a Once UI section into AGENTS.md and CLAUDE.md and adds a Cursor rule. The section sits between markers, so the rest of your file stays as it is and a second run changes nothing. If your CLAUDE.md already imports AGENTS.md, it is left alone, so the rules don't load twice.The section tells the agent to pick the task bundle closest to what it is building and read it in one step, to start a signed-in app from the working starter that ships in the package instead of writing the shell from scratch, and to validate what it wrote:
Everything it points to ships inside the package, so the rules always match the version you installed.
