CLAUDE.md, AGENTS.md, Rules Files: The New Operating Instructions for Software Teams

The agent shipped clean code. It passed review, it passed CI, and it quietly used a date-handling pattern the team had agreed to retire two quarters ago. Nobody caught it, because nothing was wrong with the code. The convention it broke lived in a wiki page the agent never opened. If you lead engineering and you have watched this happen, you are already deciding something whether you mean to or not: whether the files your agents read at generation time are a developer convenience, or the place your team's conventions now reach the code, or quietly fail to.

These files are not config, and they are not a control switch either

CLAUDE.md, AGENTS.md, Cursor rules files, and Copilot repository instructions are converging into one emerging artifact class: the operating instructions for software teams. Here is the version a CTO can repeat. The class is where your team's conventions get written down so the coding agent reads them at the moment it generates, which raises the odds that what the team holds reaches the code. It is not a switch that forces compliance, and it is not the thing that controls what the agent is allowed to touch. It is the conventions, written where the agent reads them.

That single sentence carries the whole argument, and it carries a correction most writing on this topic gets wrong. The instruction file influences the generated code. It does not enforce it, and it does not grant or restrict access. Those are three different layers, and a team that runs them together ends up confident about a standards bar it has not actually secured.

Step back from any one tool and one artifact resolves

Before a coding agent writes, it loads designated instruction files: repo-resident ones, sometimes alongside global or user-level rules the tool supports. That file tells it this team's naming conventions, directory structure, build and test commands, the libraries to prefer and the ones to avoid, the review bar, the constraints that are non-negotiable. The agent loads that context, then generates. The filename changes with the tool. The job does not.

Call the thing by what it does and the convergence is obvious. Claude Code reads CLAUDE.md. Codex and a growing set of other harnesses read AGENTS.md, an open format published as a shared spec rather than one vendor's private convention. Cursor reads rules files, written as .mdc files under a .cursor directory. GitHub Copilot reads repository custom instructions. Four filenames, one artifact class, all working the same problem the same way: hand the agent this team's conventions at the moment it writes, in a file that lives in the repo next to the code.

The convergence itself is the strongest evidence that this is a real class and not a coincidence of tooling. A cross-tool open format is hard to explain unless the underlying artifact is the same thing. The AGENTS.md format exists precisely because multiple agent harnesses needed the same file, and a shared spec is cheaper than every vendor reinventing it. The format is downstream of the need.

[1] Discovery and precedence differ by tool, and the difference matters when you reason about which rule wins. Claude Code's richest native format is CLAUDE.md, and it discovers nested CLAUDE.md files by relevance when it reads files in those paths, alongside ancestor, user, and managed instructions; cross-tool AGENTS.md support varies and is secondary where present. Cursor loads .mdc rules by their scoping rules. Copilot applies repository instructions to the request contexts its features support. The shared property is that the file is contextual guidance the agent reads before it writes. It is not identical runtime behavior across tools.

[2] The scope types are tool-specific, not a uniform set. Claude Code supports repo-level, nested path-relevant, ancestor, user, and managed scopes. AGENTS.md supports a repo file with directory-level files that apply by location. Cursor .mdc rules carry their own glob/scope metadata. Copilot repository instructions apply to the request contexts its features support, with path-specific instruction files where offered. "Role-oriented" rules, where they exist, are a convention authors encode inside the file, not a scope the tool resolves on its own. The shared property is that the class supports more-specific-than-repo scoping; the exact scope vocabulary is the tool's, not the class's.

Read that table for what it is. It is not a ranking and not a feature comparison. It is the shape of one artifact class wearing four filenames. The point of the row labels is to show what every column shares, not which column wins. Where this artifact class sits among the other substrate classes is mapped in the six-class AI engineering stack.

The file is the conventions written down, not the mechanism that guarantees them

The file is the standards an agent loads before it generates. That is the whole of what it is. It is the team's conventions, written down in the one place the agent will actually read them.

What it is not is an enforcement mechanism. Writing a rule in CLAUDE.md raises the probability the agent applies the rule. It does not guarantee it. Claude Code's own documentation is precise about this: the instructions are treated as context, not as enforced configuration, and there is no guarantee of strict compliance, especially for vague or conflicting instructions. The file is guidance. Guidance and enforcement are different layers of the same problem, and the most common mistake teams make with this artifact is treating the first as if it were the second.

I have argued elsewhere that coding standards have to become agent-readable to matter at all, and that a context file is the necessary first layer but never the sufficient one, because the deterministic check and the human judgment review sit downstream of it. The short version for this article: a rule in the file makes conformance more likely, the deterministic check is what verifies that specific rule independently of what the agent did, and access control is a third thing entirely. Hold that three-way distinction. It governs almost everything that follows.

