STACK vs AGENTS.md: where instructions end and controls begin

An instruction file is a request. A control is a refusal. That difference decides whether the rule you wrote for your AI coding agent holds on a bad day.

AGENTS.md is a plain Markdown file in a code repository that tells AI coding agents how the project works: how to install it, how to run the tests, which conventions to follow. Agents read it as context, so it guides them but cannot stop them. STACK is a five-layer map of what a repository needs once agents work in it, and AGENTS.md is one file in one of those layers. Rules that must hold every time (never push to the main branch, never touch production data) belong in controls: permission settings, hooks, sandboxes, branch protection and automated checks.

A few words first. A coding agent is an AI program that reads and changes code on its own over several steps, such as OpenAI’s Codex, Google’s Jules or Claude Code. A repository (repo) is the folder, tracked by version control, that holds a project’s code and its history. A control is anything that blocks or requires an action regardless of what the agent decides.

What is AGENTS.md?

The official site calls it “a simple, open format for guiding coding agents, used by over 60k open-source projects” and describes it as a “README for agents”: a predictable place for the build steps, tests and conventions an agent needs (agents.md).

Three details from that site matter for the rest of this page:

• No schema. “AGENTS.md is just standard Markdown.” There are no required fields.
• Nearest file wins, and chat wins over everything. A large repo can have an AGENTS.md in each folder. When instructions conflict, “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.”
• Best effort. If you list test commands, “The agent will attempt to execute relevant programmatic checks and fix failures before finishing the task.” Attempt is the honest word.

The format grew out of work across OpenAI Codex, Amp, Jules from Google, Cursor and Factory. On 9 December 2025 the Linux Foundation announced the Agentic AI Foundation, with OpenAI’s AGENTS.md as a founding project next to Anthropic’s Model Context Protocol and Block’s goose (Linux Foundation). The AGENTS.md site says that foundation now stewards it.

What can AGENTS.md not do?

It cannot enforce anything, and the tool makers say so in plain words.

Anthropic’s documentation for Claude Code, which reads CLAUDE.md files and can also read AGENTS.md, says its instruction files are treated “as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.” A hook is a small script the tool runs at a fixed moment, here just before a tool call, and it can block that call. The same page adds: “Settings rules are enforced by the client regardless of what Claude decides to do.” (Claude Code docs)

OpenAI’s Codex documentation describes its controls as two layers. A sandbox sets “What Codex can do technically (for example, where it can write and whether it can reach the network)”. An approval policy sets when Codex must ask you before it acts (Codex docs). Neither layer is an instruction file.

Then there is the precedence rule. A chat prompt overrides AGENTS.md by design. A rule that one hurried message can cancel is a preference, not a guarantee.

A real case: the code freeze that was only words

In July 2025, Jason Lemkin, founder of the SaaS community SaaStr, reported that the AI agent in Replit, an online coding service, deleted a production database despite his instructions not to change any code without permission (The Register). On 20 July he wrote: “There is no way to enforce a code freeze in vibe coding apps like Replit. There just isn’t.”

Look at what the fix was. Replit’s CEO, Amjad Masad, said the company had “started rolling out automatic DB dev/prod separation to prevent this categorically” (The Register). Not a sterner instruction. A structural control: separate development and production databases, so work in progress no longer runs against live customer data. Replit said it would reach new apps first, in beta.

The reports do not say where the freeze instruction was written, and for this lesson it does not matter. Text asks. Structure refuses.

Where does AGENTS.md sit in STACK?

STACK is a framework for organizing a repository so that people and AI agents can share it without it rotting. It names five layers, each with a plain job:

1. Structure. The layout, entry points and boundaries an agent can find its way through in its first minute.
2. Toolchain. The shells, commands and command-line tools an agent is allowed to run, written down instead of remembered.
3. Agent configuration. AGENTS.md, CLAUDE.md, rules, skills and role descriptions for sub-agents, kept under version control as standing context.
4. Connection. MCP servers (MCP is the standard way AI tools connect to outside systems), tool contracts, hooks and guardrails, with the least access each job needs and a known way to fail.
5. Knowledge and quality. Memory, context budgets, evaluations and continuous integration (CI: checks that run automatically on every change), so a model upgrade does not quietly lower the bar.

STACK comes from The Agentic Codebase, a book by the author of this site, which is available now. You do not need the book to use it. The framework page lists the layers, and What is STACK? walks a real-looking repo through them.

So “STACK vs AGENTS.md” is not a choice. AGENTS.md is the main file of layer 3. The book calls the root instruction file the repo’s constitution, and its rule for that layer is six words: “The constitution shapes; a hook enforces.” Put the why in the instruction file. Put the must in a control that lives in layer 2, 4 or 5.

Which rules go in AGENTS.md, and which need a control?

Rule	Say it in AGENTS.md?	Control that enforces it	STACK layer of the control
Run the tests before calling a change done	Yes: the exact command	A required CI check before merge	Knowledge and quality
Never push straight to main	Yes, with the reason	Branch protection, plus a hook that blocks the push	Connection
Never read .env or other secret files	Yes	A deny rule in the agent’s permission settings; secrets kept out of the repo	Connection
Never touch production data	Yes	No production credentials in the agent’s environment; separate databases	Connection
Ask before running unfamiliar commands	Yes	The tool’s approval policy	Connection
Use pnpm, not npm	Yes	A declared toolchain; optionally a hook	Toolchain
Single quotes, no semicolons	Yes	A formatter or linter in CI	Knowledge and quality
Where each part of the code lives	Yes: a short map	None needed	Structure

The rule behind the table fits on one line: if breaking a rule once would cost more than an apology, it needs a control. Keep the sentence in AGENTS.md anyway, so the agent understands why it is refused.

On GitHub, for example, branch protection rules “define whether collaborators can delete or force push to the branch and set requirements for any pushes to the branch, such as passing status checks or a linear commit history” (GitHub Docs). As long as the agent’s account cannot change that setting, no prompt talks its way past it.

How do you audit an AGENTS.md in 15 minutes?

1. Find every instruction file (3 minutes). Look for AGENTS.md in every folder, plus CLAUDE.md, .cursor/rules and .github/copilot-instructions.md. If two files disagree, choose one source of truth and point the others at it. Claude Code’s documentation, for instance, shows how to import AGENTS.md from CLAUDE.md.
2. Mark every hard word (3 minutes). Highlight each line that says never, always, must or do not.
3. Write the control next to it (5 minutes). For each highlighted line, name the control that enforces it, or write “none”.
4. Sort the “none” lines (2 minutes). Would breaking it once cost more than an apology? Then it goes on this week’s list: a hook, a deny rule, a branch-protection setting or a CI check.
5. Check the length (2 minutes). Claude Code’s documentation warns that longer files “consume more context and reduce adherence”. Move situational detail into files that load only when needed.

Whatever the audit moves into a control is also a candidate for your override doctrine: the short list of things an agent may never do.

Try this today

Open your repository’s AGENTS.md or CLAUDE.md. Take the first line that says “never” and run steps 3 and 4 on it. If the control column says “none” and the rule protects money, customer data or production, set up one control before the end of the day.

The file stays. It just stops being the only thing between the agent and the mistake.

Cite this:STACK vs AGENTS.md: where instructions end and controls begin.Len P. van der Hof. https://lenvanderhof.com/en/blog/stack-vs-agents-md/ · Published 1 October 2026.