AGENTS.md Guide for Builders

Summary

What AGENTS.md does

AGENTS.md is useful because agents need context before they act. A human can scan a folder, remember past decisions and infer intent from tone. An agent needs those expectations written down.

The file is not a brand story, a style manifesto or a long team handbook. It is a working agreement for software that reads instructions. It should answer practical questions:

• What is this workspace for?
• Which files are source of truth?
• What should the agent check before making changes?
• Which words, claims or patterns are banned in public copy?
• Which commands should run before work is called complete?
• Which actions need human approval?
• What should the agent leave untouched?

The public AGENTS.md format describes the file as a simple open format for guiding coding agents. OpenAI documents AGENTS.md for Codex as a way to give custom instructions. Those facts matter because the file is becoming a common handoff surface between human builders and agentic tools, but the best file is still the one that fits the work in front of you.

When to create an AGENTS.md file

Create an AGENTS.md file when the same kind of agent mistake happens more than once. Maybe the agent edits generated files instead of source files. Maybe it invents public claims. Maybe it runs the wrong checks. Maybe it changes the visual style while fixing copy. Those are not only execution problems. They are instruction problems.

You should create one when a workspace has any of these conditions:

• More than one kind of file matters, such as copy, HTML, CSS, images and publishing records.
• Public copy has strict language rules.
• The visual system has rules that should not drift.
• Certain actions require approval, such as publishing, deleting, moving credentials or changing live settings.
• The same checks must run every time.
• More than one agent or editor may touch the same work.
• The work connects to live sites, forms, media, search metadata or external tools.

For a small personal script, a short README may be enough. For a website, app, content engine, automation system or AI-assisted workspace, AGENTS.md saves time because it turns repeated explanations into reusable context.

What to include

Start with the decisions that protect the work. A useful AGENTS.md file does not need every detail. It needs the details an agent is likely to miss.

Purpose and audience

State what the workspace is for and who it serves. Keep it plain.

Example: “This site helps builders understand software-to-software workflows with agents, MCP, APIs, instruction files and templates.”

That single sentence helps an agent reject copy that drifts into a generic AI tools blog, enterprise integration pitch or old topic.

Source files

Tell the agent where truth lives. If copy starts in Markdown and HTML is generated from it, say that. If design rules live in a design file, say that. If publishing records live in a separate folder, say that.

This section prevents edits in the wrong place. It also helps the agent update the right records after creating a page.

Language rules

List words, claims and phrases that cannot appear in public copy. Be exact. If a word is banned, write the word. If a tone is wrong, show a better version.

For mean.md pages, this matters because coding is only one use case. The site covers marketing, operations, research, content and personal systems too. An agent that sees only code examples may narrow the category unless the instruction file says otherwise.

Design rules

Give the agent the visual boundaries that should survive every edit: fonts, colors, button style, card radius, mobile width, contrast and image treatment.

Do not bury design decisions in vague praise. “Keep the design polished” does not help. “Use cream background, warm near-black text, orange accent buttons, sand borders and no decorative gradient blobs” helps.

Commands and checks

List the checks that prove the work is sound. This can include source scans, render checks, link checks, schema checks, character counts, FAQ counts and mobile screenshots.

The point is not to run every check every time. The point is to make the expected checks visible so the agent can choose the right ones for the current change.

Approval boundaries

Write down actions that need a human. Publishing, changing credentials, deleting content, overwriting live settings, changing brand names and making legal claims should not be casual agent decisions.

Approval boundaries are not bureaucracy. They are how you keep agent speed from turning into live-site risk.

A practical AGENTS.md structure

Use a structure that is easy to scan. The file below is a starting pattern for a builder workspace. Replace the examples with your own rules.

# AGENTS.md

## Purpose

This workspace helps builders create software-to-software workflows with agents, MCP, APIs, instruction files and reusable templates.

## Public Voice

- Use clear, direct English.
- Keep coding as one use case, not the whole category.
- Do not invent proof, partnerships, numbers or guarantees.
- Do not use banned public words or claims listed in the writing rules.

## Source Files

- Copy starts in `docs/copy/`.
- Published page HTML is prepared in `pages/`.
- Design rules live in `docs/design/design.md`.
- Publishing records live in `publishing/`.
- Task ownership lives in `task.md`.

## Work Rules