The three layers solve three different problems and are enforced in three different places. The instruction file shapes behavior through context the agent reads. The enforcement layer runs a deterministic check that does not care what the agent intended. The access layer is platform machinery: on macOS, agent harnesses use sandbox profiles like Seatbelt; on Linux, bubblewrap; both sit underneath permission settings and approval prompts. None of those access controls works by reading your instruction file. A team that writes "do not touch production credentials" into CLAUDE.md and believes it has secured anything has confused the first layer for the third. The sentence raises the odds the agent avoids the credentials. It does not stop the agent from reaching them. A configured permission policy, sandbox profile, or approval gate stops that, and only when it actually covers the tool, action, and path involved. The instruction file is the wrong layer for a boundary that has to hold.

Which is why the load-bearing phrase is read at generation time. Documentation is read by humans, sometimes, when they remember it exists. The instruction file is loaded into the agent's context before it writes, according to each tool's own discovery and scoping rules. That is the difference that promotes this artifact out of the documentation pile and into the operating model. A standard the agent reads at generation time has a path to the code. A standard that lives only in a wiki the agent never opens does not. Same standard, two destinations, and only one of them has a chance of shipping.

Two patterns show the file doing operating-model work

Abstractions about artifact classes are easy to nod along to and hard to act on. Two concrete patterns make the claim load-bearing.

Take a naming convention. A team decides that all money values move through a single typed amount object, never raw floats, to keep rounding errors out of the ledger. That decision exists somewhere. If it exists in a wiki page and a Slack thread from last spring, the agent writing a new pricing module has no access to it. It generates clean, idiomatic, float-based code that passes review because the reviewer is moving fast and the code looks right. The convention was held by the team and missed by the work. Now encode the same convention as one line in the instruction file the agent reads. The agent loads it before generating, and the odds that it reaches for the typed amount object instead of a raw float go up sharply. Not to certainty. A long file, a conflicting instruction, an ambiguous prompt can still produce the float version, which is exactly why the deterministic check on the enforcement layer exists. But the convention now has a path to the code that it did not have when it lived only in the wiki. Nothing about the team's standard changed. What changed is whether the standard was in the file the agent reads. That is the entire mechanism, and it is the difference between a convention that is real and one that is merely true.

Now take something heavier than a naming rule. A team wants its data-access layer to go through a repository pattern, not raw queries scattered through the service code. That is not a style preference, it is a redesign of how a category of work gets done. You can put a path-scoped rule in the instruction file: when the agent reads files in the data-access directory, it picks up the rule that the repository pattern is the contract, with a one-line example of the shape. The scoping is relevance-based, not a hard wall. The agent loads that rule when it works in that area, and the broader repo-level conventions plus any user-level instructions still apply on top of it. What you get is not a hard boundary that governs that directory and could never touch code elsewhere. What you get is a higher likelihood that code generated in that area follows the pattern, because the rule is in the context the agent reads when it works there. The instruction file is where a role-level or workflow-level redesign stops being a tacit agreement and becomes durable. This is the same point I have made about role-based AI playbooks: the redesign only sticks when it lives somewhere the work actually touches. For agent-authored code, that somewhere is the file the agent reads.

Both examples share a structure worth naming. The standard was never the problem. The team had it. The question was whether the standard reached the point of generation, and the instruction file is the surface that decides whether it has a path there at all. That is operating-model work, not configuration. The verification that it landed is a separate job for a separate layer.

Where the class sits in the operating model

This is the part no tooling guide writes, because writing it requires stepping out of any one tool's documentation and asking an operating-model question instead.

An AI operating model is a designed system of interdependent components: roles and responsibilities, decision rights, workflows and handoffs, review and control standards, information and system access, incentives and performance measures, operating cadence. AI transformation that lasts is change to that system, not the purchase of a tool that sits beside it. The instruction-file class is one component of that system. It is not the system.

Be precise about which component it is, because the precision is the whole contribution. The instruction-file class is the durable encoding surface for two components: review-and-control standards, and workflows and handoffs. Review-and-control standards live in the file when a team writes its review bar into the conventions the agent loads, so the bar has a chance to be applied before the human review rather than only at it. Workflows and handoffs live in the file when the team encodes how a category of work is supposed to flow. The file does not own those components. It is where they get written down in a form the agent reads. A standard that is held only in people's heads is part of the operating model in name only. The instruction file is the surface that gives review-and-control standards and workflows a durable home for the part of the work an agent now does.

