AGENTS.md Explained: The Operating Rules Your Agent Lives By

AGENTS.md is the file that tells an agent how to start up and how to behave inside a workspace. If SOUL.md is personality, AGENTS.md is the operating procedure. It is easy to overlook because it looks like a rules file, but that is exactly why it matters: this is where consistency comes from, and consistency is what keeps an assistant predictable.

This guide covers what AGENTS.md controls, why the rules file earns its keep, and the sections worth writing down before you trust an agent with real work.

What AGENTS.md controls

AGENTS.md usually covers the session startup sequence, memory rules, red lines, what counts as internal versus external work, and how the agent should behave in shared spaces. It is the file that says what happens first, what must be remembered, and what should never be done casually.

That makes it different from a personality file. AGENTS.md is about the rules of engagement, not the voice. SOUL.md tells the agent who it is; AGENTS.md tells it how to operate, which is a quieter job with bigger consequences when it is missing.

Why it matters so much

Without AGENTS.md, startup behavior drifts. One session reads memory first, another skips it, and another starts answering before it has enough context. That is how little inconsistencies become daily annoyances. The file also removes the guesswork around guardrails: if red lines are not defined, the agent treats everything as equally safe or equally risky, and neither default is what you want.

When the file is right, the effect is visible: the agent stops improvising its own process and follows the same sequence every time, which makes the whole setup calmer and easier to audit when something goes wrong.

The startup sequence

The first job of AGENTS.md is to say what happens when a session starts. A good rule reads like the one below, which is a real working example:

the startup sequence (real workspace rule)
# Use runtime-provided startup context first:
#   AGENTS.md, SOUL.md, USER.md, recent daily memory,
#   and MEMORY.md (main session only).

# Do not reread startup files unless:
#   1. the user explicitly asks
#   2. the provided context is missing something
#   3. you need a deeper follow-up read

# Style first, then the person, then recent history.
# The same way a human teammate catches up.

The sequence mirrors how a human teammate would catch up: first the style, then the person, then the recent history. Writing the order down matters because agents do not naturally agree on it, and sessions that start differently behave differently all day.

How to define red lines

This is where clarity pays off most. If an action affects the outside world, say so. If it needs approval, say so. If it is safe to do silently, say that too. The more explicit the rule, the less the agent has to infer, and inference is where accidents come from.

red lines, written bluntly
Do not exfiltrate private data. Ever.
Do not run destructive commands without asking.
Before changing config or schedulers (crontab, systemd,
nginx, shell rc): inspect first, preserve and merge.
Prefer trash over rm: recoverable beats gone forever.
When in doubt, ask.

# External vs internal
Safe freely: read files, explore, learn, search the web,
check calendars, work inside the workspace.
Ask first: sending email, posting publicly, anything that
leaves the machine, anything uncertain.

A concrete example: if you want every email drafted before sending, write that directly. A rule like that changes the workflow immediately and prevents accidental sends, because the agent now knows that sending is a two-step event with a human in the middle.

Internal versus external work

The most useful boundary in the file separates what is safe to do freely from what needs approval. Reading files, exploring, organizing, searching the web, checking calendars, and working inside the workspace are internal actions; the agent should treat them as routine. Sending email, posting publicly, or doing anything that leaves the machine is external, and external actions get the explicit rule: ask first. Framing the boundary as internal versus external is easier for the agent to apply than a long list of specific commands, because it generalizes to new tools and new situations.

Group chat behavior

Agents show up in noisy environments, and AGENTS.md should say when to speak and when to stay quiet. Good rules keep the agent from interrupting conversations just because it can, and push it toward acting like a good participant instead of an eager bot: respond when directly addressed or when it adds real value, stay silent during banter, react like a human would, and never triple-tap the same conversation with fragments.

This section is subtle and powerful. Chat behavior is where an assistant feels socially aware instead of mechanically present, and the rules file is where that feeling gets designed on purpose.

Maintenance and heartbeat rules

A complete AGENTS.md also covers the ongoing rhythm: memory maintenance habits, when the agent should be proactive rather than passive, and how often to check in. Proactive work without guardrails becomes noise, so the file should define both the cadence and the restraint: useful background work, no pestering, quiet hours respected. And like the agent it governs, the file itself needs maintenance, conventions get added as the setup grows and the file is never truly finished.

The section map

The operating procedure breaks into six sections, each with one job:

an AGENTS.md skeleton
## Session Startup      what context loads first
## Memory               daily notes vs long-term file
## Red Lines            what never happens casually
## External vs Internal what needs approval
## Group Chats          when to speak, when to stay quiet
## Heartbeats           proactive checks and cadence
## Make It Yours        conventions that grow over time

# Keep rules short and blunt. Vague rules create
# vague behavior; explicit rules create consistency.

The practical test for the file: read it back as if you were a new session that knows nothing else about the workspace. Would you know what to load first, what needs approval, and when to stay quiet? If a section only makes sense to the person who wrote it, rewrite it until a stranger could follow it. The file is read by fresh sessions constantly, so it has to work without institutional memory.

Common mistakes

• Leaving the default template untouched. It looks complete, but it rarely matches how you actually want the agent to operate.
• Forgetting to define what requires permission, which leaves the external boundary wide open by default.
• Being vague about memory and red lines, exactly the places where a vague rule creates a real problem later.
• Treating the file as finished. The rules should grow as the setup grows.

Quick tips

• Write the startup order down; it is the cheapest consistency win available.
• Separate safe internal actions from external ones that need approval.
• Define permission boundaries clearly, with concrete examples like email.
• Add chat behavior rules if you use shared spaces.
• Keep red lines short and blunt. Vague rules create vague behavior.

AGENTS.md sits alongside the other workspace files covered in this series: IDENTITY.md names the agent, MEMORY.md carries what it remembers, and The Complete OpenClaw Guide ties the whole setup together.

This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.

About The Author

Marcus Li

Marcus Li is a web designer and marketing specialist based in Vancouver, BC. After years of helping clients build their online presence, he discovered how AI tools could level the playing field for everyday entrepreneurs. He shares what actually works, no fluff, no hype.

See author's posts