Sponsored by
Hi, there!
Welcome to the 21st edition of Work in Beta.
In this edition, we break down CLAUDE.md and AGENTS.md - two file names you keep seeing everywhere and explain why they matter.
Our free AI Starter Kits are the fastest way to go from "I should use AI more" to actually using it. Pick a tool, open the first lesson, and you'll have something working in 10 minutes. Start one here.
So let's dive in!
IF YOU ONLY HAVE 2 MINUTES
Image Credits: ChatGPT / Work in Beta
THE ‘HOW TO’ PLAYBOOK
CLAUDE.md and AGENTS.md Are Everywhere. Here Is What They Actually Do.
If you have been anywhere near AI conversations in the last few months, you have seen these terms: CLAUDE.md, AGENTS.md. Context engineering. Instruction files. Agent workflows.
Everyone uses them as if they are obvious. Nobody stops to explain them. You scroll past another post about "optimizing your CLAUDE.md" and think: did I miss something? Is this another technical rabbit hole I am supposed to climb into?
Here is the short answer: no.
The AI world has developed a bad habit of turning simple ideas into intimidating vocabulary. This is one of those times. The concept behind all these file names is something you already understand and once we strip the jargon, you will wonder why anyone made it sound complicated.
What These Files Actually Are
A CLAUDE.md or AGENTS.md file is a text document with standing instructions that AI reads automatically before you start working together.
That is it. No magic. No hidden configuration. Just a file that says: here is how this project works, what matters, what to avoid, and where key things live.
Think of it as the briefing note you hand a new teammate before day one. Not the task itself - the context behind every task.
One important distinction: not every AI tool uses these files. There are tools you talk to - ChatGPT, Claude chat, Gemini. You type a message, they reply. Those have their own setup (Custom Instructions, Projects, system prompts), and they do not need these files.
Then there are tools that work inside your project - they open your folders, read your files, make edits, run things. Claude Code, Claude Cowork, Codex, Cursor, Windsurf. These are the tools that read CLAUDE.md and AGENTS.md automatically.
The simple version: if AI is answering your questions, you do not need these files. If AI is doing work inside your project, that is where instruction files matter.
CLAUDE.md is Anthropic's version, used by Claude Code and Claude Cowork. AGENTS.md is an open format used by 60,000+ projects across Codex, Cursor, Windsurf, and others.
The Problem These Files Actually Solve
This is not a file-format story. It is a workflow story.
Without an instruction file, AI starts from zero every time you open a project. (We covered this problem in Edition 3 and back then, Projects were the fix. Instruction files take it further.) So you repeat: what the project is. How you want work done. What to avoid. What "done" looks like. The same 5 corrections, every single session.
If you keep telling the AI: use this tool, not that one. Check tests before saying you are done. Do not touch these files. Explain changes in plain language - then you do not have a prompting problem. You have an instruction-layer problem. The knowledge exists. It is just trapped in your head instead of written down.
Anthropic's own guidance says it directly: add something to your CLAUDE.md the second time you make the same correction. Not the tenth time. The second.
That is a very specific signal. If you are correcting the same thing twice, it belongs in the file not in your memory.
We call this the re-explanation tax: the time you spend teaching AI something it already knew yesterday. In Edition 17, we showed how to spot the work in your week that should become a Skill. Instruction files solve the same problem one layer earlier - before the task, not during it. Instruction files eliminate it.
The Map That Makes It All Click
A lot of the overwhelm comes from not having a simple map. Three terms keep floating around - prompts, instruction files, skills - and people blur them together. Here is the distinction:
Prompt = what you want right now. "Summarize this meeting." "Draft a proposal."
Instruction file (
CLAUDE.md/AGENTS.md) = what AI should already know before you ask. Project rules, conventions, boundaries, preferences.Skill / procedure file = how to do one repeatable task. A step-by-step workflow for a specific kind of work. (We broke down Skills in detail in Edition 10.)
The prompt is the question. The instruction file is the map. The skill is the method.
In Edition 16, we built a Personal AI Operating System - files that carry who you are across tools. Instruction files are the same principle applied at the project level: not who you are, but how work happens here.
What Goes Inside One
A good instruction file usually answers five questions:
What is this project?
How do we work here?
How do we check the work?
What should you avoid?
What does "done" look like?
Here is what that looks like in practice:
# Project overview
- This project does:
- The main goal is:
# How we work
- Start with:
- Test with:
- Before finishing, always:
# Conventions
- Name files like:
- Prefer this style:
# Boundaries
- Do not change:
- Ask before:
# Done means
- Explain work like this:
- Done looks like:
There is no universal template. The value is not the exact format. The value is writing down the reusable context you are tired of repeating.
One useful rule: a bad instruction file is an essay. A good one is a checklist plus a briefing note. Short. Concrete. Scannable. If AI cannot verify it or act on it, it probably does not belong in the file.
Why This Matters
The highest-leverage AI users we work with are spending less time on individual prompts and more time on setup - the reusable context that exists before any conversation starts. Writing. Research. Analysis. Reporting. Team workflows. The same pattern applies everywhere.
The shift is not from bad prompts to good prompts. It is from chat technique to context architecture. Setup over typing. Systems over tips. This is where AI work is heading and CLAUDE.md / AGENTS.md are the most visible example of that shift right now.
The Mistakes We See People Make
Thinking this is only for developers. The concept - reusable instructions before work starts - applies to anyone using AI on recurring work. You do not need to write code to benefit from writing down how you want work done.
Writing a 2,000-word instruction file. Longer is not better. Anthropic explicitly recommends keeping these files concise and signal-dense. The best files contain things AI cannot easily figure out on its own - exact commands, hard boundaries, non-obvious preferences. Most teams over-document what AI can discover and under-document what only humans know.
Confusing the instruction file with the prompt. If your starting prompt is 400 words of context before the actual question, that context belongs in the instruction file. The prompt should be the task. The instruction file should be the world.
Ignoring the open-format shift.
CLAUDE.mdworks with one company's tools.AGENTS.mdworks across many. Teams that write portable instruction files now avoid rewriting everything when they switch tools later.
Final Thought
You are not hearing about CLAUDE.md and AGENTS.md because everyone suddenly became a programmer. You are hearing about them because AI work is shifting from better prompts to better setup.
The people getting consistent output are not typing better questions. They are building better starting conditions.
WORK WITH US
Build With Us
Most professionals know AI can do more for them. The gap isn't awareness - it's knowing where to start, what to change, and how to make it stick.
That's what we work on through Work in Beta.
For individuals, we run working sessions - not teaching sessions, not agency engagements. You bring a real work problem and we figure out the AI solution together. You build, we guide. Think of it as borrowing our learning curve instead of building your own from scratch. You walk out with something working and the skills to keep going. When you get stuck, we're a message away.
For organisations, AI adoption is a people problem, not a technology problem. Your teams have the tools - what's missing is the translation layer between AI capability and daily work. Which processes to redesign, which habits to break, how to build genuine fluency - not just awareness. We help close that gap through hands-on training, process redesign, and deep adoption engagements. Not advisory, forward-deployed.
If any of this resonates, email us at [email protected] and we will figure out how to work together.