Now the part that is easy to get wrong. The instruction-file class is not the information-and-system-access component of the operating model. That component is a real and separate thing: the permissions, the sandbox, the approval gates that decide what each role's agent is allowed to touch. System access is capability, enforced at the platform level. The instruction file is context, read by the model. They are constantly confused because both shape what the agent ends up doing, but they do it through different machinery and they fail in different ways. An agent with the wrong context generates code that misses a convention. An agent with the wrong permissions reaches a system it should never have touched. Writing "stay out of the payments service" into CLAUDE.md addresses the first. It does nothing about the second. The access layer is where the second is handled, and it is not this file.

So the mapping is narrow and exact. The instruction-file class is the durable encoding surface for review-and-control standards and workflows. It became load-bearing for one reason: agents read it, and what reaches the agent has a path to the code. It is not the access layer, not the enforcement layer, not decision rights, not incentives, not cadence, and it is emphatically not the operating model itself. A team that says "we have a CLAUDE.md, so we have an AI operating model" has mistaken one component for the system, which is the same category error as mistaking a tool purchase for transformation. The file is one load-bearing part of a larger machine. Treating it as the machine is how teams end up surprised that the machine still does not run.

Managing it as an asset is the operating question, not how to write a good one

If the instruction-file class is an operating-model surface, the operating question is no longer "how do I write a good one." It is "how does the team manage this as a controlled asset." Four criteria separate a managed asset from a per-developer convenience.

It is owned. A named role maintains the file class, the way a named role owns the build pipeline or the deployment runbook. Ownership is not "whoever last edited it." It is a person or role accountable for keeping it current, with the authority to merge or reject changes to it. An unowned standards surface drifts because no one is accountable for the gap between what it says and what the team holds.

It is version-controlled and reviewed. The file lives in the repo, which most teams get for free, but it lives there as code, not as a scratch pad. A change to the instruction file changes the conventions every future agent will read in that scope, which raises or lowers the odds those agents conform across all the code they generate. That is a wide blast radius, so the change goes through review like any other change with that reach. A pull request that edits CLAUDE.md is editing the conventions the agent will load for all future generation in that scope. Reviewing it casually because "it is just the rules file" is reviewing a change to the team's standards bar without reading it.

It is audited. Someone checks, on a cadence, that the file still matches the standards the team actually holds. This is the criterion teams skip, and it is the one that matters most over time, because the failure it prevents is silent. The file does not announce when it has gone stale. It keeps loading the old convention into every generation long after the team moved on.

It is scoped. The class supports repo-level, path-level, and role-level rules, and the scoping is a design decision, not an accident of where someone happened to put a line. Repo-level for the conventions that hold everywhere. Path-level for the rules that should reach the agent when it works in a category of code. Role-level for the context a particular kind of contributor's agent needs. Scoping is how the file stays precise as it grows, instead of becoming a wall of rules no agent can prioritize.

These are criteria, not a checklist to copy. The point is the shift in posture. The honest question for an engineering leader is not whether the team has these files, because by now it does, whether anyone decided to or not. The question is whether the team treats them the way it treats any other asset that decides what ships.

Four ways teams get this wrong

The mistakes are predictable, which is good news, because predictable mistakes can be designed out.

The convenience trap is the most common. Each developer maintains their own instruction file, tuned to how they personally like the agent to behave, and the team has no shared standard at all. The files multiply, none of them is authoritative, and the result is that agent-authored code varies by whoever happened to write it. The artifact that could carry the team's standard is instead carrying twelve private preferences. The fix is not more files. It is one owned, shared surface, with personal preferences kept out of it.

The guidance-is-enforcement confusion is the most dangerous, because it produces false confidence. A team writes the rule into the file, sees the agent follow it a few times, and concludes the standard is now enforced. It is not. The file is guidance. It raises the odds and stops there. The agent can still miss the rule, especially as the file grows and the rule competes for attention with fifty others. Enforcement is the deterministic check that runs regardless of what the agent did: the hook, the test, the CI gate, the human review that catches what the agent missed. Treating the written rule as the guarantee is how a team ends up with a standards bar it believes in and code that quietly does not meet it. The performance precondition is that the standard is encoded where the agent reads it. Encoding is necessary. It is not the same as the check that proves conformance, which is the activity-versus-performance distinction I have drawn before about honest AI adoption metrics: "the agents are producing code" is activity, and "the standard reached the code and was verified" is performance.

