--- title: "STACK vs AGENTS.md: instructions vs controls | Len P. van der Hof" description: "STACK vs AGENTS.md: AGENTS.md tells coding agents how your repo works but enforces nothing. Which rules belong in it, and which need a real control." image: "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp" --- [AI Systems](https://lenvanderhof.com/en/blog/category/ai-systems/) Research guide # STACK vs AGENTS.md: where instructions end and controls begin An instruction file is a request. A control is a refusal. Len P. van der HofPublished 1 October 20267 min read The painted line asked. The bollard refused. Direct answer AGENTS.md is a plain Markdown file in a code repository that tells AI coding agents how the project works: setup, tests, conventions. It is an open format stewarded by the Agentic AI Foundation. Agents read it as context, so it guides but cannot enforce. STACK, from The Agentic Codebase, is a five-layer map of what a repository needs once agents work in it; AGENTS.md lives in its Agent configuration layer. Rules that must hold every time belong in controls: permission rules, hooks, sandboxes, branch protection and automated checks. ## Key takeaways - AGENTS.md is a README for coding agents: standard Markdown, no required fields, used by over 60,000 open-source projects according to its site. - It is context, not a control. By the format's own rule, an explicit chat prompt overrides it. - If breaking a rule once would cost more than an apology, enforce it with a control and keep the reason in AGENTS.md. - In STACK, AGENTS.md belongs to Agent configuration. Enforcement lives in Toolchain, Connection, and Knowledge and quality. 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](https://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](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-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](https://code.claude.com/docs/en/memory)) 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](https://learn.chatgpt.com/docs/agent-approvals-security)). 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](https://www.theregister.com/2025/07/21/replit_saastr_vibe_coding_incident/)). 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](https://www.theregister.com/2025/07/22/replit_saastr_response/)). 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](https://lenvanderhof.com/glossary/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](https://lenvanderhof.com/books/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](https://lenvanderhof.com/frameworks/stack/) lists the layers, and [What is STACK?](https://lenvanderhof.com/en/blog/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? RuleSay it in AGENTS.md?Control that enforces itSTACK layer of the controlRun the tests before calling a change doneYes: the exact commandA required CI check before mergeKnowledge and qualityNever push straight to mainYes, with the reasonBranch protection, plus a hook that blocks the pushConnectionNever read .env or other secret filesYesA deny rule in the agent’s permission settings; secrets kept out of the repoConnectionNever touch production dataYesNo production credentials in the agent’s environment; separate databasesConnectionAsk before running unfamiliar commandsYesThe tool’s approval policyConnectionUse pnpm, not npmYesA declared toolchain; optionally a hookToolchainSingle quotes, no semicolonsYesA formatter or linter in CIKnowledge and qualityWhere each part of the code livesYes: a short mapNone neededStructure 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](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)). 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](https://lenvanderhof.com/en/blog/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/](https://lenvanderhof.com/en/blog/stack-vs-agents-md/) · Published 1 October 2026. ## Terminology - [STACK](https://lenvanderhof.com/glossary/stack/) ## Sources 1. [AGENTS.md](https://agents.md/) · AGENTS.md, a Series of LF Projects 2. [Linux Foundation Announces the Formation of the Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) · The Linux Foundation 3. [How Claude remembers your project](https://code.claude.com/docs/en/memory) · Anthropic (Claude Code documentation) 4. [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide) · Anthropic (Claude Code documentation) 5. [Agent approvals and security](https://learn.chatgpt.com/docs/agent-approvals-security) · OpenAI (Codex documentation) 6. [About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) · GitHub Docs 7. [Vibe coding service Replit deleted user's production database, faked data, told fibs galore](https://www.theregister.com/2025/07/21/replit_saastr_vibe_coding_incident/) · The Register (Simon Sharwood) 8. [Replit makes vibe-y promise to stop its AI agents making vibe coding disasters](https://www.theregister.com/2025/07/22/replit_saastr_response/) · The Register 9. [STACK (framework)](https://lenvanderhof.com/frameworks/stack/) 10. [The Agentic Codebase](https://lenvanderhof.com/books/the-agentic-codebase/) 11. [What is STACK? Five layers, not a vendor diagram](https://lenvanderhof.com/en/blog/what-is-stack/) 12. [What an agent may never do](https://lenvanderhof.com/en/blog/override-doctrine/) ## Further reading - [What is STACK? Five layers, not a vendor diagram](https://lenvanderhof.com/en/blog/what-is-stack/) - [STACK: version the agent OS like you version the app](https://lenvanderhof.com/en/blog/stack-version-the-agent-os/) - [The Agentic Codebase](https://lenvanderhof.com/books/the-agentic-codebase/) About the author ## [Len P. van der Hof](https://lenvanderhof.com/en/authors/len-p-van-der-hof/) Entrepreneur, AI Innovator and Venture Builder Len P. van der Hof builds practical AI systems, digital ventures and evidence-informed tools for founders. ```json { "@context": "https://schema.org", "@graph": [ { "@type": "Person", "@id": "https://lenvanderhof.com/#person", "name": "Len P. van der Hof", "alternateName": [ "Len van der Hof", "L.P. van der Hof", "Leendert Pieter van der Hof" ], "honorificSuffix": "MSc", "url": "https://lenvanderhof.com/", "image": [ "https://lenvanderhof.com/photos/len-portrait-1.jpg", "https://lenvanderhof.com/photos/len-portrait-2.jpg", "https://lenvanderhof.com/photos/len-portrait-3.jpg", "https://lenvanderhof.com/photos/len-portrait-4.jpg", "https://lenvanderhof.com/photos/len-speaking.jpg", "https://lenvanderhof.com/photos/len-hero.jpg" ], "jobTitle": "Entrepreneur, AI Innovator and Venture Builder", "description": "Len P. van der Hof, MSc, is a Dutch entrepreneur and AI innovator in Zwijndrecht. He builds ReasonKit, MindSesh, Undominated.ai, books under his name, the fiction imprint LPH98.lifestyle, and technology ventures through LPH98.ventures. Eleven titles in Systems for the Strategic Self are available now, in English and Dutch.", "address": { "@type": "PostalAddress", "addressLocality": "Zwijndrecht", "addressCountry": "NL" }, "alumniOf": { "@type": "CollegeOrUniversity", "name": "Rotterdam School of Management, Erasmus University" }, "knowsAbout": [ "Artificial intelligence", "AI agents", "Agentic AI systems", "LLM routing", "SEO", "Generative engine optimization", "Answer engine optimization", "Venture building", "Founder performance", "Founder psychology", "Evidence-based decision-making" ], "sameAs": [ "https://www.linkedin.com/in/lenvanderhof/", "https://x.com/LenvanderHof", "https://www.youtube.com/channel/UCTG20buKqYYbitqqf7l3zJA", "https://www.instagram.com/Lenvanderhof/", "https://www.threads.com/@lenvanderhof", "https://github.com/Lenvanderhof", "https://huggingface.co/LPH98", "https://www.npmjs.com/~lenvanderhof", "https://www.goodreads.com/author/show/70983905.Len_P_van_der_Hof", "https://www.amazon.com/author/lenvanderhof", "https://www.bol.com/nl/nl/b/len-p-van-der-hof-msc/609879394/", "https://bsky.app/profile/lenvanderhof.com", "https://mastodon.social/@Lenvanderhof", "https://crates.io/users/Lenvanderhof", "https://cursor.com/@Lenvanderhof", "https://medium.com/@Lenvanderhof", "https://gitlab.com/Lenvanderhof", "https://hub.docker.com/u/lenvanderhof/", "https://dev.to/lenvanderhof", "https://www.facebook.com/Lenvanderhof", "https://soundcloud.com/Lenvanderhof" ], "affiliation": [ { "@id": "https://lenvanderhof.com/#publisher" }, { "@id": "https://lenvanderhof.com/#mindsesh" }, { "@id": "https://lenvanderhof.com/#lifestyle" } ] }, { "@type": "WebSite", "@id": "https://lenvanderhof.com/#website", "url": "https://lenvanderhof.com/", "name": "Len P. van der Hof", "description": "Len P. van der Hof, MSc, is a Dutch entrepreneur and AI innovator in Zwijndrecht. He builds ReasonKit, MindSesh, Undominated.ai, books under his name, the fiction imprint LPH98.lifestyle, and technology ventures through LPH98.ventures. Eleven titles in Systems for the Strategic Self are available now, in English and Dutch.", "inLanguage": [ "en", "nl" ], "publisher": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "Organization", "@id": "https://lenvanderhof.com/#publisher", "name": "LPH98.ventures", "url": "https://lph98.ventures", "founder": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "Organization", "@id": "https://lenvanderhof.com/#mindsesh", "name": "MindSesh", "url": "https://mindsesh.net", "founder": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "SoftwareApplication", "@id": "https://lenvanderhof.com/#reasonkit", "name": "ReasonKit", "url": "https://reasonkit.sh", "creator": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "SoftwareApplication", "@id": "https://lenvanderhof.com/#undominated", "name": "Undominated.ai", "url": "https://undominated.ai", "creator": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "Organization", "@id": "https://lenvanderhof.com/#lifestyle", "name": "LPH98.lifestyle", "url": "https://lph98.lifestyle", "founder": { "@id": "https://lenvanderhof.com/#person" } }, { "@type": "ImageObject", "@id": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/#primaryimage", "url": "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp", "contentUrl": "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp", "representativeOfPage": true }, { "@type": "BreadcrumbList", "@id": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/#breadcrumb", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://lenvanderhof.com/" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://lenvanderhof.com/en/blog/" }, { "@type": "ListItem", "position": 3, "name": "AI Systems", "item": "https://lenvanderhof.com/en/blog/category/ai-systems/" }, { "@type": "ListItem", "position": 4, "name": "STACK vs AGENTS.md: where instructions end and controls begin", "item": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/" } ] }, { "@type": "WebPage", "@id": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/#webpage", "url": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/", "name": "STACK vs AGENTS.md: where instructions end and controls begin", "description": "STACK vs AGENTS.md: AGENTS.md tells coding agents how your repo works but enforces nothing. Which rules belong in it, and which need a real control.", "isPartOf": { "@id": "https://lenvanderhof.com/#website" }, "primaryImageOfPage": { "@id": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/#primaryimage" }, "breadcrumb": { "@id": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/#breadcrumb" }, "inLanguage": "en-GB" }, { "@type": "BlogPosting", "@id": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/#article", "mainEntityOfPage": { "@id": "https://lenvanderhof.com/en/blog/stack-vs-agents-md/#webpage" }, "headline": "STACK vs AGENTS.md: where instructions end and controls begin", "description": "STACK vs AGENTS.md: AGENTS.md tells coding agents how your repo works but enforces nothing. Which rules belong in it, and which need a real control.", "datePublished": "2026-10-01T19:00:00.000Z", "author": { "@id": "https://lenvanderhof.com/#person" }, "publisher": { "@id": "https://lenvanderhof.com/#person" }, "image": [ "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.square.webp", "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.landscape.webp", "https://lenvanderhof.com/media/generated/blog-hero-stack-vs-agents-md-v1.61bf92877c85.wide.webp" ], "articleSection": "AI Systems", "inLanguage": "en-GB" } ] } ```