Why Your AI Agent Ignores Your Team's Conventions

You told the agent to use semantic color tokens. It used hex values. You told it again. It used hex values. The third time you typed the instruction in caps. It still used hex values.

The agent is not ignoring you. The instruction is sitting in the chat, but the chat is not where the agent looks for project rules. The chat is for the current task. Project rules live somewhere else, and yours is empty.

What actually shapes agent behavior

An agent's output is shaped by four inputs, not just your message.

The system prompt. Every agent has one. You do not see it. It tells the model how to behave, what tools to use, what tone to take. It is set by the tool vendor, not by you. It is always there.

Tool definitions. The agent knows what tools it has, what parameters they take, what output to expect. This is what makes it an agent instead of a chatbot. You also do not control this directly.

Project context. This is the one you control. If your repo has an AGENTS.md file at the root, the agent reads it on every conversation. This is where your conventions, your stack, your naming rules, your "do not do" list all live.

Environment data. Operating system, current directory, open files, selected text. The agent sees this too. It is why asking about "this file" works.

Your chat message is the fifth input, the obvious one. It is also the weakest for shaping long-term behavior, because it only exists for the current thread.

Why your chat instructions do not stick

When you type "always use semantic tokens" in chat, the agent obeys for that message. Maybe the next. By the third message the instruction has scrolled up, surrounded by other priorities, and the model weights it lower.

When you put "always use semantic tokens" in AGENTS.md, it is in the context window of every single message from message one. It never scrolls away. It is not competing with the current task for attention.

This is the structural difference. Chat instructions are temporary. Project rules are persistent. Agents follow persistent rules more reliably than temporary ones.

What goes in AGENTS.md

The minimum that earns its keep:

Your stack. Framework, language, package manager, test runner. The agent stops guessing and stops suggesting tools you do not use.

Your conventions. Naming patterns, file structure, where new code should go. The agent stops putting utils in helpers/ when your project uses lib/.

Your "do not" list. Patterns you have rejected before. "Do not add new dependencies without asking." "Do not refactor outside the scope of the ticket." "Do not write tests after the code."

Your tokens. Design system colors, typography scale, spacing units. The agent stops inventing hex values.

Anything you find yourself repeating in chat across sessions. If you have typed the same correction three times, it belongs in AGENTS.md.

What does not belong

Long essays about your business model. Architecture diagrams in prose. Anything the agent cannot act on in code. AGENTS.md is for instructions the agent can follow, not context for humans.

If your AGENTS.md is more than a page, you are probably mixing audiences. Split it: keep the agent-facing rules short, link out to human-facing docs.

The smallest test

Open your AGENTS.md (or create one if it does not exist). Add the three rules you find yourself repeating most often in chat. Restart the agent. Try the same task that ignored your instructions last time.

If the agent now follows the rule without being told, the problem was never the model. The instructions were in the wrong place.