The access confusion is the quieter cousin of the same mistake, and it is the more dangerous of the two when it fires. A team writes "never call external APIs from the worker process" or "do not modify the billing tables" into the instruction file and treats the sentence as a control. It is not a control. It is context that lowers the odds the agent does the thing, the same as any other written convention. What the agent is actually permitted to touch is decided by the permissions, the sandbox, and the approval gates, not by a line the model reads and may or may not weigh. If the boundary matters for safety or security, it belongs in the access layer, enforced by the platform, not in a file the agent treats as guidance. Putting a hard boundary in a soft surface is how a team believes it has a guardrail when it has a suggestion.

The drift trap is the quietest of all. The file stops matching the standards the team actually holds, and nothing flags it. The team retires a pattern, updates the wiki, tells everyone in standup, and forgets the instruction file. Every agent keeps loading the retired pattern and generating against it. The drift compounds because it is invisible: the code looks consistent, it is just consistent with a standard the team abandoned. This is the failure the audit criterion exists to catch, and it is the reason audit is not optional for a surface that decides what gets generated.

There is one more surface worth naming, because most teams have not considered it at all: the file is a security surface in its own right. The instruction file is an input the agent reads as instruction, which makes it a trusted channel into code generation, which makes it an attack surface. This is the prompt-injection problem applied to a repo-resident file: anything the agent ingests as instruction can carry a directive the team did not intend, which is why OWASP lists prompt injection as the top risk for LLM applications. The rules-file case is the version that lives in your repository and reaches the agent through a contributed change or any repo-resident text the agent is configured to treat as guidance, and Wiz's guidance on securing AI coding with rules files treats it directly. But be precise about the risk class, because the precision changes the fix. This is not the same as a malicious build script, which runs directly the moment it executes. The instruction file's impact is mediated. It steers a probabilistic model, and whatever it steers the model toward still has to clear the enforcement and access layers downstream. That makes it a real risk and a lower-tier one than executable code: a trusted-input, prompt-injection-adjacent surface that earns the same provenance discipline you give any input the agent trusts. Review changes to it. Control who can change it. Treat an unreviewed edit to the instruction file the way you would treat an unreviewed change to any input the agent will read as guidance, and lean on the enforcement and access layers for the boundaries that have to hold regardless of what the file says.

Key takeaways

• CLAUDE.md, AGENTS.md, Cursor rules, and Copilot instructions are one artifact class, not four products. The shared defining property is that the agent reads the file as context at generation time to learn this team's conventions. Discovery rules differ by tool, so the class converges on a role, not on identical runtime behavior.
• That property makes the class an operating-model surface, not configuration. A standard the agent reads has a path to the code; a standard the agent never reads does not. The path is probabilistic influence, not a guarantee.
• The file is influence, not enforcement, and not access. It raises the odds the standard is applied. The deterministic check (hooks, CI, review) verifies the rule held. The permissions, sandbox, and approvals control what the agent may touch. Confusing the three produces false confidence and, in the access case, a guardrail that is only a suggestion.
• In the operating model, the class is the durable encoding surface for review-and-control standards and workflows. It is one load-bearing component, never the whole model, and never the system-access component.
• Manage it as an asset: owned by a named role, version-controlled and reviewed like code, audited on a cadence against the standards the team holds, and deliberately scoped. And remember it is a trusted input the agent reads, which makes it an attack surface that earns review and provenance discipline, distinct from and lower-tier than executable code.

What to do with this

Stop treating the instruction file as config. By now your team has these files whether anyone decided to or not, and the only open question is whether you manage the surface that shapes what your agents generate, or leave it to drift.

The work is not writing a better CLAUDE.md. The work is deciding who owns the file class, how changes to it get reviewed, how it gets audited against the standards your team actually holds, and how it is scoped as it grows. It is also deciding, deliberately, which of your standards belong in this influence layer and which need the enforcement layer or the access layer to actually hold. Those are operating-model decisions, and they belong to whoever is accountable for what the team ships, not to whoever last touched the file.

A spec tells the team what to build. The instruction file tells the team's agents how this team builds. The spec and the instruction file are two of the durable artifacts that now stand between intent and generated code. The spec has had owners and review for years. The instruction file is newer, quieter, and increasingly the place your team's conventions either reach the code or quietly stop reaching it. The teams that will look back on this period well are the ones that named the file class as the influence surface it is, managed it like one, and put the enforcement and access layers underneath it, before the drift had a chance to ship.

AI Transparency Notice: This article and its accompanying images were created with the assistance of generative AI. The author directed the content, contributed the underlying ideas and analysis, and reviewed the final publication.

Frequently Asked Questions