DEV Community: PromptMaster

AGENTS.md for a team: own it, review it, don't let it bloat

PromptMaster — Thu, 02 Jul 2026 09:06:56 +0000

Solo vs team

A solo AGENTS.md satisfies one person. A team's is a shared artifact — and it needs a little process.

Treat it like code

It lives in the repo, changes via PR, gets reviewed like anything else. A change shapes every agent's behaviour for every dev — same care as a shared config change.

Give it an owner

Unowned shared files either go stale (nobody updates) or bloat (everybody does). An owner keeps it sharp and guards the bar against bloat — the one pressure a team applies constantly.

Resist the committee effect

Each person adds the rule that bit them, nobody removes anything, and in a quarter the important rules are buried. The fix — ruthless pruning — has to be someone's explicit job.

Free onboarding

A good AGENTS.md is one of the best onboarding docs you have. A new hire reads it in a minute: how to build, the real conventions, what not to touch. And because agents depend on it, it stays current.

Keep it in sync across tools

Different devs, different agents → one real file, symlinked where a tool needs another name. Commit the symlink so everyone's on identical context on clone.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

Who owns the AGENTS.md on your team — or is it nobody's job yet? 👇

Don't generate your AGENTS.md with an LLM

PromptMaster — Thu, 02 Jul 2026 09:05:43 +0000

The counterintuitive finding

Generating your AGENTS.md from a model feels efficient. The research disagrees: developer-written vs LLM-generated instruction files showed the generated ones reduced task success in 5 of 8 settings, added extra steps per task, and raised inference cost with no quality gain.

Why it underperforms

A model writing from general knowledge:

restates what the agent already knows (generic best practices)
produces vague, plausible directives that don't change behaviour
→ the exact bloat that makes agents ignore the file

The value is what only you know

The convention you adopted after a painful bug. The directory that must never be touched, for a non-obvious reason. The exact command with the flag that matters. A model can't generate what it doesn't know — so it fills the space with filler.

Where automation does help

