The repository is the contract 📜

There’s a moment in every project when someone (usually the most exhausted person on the team) writes a text file with the rules of the game inside. They call it AGENTS.md, commit it, and hope that everyone — humans and machines alike — will respect it.

It’s not a technical configuration file. It’s not a poorly maintained README. It’s something subtler and more powerful: the social contract of the repository. That unwritten (well, written) agreement that defines how we work, what doesn’t get touched, and what we expect from each other.

And when “each other” includes an AI agent, the contract becomes even more critical. Because an agent that doesn’t know the rules isn’t dangerous: it’s unpredictable. And unpredictability, in a software project, translates into bugs, tech debt, and meetings where everyone looks at each other asking “who did this?”.

The contract you didn’t know you had 🧾

Every team has its own way of doing things. Some rules are documented, others live only in the minds of the senior devs who’ve “been around forever.” The problem is that an AI agent can’t read minds. It doesn’t know that the legacy/auth module is sacred and shouldn’t be touched after 5 PM on Fridays. It doesn’t know that commits must follow Conventional Commits. It doesn’t know that tests must run before every PR.

The AGENTS.md is not a manual: it’s a set of operational constraints that the agent applies without needing repeated instructions.

Without a clear contract, the agent operates by analogy. And analogies, as we know, are the most elegant way to make elegant errors.

The point is that the contract already exists, even without a dedicated file. It’s just implicit, fragile, and lives in one person’s head. When that person is on vacation, the contract vanishes. With an AGENTS.md, the pact becomes objective: it doesn’t depend on who’s on the team today, but on what the project always requires.

And it’s not just about the agent. A written contract forces the team itself to be honest about what it actually does versus what it claims to do. That gap, in most teams, is wider than anyone likes to admit.

Shared knowledge, not dead documentation 🧠

The difference between a well-written AGENTS.md and a forgotten wiki is subtle but significant. The wiki says “these are our best practices.” The contract says “these are the rules you apply now, no discussion.”

It’s not passive documentation. It’s active knowledge: something the agent reads, interprets, and uses to make decisions. It’s like handing the new hire a sheet with the house rules, not a thick manual to read “whenever you get around to it.”

The distinction lies in attitude. The wiki is advisory: “you can look at this if you want.” The contract is operational: “this is how you work.” And when the “you” is an agent processing thousands of tokens per minute, the difference between advisory and operational translates into the gap between coherent output and plausible noise.

This connects to a theme we’ve already explored: maintaining a rich agentic context isn’t just about well-written prompts. It’s about repository structure. The context must be there, in the files, versioned, reviewed, alive.

The hierarchy of the pact 🏗️

A single root AGENTS.md works for simple projects. But as the project grows, the contract must adapt.

The solution is hierarchy: a root file with general rules, and specific files in subdirectories that handle exceptions. Like a constitution with local laws. The principle is the same one that applies to configuring the repository: context stratifies, and each layer adds precision without duplication.

A monorepo without context hierarchy is like a country without local courts: everything ends up at parliament, and parliament is always in the backlog.

In a monorepo, this hierarchy becomes essential. Every package has its own rules, but shares a core set of constraints. Without hierarchy, you either duplicate everywhere (and then maintain them all), or leave gaps (and the agent guesses).

The elegant thing is that the hierarchy already mirrors how we think about code: modules, packages, layers of abstraction. The contract follows the same logic. It’s not an add-on: it’s the documentary translation of the architecture.

The contract as collective memory 🧬

This is where the discussion gets philosophical, but not for the sake of it.

When a team defines its AGENTS.md, it’s doing something deeper than “writing rules.” It’s externalizing collective memory. Past decisions, accepted compromises, avoided traps — all compressed into a file that anyone can read, human or machine.

It’s the same mechanism behind the collective mind and the untranslatable state: when knowledge lives only in individual minds, it’s fragile. When externalized, it becomes robust. But when compressed, something is lost.

An AGENTS.md can’t capture everything. It can’t say “this function is written this way because Marco was in a hurry on March 14th.” But it can say “this module has weak tests, proceed with caution.” It’s a lossy compression, but it’s better than nothing.

And here’s the beautiful paradox: the more precise the contract, the less “human” it becomes. But the vaguer it is, the less useful it is. Finding the sweet spot — specific enough to be applicable, flexible enough to survive changes — is an art. An art that, fortunately, can be versioned.

When the contract breaks 💥

A contract is worthless without consequences. And an AGENTS.md without enforcement is just a text file with good intentions.

The consequences, in the agent world, are various:

• The agent ignores the rules and produces incoherent output
• The team loses trust in the process and goes back to doing everything manually
• The repository accumulates tech debt because nobody enforces constraints

And there’s a subtle side effect: when the contract is ignored too often, the team stops believing in it. It becomes that file that “exists but nobody reads.” And a contract that nobody respects is worse than no contract, because it teaches the team that rules are optional.

The solution isn’t “more rules.” It’s clear, verifiable, maintained rules. Every time the agent does something you didn’t want, you update the contract. Every time a rule no longer applies, you remove it. The file lives and breathes with the project.

The future: living contracts 🌱

We’re moving toward a world where the repository isn’t just a code container, but a shared cognitive system. Code is the “what,” AGENTS.md is the “how” and the “why.”

This changes how we think about documentation. No longer a boring appendix, but an architectural component. No longer “to be written when we have time,” but “to be maintained like we maintain code.”

And it changes how we think about teams. A good contract isn’t just a technical advantage: it’s a cultural one. It forces the team to make explicit what it takes for granted. To ask itself: “are our rules written down somewhere, or do they only live in our heads?”

The answer, in most cases, is uncomfortable. But at least now there’s a place to write it down.

And it’s exactly here that the contract transforms from constraint to resource: it’s no longer something that tells you what you can’t do, but something that reminds you why you do it a certain way.

The repository is the contract. The contract is knowledge. Knowledge is power — but only when it’s shared and alive.

And perhaps, in the end, this is the most important lesson: a good contract isn’t the one everyone signs, but the one everyone respects. Even when no one is watching. Especially when it’s a machine that has to respect it.