Almost always because it was never told the rules. An agent reads your code or your CMS and infers what you want. If your naming conventions, brand rules, and legal language live in somebody's head, the agent guesses. Writing those rules into a file it reads first fixes most of it.
This is the least glamorous part of working with AI agents, and the part that changes output the most. It is also cheap. You are writing a Markdown file, not building a pipeline.
The conventions have settled enough in 2026 to be worth learning properly. So here is what these files are, what the spec actually says, and what we put in them for website projects.
It is a plain Markdown file that sits in your project and tells AI coding agents how to work there. Think of it as a README written for a machine rather than a new hire. It covers conventions, commands, constraints, and the things a newcomer would get wrong on day one.
The dominant convention is AGENTS.md. It began as a collaboration between OpenAI Codex, Amp, Google Jules, Cursor and Factory, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. That governance matters, because it means no single vendor can quietly change the format underneath you.
By its own count the format is used by over 60,000 open source projects and supported by more than 20 tools, including GitHub Copilot, Gemini CLI, Visual Studio Code, Zed, Aider, Devin, JetBrains Junie and Warp. For a convention that is roughly a year old, that is unusually fast agreement.
Almost nothing, which surprises people. There are no required fields. It is standard Markdown, and the spec says you can use any headings you like, because the agent simply parses the text you provide. The freedom is deliberate and it is also the main way teams get this wrong.
The one structural rule worth knowing is precedence. The closest AGENTS.md file in the directory tree wins. That means you can put a general file at the root of a monorepo and a more specific one inside a package, and the specific one governs work in that package.
Because nothing is required, the quality of the file is entirely down to what you decide to write. A file that says "write clean code" is worse than no file, because it costs tokens and teaches nothing. A file that says which CSS class naming system this project uses is immediately useful.
No, and the difference is worth being precise about. An instructions file is context. It tells the agent how to behave. The Model Context Protocol is plumbing. It is described by its own documentation as an open source standard for connecting AI applications to external systems, and its docs compare it to a USB-C port for AI applications.
So MCP gives an agent the ability to reach your CMS, your database, or your deploy logs. The instructions file tells it what it is allowed to do once it gets there. You generally want both, and they solve different problems.
MCP has broad support across Claude, ChatGPT, Visual Studio Code and Cursor, which is why it has become the default way to expose a system to an agent. Our overview of MCP servers for web teams covers the connection side in detail.
Start with the things that are true and non obvious. The stack and where things live. The naming convention for classes or components. The command that runs the build and the command that runs the tests. Which directories are generated and must never be edited by hand.
Then add the rules that exist for a reason outside the code. The legal language that cannot be reworded. The claims you are not allowed to make about the product. The alt text standard. Accessibility requirements you have committed to. These are the rules an agent has no way of inferring, and they are the ones where being wrong is expensive.
Finish with your definition of done. If a change to the site requires a Lighthouse check, a visual review, or a specific commit message format, say so in one line each. We have found that this section prevents more rework than any other, because it turns a vague standard into something checkable.
Anything you would not enforce on a human. Long philosophical statements about quality do not change agent behaviour and they crowd out the specifics that do. Neither does restating things the agent can read directly from your code.
Leave out secrets, obviously. Never put API keys, tokens, internal hostnames or credentials in the file. It is committed to your repository and it is read by tools you do not fully control. If a rule needs a secret to follow, describe where the secret comes from instead of what it is.
We also leave out anything that changes weekly. A file full of current sprint details goes stale in days and then actively misleads. Put durable rules in the file and time bound context in the prompt.
Yes, and fast. Webflow launched Agent Instructions earlier in summer 2026, and at Webflow Conf on September 2, 2026 it announced that Webflow can now generate those instructions for you, with templates covering brand guidelines, design system, asset guidelines and CMS content, pulled from what Webflow already knows about your site.
The generated files are ordinary Markdown that you can edit, update, or regenerate as the site evolves. That is the right design. Generation solves the blank page problem, which is the real reason most teams never write one, while leaving you in control of the content.
Webflow announced two related things at the same event. MCP 2.1 expands what agents can do in Webflow, including building GSAP powered interactions and better CMS querying, and was described as becoming available to everyone later that month. Agent Presence, which shows an agent working live on the canvas the way you would see a teammate, was given the same timing.
Give it an owner and put it in the review path. The simplest rule we use is that if a pull request changes a convention, it changes the instructions file in the same pull request. That way the file is never more than one merge behind reality.
The second habit is deleting. Every rule in the file costs context on every agent run. When a rule stops being true, remove it rather than adding a note saying it is no longer true. Files grow by accretion unless somebody is willing to cut them.
Generated files need the same discipline. If Webflow or any other tool can regenerate your instructions from the current state of the site, regenerating on a schedule is safer than hand editing forever. Just read the diff before you accept it.
In our experience, noticeably, though we want to be careful here. We have not run a controlled study, and we would not trust anyone who claims a precise percentage for this. What we can say is that the errors change character. Agents stop making convention mistakes and start making judgement mistakes, which are easier to spot in review.
The mechanism is simple enough to believe. An agent with no context reconstructs your conventions from whatever it can see, and it will happily follow the worst pattern in your codebase if that pattern appears twice. Telling it the intended pattern removes that whole class of failure.
What it does not do is remove the need to review. Instructions reduce the noise so a human can see the real problems. Our notes on reviewing AI written code cover what to look for once the obvious mistakes are gone.
Write the file today and keep it to one page. Stack, conventions, build and test commands, generated directories, the rules that exist for legal or accessibility reasons, and your definition of done. That is enough to be useful, and a short file that gets read beats a thorough one that gets skimmed.
Then watch what your agents get wrong over the next fortnight and add only those rules. The file should grow from real failures, not from imagining them. If you want help working out what belongs in yours, or you are wiring agents into a Webflow build and want a second opinion on the guardrails, we are happy to talk it through at phoenix.studio.
Tell us where you want to go. We'll tell you how we'd get you there.