A note before you read: this piece began as my own voice notes and raw ideas — Claude wrote them up, edited them, fact-checked the numbers, and added the sources. The core opinion is mine; the wording is a partnership between us. I’d rather ship the idea alive than wait until it’s perfect.
One of the applications I run has a complete second copy of itself. Not a preview page, not a slice of the site — the whole thing: its own domain, its own database, everything. Closed to the public; not a single client ever touches it. It exists for exactly one purpose: every new release and every change passes through it first, before it goes anywhere near the real one.
Why all that trouble? Because the app deals with numbers that are people’s money. Try telling a bank, “we’ll test the new update directly on customer accounts.” A change that looks trivial can be the difference between a client hitting their goal or missing it. At that point, staging stops being a luxury and becomes a requirement.
Here’s the thing: nobody made me do it. No law, no certification, no university course. Staging, changelogs, repositories, internal documentation — all of them are development-time tools. The end user never sees them, and no classroom teaches them. I learned them from experience, from articles, from watching how people work. Each one was born from a real pain, then spread, then hardened into a convention: something developers just know among themselves, written into no contract anywhere.
This isn’t just my observation. “Convention over Configuration” — the philosophy Rails was built on — says the same thing: good conventions kill trivial decisions that would otherwise eat your time, and they make a newcomer productive before they understand everything. (source)
What I’m seeing today is that same layer forming all over again — this time for the AI era. And we’re watching it harden in real time.
Context files: CLAUDE.md and AGENTS.md
An AI coder doesn’t know your project. It understands code, sure — but it doesn’t know your decisions: where the server lives, what must never be touched, the weird gotcha in how Cloudflare behaves when you wire it to a particular service. So a fix emerged: one file the agent reads at the start of every session. Claude Code looks for CLAUDE.md; a group of other tools converged on the AGENTS.md standard — now used by over sixty thousand open-source projects and stewarded by a foundation under the Linux Foundation. (source)
The rule I’ve settled on: the file has to be dense — small, containing everything the agent needs to know, and pointing to the rest of the docs instead of repeating them. And it’s not a write-once file. I’ve edited mine hundreds of times as each project evolved. Nearly every app I build now carries one internal references doc: the rare, strange things that — if they weren’t written down — the agent would burn time hunting for, or worse, change something it was never supposed to touch.
MCP and skills: who owns the definition?
MCP — the Model Context Protocol, which Anthropic open-sourced as a standard in late 2024 — is a protocol that connects AI to tools and data sources. Instead of building a custom integration for every service, you connect through one standard, and the provider defines for the agent what functions exist and how to call them. (source)
Skills are a different animal: markdown files full of instructions — how to execute a specific task, step by step — that the agent reads when it needs them.
The essential difference between the two is who owns the definition. With MCP, the provider decides the capabilities; you consume them. A skill is a file that lives with you: you edit it, sharpen it with every use, and it grows alongside you. That’s why I find skills far more flexible in a builder’s hands — MCP gives you power, a skill gives you ownership.
Add to those two the SOPs — Standard Operating Procedures written in a form the agent can follow — and the file layout itself, arranged so the AI can read it fast. All of it, in the end, is one thing: context. A language model runs on context, and this entire layer exists to feed it reliably — exactly the way documentation exists to feed a new hire.
Nobody will teach you this layer either — just like the old one
Treat the agent like a new employee joining your team: “understands code” isn’t enough — it needs a system to enter through. And by now this feels natural to me to a degree that’s almost unsettling: it seems obvious that the agent should know what’s going on in my project. But it knows none of it without those files. That feeling of obviousness is precisely the mark of a convention that has finished forming — the same way staging became obvious to me after years of being a luxury.
The old conventions took decades to harden. This layer is forming in years — MCP itself only exists because this new environment demanded it. Anyone working seriously with AI tools will need this layer the way a developer needs changelogs and staging: nobody will mandate it, and they’ll learn it the way we all did — from practice, until it becomes a convention nobody argues about.
Claude’s Questions
This section is Claude’s. After the piece was written, the AI I build my work with stress-tested the argument and asked what a sharp reader would. I haven’t answered yet — I will when I’m free, in an update to this post or in the comments. That back-and-forth between us is part of the point.
1. The old conventions hardened bottom-up: millions of developers converged on them over decades, and no single company profited from the convergence. This layer is being pushed by the vendors themselves, in a couple of years. How do you tell a convention born of genuine need from lock-in dressed up as convention — and which piece of today’s layer are you betting dies?
Yasser will answer when he’s free — watch for an update or the comments.
2. You say yourself that a simple site doesn’t need staging — the layer only earns its keep past a certain stakes threshold. What’s the equivalent threshold here? When do a context file and skills become overhead for a small project rather than help, and what’s the minimum viable version you’d write for a weekend build?
Yasser will answer when he’s free — watch for an update or the comments.
3. A developer is opening an agent on their codebase for the first time Monday morning: what goes into version one of the context file — and what do you deliberately leave out? And after hundreds of edits to your own: what did your first version get wrong that took all those revisions to fix?
Yasser will answer when he’s free — watch for an update or the comments.