Scaffolding: generate a skeleton of headings + detected tooling, then fill and prune by hand.
Machine-maintained sections fed by a real source of truth (not the model's guess).

The dividing line is the source: never let the model invent your project's context.

The tell

Generated files read like they could describe any project. Hand-written ones read like they could only describe yours. Aim for that.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

Hand-written or generated — what's in your AGENTS.md right now? 👇

The commands section is the highest-ROI part of your AGENTS.md

PromptMaster — Thu, 02 Jul 2026 09:05:03 +0000

Why commands matter most

Most agent tasks end in a build or a test. List the exact commands and the agent runs them, reads the output, and fixes its own errors before finishing. Leave them out and it guesses — or reports success on code that never passed.

Be literal

"Run the tests" can't be executed. pnpm test can.

## Commands
Install:    pnpm install --frozen-lockfile
Dev:        pnpm dev
Build:      pnpm build
Test (all): pnpm test
Test (one): pnpm test -- path/to/file.test.ts
Typecheck:  pnpm typecheck
Lint + fix: pnpm lint --fix

Don't skip the single-test command

Test (one) lets the agent iterate in seconds on a focused change instead of running the whole suite (or skipping verification entirely).

Name the gate

Say what must pass before a change is "done" — types, lint, tests. The agent treats that as the bar to clear. Bonus: make it match your CI so the work it considers done is work that actually merges.

Monorepo?

Put workspace-wide commands at the root and package-specific ones in each package's AGENTS.md — the nearest file wins.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

What's in your commands section that's saved you the most rework? 👇

AGENTS.md vs CLAUDE.md vs README.md: what's the difference?

PromptMaster — Thu, 02 Jul 2026 09:04:07 +0000

Same shape, different readers

All three are Markdown at your repo root, which is why they get confused. But:

README.md → for humans: quick start, what the project does, how to contribute.
AGENTS.md → for agents, cross-tool: build/test commands, conventions, boundaries. Read by Codex, Cursor, Copilot, Gemini CLI and more.
CLAUDE.md → for Claude Code specifically (it doesn't read AGENTS.md natively yet).

You don't need two agent files

If you use Claude Code, don't maintain a separate CLAUDE.md. Symlink it:

$ ln -s AGENTS.md CLAUDE.md

One real file, two names, zero drift.

How they fit together

repo/
  README.md     # humans
  AGENTS.md     # agents (source of truth)
  CLAUDE.md ->  AGENTS.md   # symlink, for Claude Code

Keep all three. Each stays focused on its reader; the README can even link to AGENTS.md so contributors know where the agent conventions live.

The one rule

Never keep two real files with the same content — they drift the first time you edit one and forget the other. One file + a symlink, always.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

Do you keep a separate CLAUDE.md, or symlink it to AGENTS.md? 👇

AGENTS.md in a monorepo: nested files and precedence

PromptMaster — Wed, 01 Jul 2026 14:56:11 +0000

When one file isn't enough

A single root AGENTS.md is right for most repos. In a monorepo, one root file either bloats trying to cover every package or stays general and loses the specifics each one needs. The hierarchy fixes this: many small files, each close to the code it describes.

Nearest file wins

When an agent edits a file, the closest AGENTS.md up the tree applies. Place files where the rules belong:

monorepo/
  AGENTS.md              # workspace-wide: tooling, shared conventions
  packages/
    api/
      AGENTS.md          # api: its commands, its db rules
    web/
      AGENTS.md          # web: its build, its component conventions

(For scale: the main OpenAI repo reportedly has ~88 AGENTS.md files.)

Root vs leaves

Root: what's true everywhere — package manager, org-wide conventions, overall layout.
Leaf: only what's specific — that package's commands, conventions, boundaries.

Don't duplicate the root

Copying shared rules into every package file recreates the drift problem. Trust precedence: state shared rules once at the root and let packages inherit them, overriding only what genuinely differs.

Keep it shallow

Two levels — root + one per top-level package — covers almost every real monorepo. If you want a fourth level, the rules probably want consolidating upward instead.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

What's your monorepo AGENTS.md depth — one root file, or a tree? 👇

One AGENTS.md, every tool: the Claude Code symlink pattern

PromptMaster — Wed, 01 Jul 2026 14:55:18 +0000

The promise and the one exception

Most agents read AGENTS.md natively — Codex, Cursor, Copilot, Gemini CLI, and more. Write it once, it just works. The exception is Claude Code, which reads CLAUDE.md and (as of now) doesn't read AGENTS.md natively.

The fix is one line

Keep one real file. Point the other name at it:

$ ln -s AGENTS.md CLAUDE.md

One file on disk, two filenames. Claude Code reads CLAUDE.md, everything else reads AGENTS.md, and since they're the same bytes they can't drift.

Don't keep two real copies

# DON'T: two real files with the same content
AGENTS.md
CLAUDE.md   # a separate copy → drifts the first time you edit one

Every team that manually syncs two copies eventually ships mismatched instructions. A symlink makes that impossible.

Monorepo + Windows notes

Monorepo: repeat the symlink at each level that has an AGENTS.md.
Windows: Git may need developer mode for symlinks; if a link checks out as a text file, recreate it after enabling symlink support.

Commit it

Commit the symlink so it's present on clone — or gitignore and recreate it via a setup script. Committing is the simpler default.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

Team using Claude Code alongside other agents — are you symlinking, or still syncing by hand? 👇

How to write an AGENTS.md that agents actually follow

PromptMaster — Wed, 01 Jul 2026 14:54:30 +0000

A great AGENTS.md isn't the longest one — it's the one where every line changes what the agent does. The file loads on every task, and attention is finite, so every line competes with every other.

What earns its place

Stack + versions (one line)
A short directory map
Exact build/test commands, including the single-test command
Conventions a formatter can't enforce
A clear "do not touch" list

The commands section is the highest ROI: list your checks and the agent runs them and fixes failures before finishing.

What to cut

Personality instructions ("act as a senior engineer") — the agent already does this
Rules a formatter/linter already enforces — wire them into tooling, not prose
Task-specific context — that belongs in the session, not the file

The one-line test

For every line: "If I remove this, will the agent make a mistake?" Keep the yeses. Delete the nos.

Applied honestly, most of what you first wrote won't survive — and the file gets more effective, because the rules that matter stop competing with noise.

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

What's the one line in your AGENTS.md that's saved you the most rework? 👇

AGENTS.md: the cross-tool standard, explained

PromptMaster — Wed, 01 Jul 2026 14:53:34 +0000

AGENTS.md is a plain Markdown file at your repository root that tells AI coding agents how your project works — build steps, test commands, conventions, and boundaries. Where README.md is for humans, AGENTS.md is for the agents that do the work.

Why it exists

Open a repo in any agent and it doesn't know your build command, your conventions, or which directories are generated. Without that context it guesses — and wrong guesses are where the bad work comes from. AGENTS.md removes the need to guess.

A minimal example

# Acme API
Fastify, TypeScript, Drizzle ORM, PostgreSQL.

## Commands
Dev:   pnpm dev
Test:  pnpm test -- path/to/file.test.ts
Check: pnpm typecheck && pnpm lint

## Do not touch
- db/migrations/ is generated. Create a new migration instead.

How agents find it

One file at the root is the default. In a monorepo you can nest more files — agents read the nearest one in the directory tree, so a package's file overrides the root for work in that package.

Who reads it

Codex, Cursor, GitHub Copilot, Gemini CLI, Devin, Factory, Jules, Amp, VS Code, Windsurf — and 60,000+ projects. It's now stewarded by the Linux Foundation. The one holdout is Claude Code, which a symlink handles (separate post).

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

How many instruction files does your repo have right now — one, or a small museum of them? 👇

How to Write DESIGN.md Prose That AI Agents Actually Follow

PromptMaster — Sun, 28 Jun 2026 07:55:48 +0000

To write DESIGN.md prose agents follow, describe intent and rules, not just values. A token says a color is a hex; good prose says it is for the primary action only. Reasoning is what lets an agent generalise to cases you did not explicitly cover.

Weak vs strong prose

## Colors

# WEAK - restates the tokens:
Primary is #1A1C1E. Secondary is #6C7278.

# STRONG - explains intent:
High-contrast neutrals with one warm accent. Use the accent
only for the single most important action. Never decoratively.

The strong version gives the agent a rule it can apply to situations you never listed.

Why prose works on agents

LLMs read markdown with very high fidelity - most of their training is structured this way. That makes prose an ideal channel for design intent. The value tells the model what a color is; only prose tells it the rules.

Cover the canonical sections

Each section answers a question the agent would otherwise guess at:

## Overview        -> the personality
## Colors          -> roles and rules
## Typography      -> the job of each style
## Layout          -> grid and spacing
## Do's and Don'ts -> hard guardrails

Do's and Don'ts is where the value is

## Do's and Don'ts
- Do use the accent for one primary action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast (4.5:1 for normal text)
- Don't use more than two font weights on a screen

Each line removes a whole category of off-brand output.

How much is enough?

A good test: would the prose let a designer who had never seen your product apply your system correctly? Write what prevents a mistake, and stop there.

FAQ

Descriptive color names? Yes - tie them to the token name so the agent can map rationale onto values.
Most important section? Do's and Don'ts - it directly prevents agent mistakes.

Bottom line

Tokens are easy; the rationale is the work. Spend your time on the prose that turns values into your identity.

Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet

Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents

What is the one design rule you wish your agent would stop breaking? Drop it below - it probably belongs in your Do's and Don'ts.

How to Wire DESIGN.md into Claude Code, Cursor, Kiro and Windsurf

PromptMaster — Sun, 28 Jun 2026 07:54:52 +0000

To make an agent use DESIGN.md, point its persistent-context mechanism at the file. The pattern is the same everywhere: tell the agent to read DESIGN.md for UI work.

Claude Code

Reference DESIGN.md from your CLAUDE.md:

# In CLAUDE.md

## Design
This project has a DESIGN.md defining the visual identity.
Before generating or modifying any UI, read DESIGN.md and
follow its tokens and rationale. Use the accent color only
as the rationale specifies.

Cursor

Use a rules file to inject DESIGN.md into every UI generation, so the design context is present whenever the agent produces interface code.

Kiro and Windsurf

# Kiro     -> add DESIGN.md to the steering directory
# Windsurf -> point the global rules file at DESIGN.md

Every agent has a persistent-context mechanism; you route it to your design file.

Verify it is honoured

Ask the agent to generate a component and inspect the result:

Does the button use your accent, or a generic blue?
Are the corners your radius?
Does the spacing match your scale?

The first generation usually reveals a gap in your prose. Fill it, and the fix is permanent.

One file, many tools

Because DESIGN.md is an open format, the same file serves Claude Code, Cursor, Kiro and Windsurf at once - one design source of truth, no per-tool drift.

FAQ

Where do DESIGN.md files come from? Write one by hand, generate a draft with an agent, or export from Google Stitch.
Does it work across tools? Yes - one file, read by each tool's own mechanism.

Bottom line

Wiring in DESIGN.md is always the same move: tell the agent's context mechanism to read the design file for UI work.

Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet

Which agent are you wiring DESIGN.md into first? Curious which tools people are using for UI work these days.

What Is DESIGN.md? A Practical Guide to Design Systems for AI Agents

PromptMaster — Sun, 28 Jun 2026 07:54:05 +0000

DESIGN.md is an open format from Google Labs that describes a design system to AI coding agents. It pairs machine-readable design tokens (YAML front matter) with human-readable rationale (markdown prose), so an agent generates UI that matches your brand instead of generic defaults.

Why agents need it

Left alone, an AI coding agent draws on the most common patterns in its training data — generic blues, default fonts, arbitrary spacing. It has no way to know your design system unless you tell it, every single time. The result is UI that looks plausible but not like yours.

DESIGN.md removes the "every single time." You describe your visual identity once, in a file the agent reads before generating any UI.

Where it lives

DESIGN.md is a plain file in your repo root. Because it is markdown with YAML front matter — formats every developer knows — it needs no build step and no special viewer. The agent reads it as-is, and it travels with your project.

The two parts

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
---

## Colors
High-contrast neutrals with a single warm accent. Use the
accent (tertiary) only for the primary action - never decoratively.

The front matter gives the agent exact values. The prose gives it the rules. Together they let the agent apply your system correctly, not just access its raw numbers.

How it relates to CLAUDE.md and AGENTS.md

If you use CLAUDE.md or AGENTS.md, this will feel familiar. DESIGN.md is to design what those files are to code conventions — persistent context the agent reads on every interaction. Complementary layers that do not overlap.

FAQ

Is it free? Yes — open format, free CLI.
Do I need a build pipeline? No. The agent reads the file as-is.
Which agents work with it? Any with a persistent-context mechanism: Claude Code, Cursor, Kiro, Windsurf.

The bottom line

DESIGN.md is a small, durable investment: describe your design system once, and every UI an agent generates starts from your brand instead of a generic default.

Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet

Have you tried DESIGN.md yet, or are you still re-explaining your design system to your agent every session? Curious where people are in the comments.

DESIGN.md Checks WCAG Contrast by Default. Here's Why That Matters.

PromptMaster — Sun, 28 Jun 2026 07:53:16 +0000

DESIGN.md's linter checks WCAG contrast by default for every component's color pairing, reporting the exact ratio and whether it passes. Accessibility is built into the tooling, not left as an optional audit - which fixes a real weakness of AI-generated UI.

The weakness it addresses

AI agents ignore contrast unless forced to consider it. Left alone, an agent places light grey text on white because it looks clean in the abstract - producing UI that fails accessibility standards and is hard to read.

How the check works

For each component pairing a text color with a background, the linter computes the contrast ratio and reports whether it meets WCAG AA (4.5:1 for normal text):

$ npx @google/design.md lint DESIGN.md

{
  "path": "components.button-primary",
  "message": "textColor (#ffffff) on backgroundColor (#1A1C1E)
              has contrast ratio 15.42:1 - passes WCAG AA."
}

Design with contrast in mind

Because the check is built in, think about contrast as you define component tokens, not after. When you pair a text color with a background, the linter tells you immediately whether it holds up - turning accessibility from an audit phase into a continuous part of defining your system.

Reinforce it in prose

## Do's and Don'ts
- Do maintain WCAG AA contrast (4.5:1 for normal text)
- Don't rely on color alone to convey meaning
- Do keep touch targets large enough

The linter handles the measurable; the prose handles the judgement.

Why it matters commercially

Accessible interfaces are often a legal requirement, not just an ethical default. Baking WCAG into the tooling reduces the risk of shipping non-compliant UI - a real and growing liability.

FAQ

Which level? WCAG AA contrast, per component pairing.
Can I extend it? Reinforce with prose for the parts a single ratio cannot capture.

Bottom line

Making WCAG a default turns accessible output into the path of least resistance.

Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet

Has an AI agent ever shipped you a contrast failure? Curious how people are catching these today.