- Read the relevant copy, design and publishing notes before editing.
- Keep changes scoped to the requested page or workflow.
- Preserve approved brand names and legal details.
- Never publish or ask for credentials unless the human explicitly asks.

## Checks

- Check one visible H1.
- Check mobile at 390px and 320px.
- Check public copy for banned words.
- Check related links and featured image mapping.
- Check schema when the page type requires it.

## Approval Boundaries

Ask before publishing, deleting, changing live settings, changing legal text, changing brand names or replacing approved media.

This template is intentionally compact. A long instruction file can become another thing the agent skims. Start short, then add rules only when they prevent real mistakes.

How AGENTS.md fits with other instruction files

AGENTS.md should not carry every rule alone. It works best as the entry point that points to deeper files.

Use AGENTS.md for the working agreement. Use a design file for visual rules. Use writing rules for voice, banned phrases and public copy. Use publishing checklists for live-site gates. Use a starter kit when you want repeatable templates.

This separation helps because each file has a job:

When those files agree, software can read the workspace more reliably. When they conflict, the agent wastes time guessing which rule wins.

How to write rules agents can use

Good agent instructions are specific, testable and short. Weak rules sound reasonable but do not change behavior.

Weak: “Make the page high quality.”

Better: “Each support page must include a Summary section, at least 20 FAQ questions, one visible H1, built-in JSON-LD schema and at least one contextual incoming link from another mean.md page.”

Weak: “Use the brand correctly.”

Better: “Use mean.md as the public brand. Use software-to-software as category language. Do not treat software-to-software as the public brand label.”

Weak: “Check mobile.”

Better: “Render at 390px and 320px. The content wrapper should use the available width, text should not clip, and the header button should stay on the logo row.”

The rule should make the next action obvious. If the agent still has to guess, the rule needs another sentence or a link to the source file.

Common mistakes

The most common mistake is writing AGENTS.md like a policy archive. Agents do not need a museum of every decision. They need current instructions that help them act.

Another mistake is turning the file into a dumping ground. If every new issue adds another paragraph, the file becomes heavy. Group rules by job. Remove old rules. Link to deeper files when the details belong elsewhere.

A third mistake is writing rules that cannot be checked. “Avoid generic copy” is hard to verify. “Do not use the phrases listed in Writing rules.md” is easier. “Each support page must be at least 10,000 characters” is even easier.

The fourth mistake is forgetting approval boundaries. Agent tools are strong enough to change live things. Your instruction file should make live changes explicit, not implied.

Review loop

Review AGENTS.md after each major content, design or publishing change. Do not wait for the file to feel outdated. The best time to update it is right after a mistake is fixed, while the lesson is still concrete.

Use this review sequence:

1. Find the repeated mistake.
2. Ask which instruction would have prevented it.
3. Add the shortest useful rule.
4. Link to the deeper source if needed.
5. Remove any rule that no longer applies.
6. Run a small check to confirm the new rule is visible to the agent.

This keeps the file alive without turning it into a manual nobody reads.

How this connects to software-to-software workflows

AGENTS.md is part of the broader software-to-software layer. APIs let software exchange data. MCP can give agents a standard way to reach tools and context. Instruction files tell agents how to behave inside a specific workspace.

That last part matters. Without instructions, an agent may know how to edit a file but not why a page exists, which audience it serves, what quality bar applies or what should never be published.

For builders, this is the practical shift: you are not only buying tools. You are shaping small systems that can read instructions, call tools, update files and run checks. AGENTS.md is one of the files that makes that system easier to control.

Starter checklist

Use this checklist when writing your first AGENTS.md file:

• Define the workspace in one sentence.
• Name the audience.
• List the source files that matter.
• Link to writing rules and design rules.
• List commands and checks.
• State approval boundaries.
• Name files or folders the agent should avoid.
• Add public copy rules.
• Add mobile and design checks if the work touches pages.
• Keep the first version short.
• Review it after the next agent session.

Next step

If you already have an agent instruction page, connect it to a focused AGENTS.md file. Start with the rules that prevent the most expensive mistakes, then add templates from the mean.md starter kit when you need repeatable files.

Read the broader guide to agent instruction files, then use the MCP guide and the mean.md Software-to-Software Starter Kit when you are ready to connect instructions to tools and reusable checks.

FAQ