CLAUDE.md and Skills: How I Stop AI Agents From Drifting

An AI agent doesn't fail loudly. It drifts — a slightly wrong brand claim here, a shortcut there, a "completed" task that was never verified — until one day the output is confidently, expensively wrong. I run the infrastructure of five brands through Claude Code and agent fleets, much of it on scheduled loops with no human watching. Shared written doctrine is one of the four things that makes a pile of agents an actual fleet — the full definition is in what an AI agent fleet is. The only reason that works is that I stopped treating context files as notes and started treating them as standard operating procedures.

Here's the system, layer by layer.

The short answer#

Agent drift — the same agent producing steadily less consistent work across runs — is stopped by moving your standards out of the conversation and into files the agent loads before it starts working. There are four layers and they do different jobs. A global CLAUDE.md holds the hard rules that apply to every project, so they follow the agent everywhere. A per-project CLAUDE.md holds the context a new teammate would need for that specific codebase or brand. Skills hold procedures the agent loads on demand, so a long checklist is available when it is relevant instead of always occupying context. Memory holds the corrections you have already given, so the same feedback does not have to be repeated next session. The distinction that makes the stack work is between hard rules, which are never negotiable and must be phrased as prohibitions, and preferences, which the agent may weigh against context. Collapse that distinction and the hard rules erode first.

How do you stop an AI agent from drifting?#

Before the details, the shape of the whole thing. Each layer answers a different question, and each has a different loading behavior:

Most guides on CLAUDE.md best practices stop at layer two. Drift lives in the gaps between the layers, so you need all four.

What goes in a global CLAUDE.md?#

My global CLAUDE.md — the one in ~/.claude/ that loads in every project — is not a preferences file. It's the constitution. It holds the rules that must hold no matter which brand or repo the agent is standing in: how to resume after an interruption without asking, how to queue multiple projects, when to ask versus decide, and a content-standards rule that governs every word of copy the fleet produces, for every client, with no exceptions.

The pattern that matters: global rules are written as directives with consequences, not vibes. "AUTO-RESUME: if you get interrupted for ANY reason, continue exactly where you left off. Never ask 'should I continue?'" reads very differently to a model than "try to be resilient." Sections carry labels like ALWAYS ACTIVE and NON-NEGOTIABLE because — measurably, in my experience across thousands of agent runs — emphasis changes compliance.

The global file is also where I put rules that would be dangerous to leave to per-project memory: a language standard I will not compromise on ships in the global file precisely so that no project, brief, or template can override it. If a rule must survive contact with every possible task, it goes in the layer that loads before every possible task.

What goes in a per-project CLAUDE.md?#

Every project I operate has its own CLAUDE.md in the repo. Most people write these like sticky notes: a few preferences, a tech-stack mention. Mine read like the operations manual you'd hand a new employee on day one, because that's functionally what they are.

A working project CLAUDE.md for one of my brands contains the brand's positioning, voice rules with good and bad examples side by side, the exact content formula every piece must follow, the claims the brand is and is not allowed to make — including one manufacturing claim documented down to the exact ceiling phrase the agent may use and the phrases it may never use — and explicit "never do this" lists. When an agent produces content at 3 a.m. with nobody reviewing it, that file is the difference between on-brand output and generic slop.

The test I apply: if I hired a competent stranger and gave them only this file, would they produce acceptable work? If not, the file is incomplete — and the agent will drift exactly where the file is silent.

Two details that do disproportionate work:

• Good and bad examples side by side. My brand files include a "voice calibration" section with real sentences labeled write like this and never write like this. Agents calibrate on contrast far better than on adjectives.
• Dated claim locks. When a factual claim gets verified or corrected, the file records the date and the reasoning, not just the rule. "Confirmed 2026-07-15: never claim X; Y is the ceiling" survives skeptical re-reading by a future agent in a way a bare prohibition doesn't.

What is the difference between a hard rule and a preference?#

Not all instructions carry the same weight, and agents need to know which is which. I separate them explicitly, at both the global and project layers:

Hard rules are non-negotiable and labeled that way in the file: never fabricate metrics, never touch these frozen pages, never deploy — a human runs the deploy script, never replace a client's images with stock or AI substitutes, never send an email without approval. These get words like "HARD RULE" and "NON-NEGOTIABLE" in the text.

Preferences are defaults the agent may override with judgment: formatting choices, tone calibration, which library to reach for first.

When everything is written with equal weight, agents treat everything as a preference. The drift starts precisely at the rules you didn't mark as rules.

What is a Claude Code skill and when should you write one?#

CLAUDE.md is always-on context; skills are procedures loaded when a task matches. I maintain custom skills for repeatable workflows — a blog framework that encodes the on-page structure every post must follow, a photo-culling workflow, an ad-production pipeline, a book-production process, a brand-voice skill per brand.

The principle: any workflow I've corrected twice becomes a skill. If I had to tell an agent "no, do it this way" more than once, that correction is now a documented procedure with steps, checks, and examples — not something I hope the next session remembers. Skills turn one-time fixes into permanent capability, which is the core loop of the whole approach I described in what running five brands with agent fleets actually looks like.

The division of labor is clean: if an instruction applies to everything an agent does in a project, it's context and belongs in CLAUDE.md. If it applies to one kind of task — produce a post, cull a shoot, cut an ad — it's a procedure and belongs in a skill, where it costs nothing until that task shows up. That cost question is not cosmetic; it's the whole discipline of context engineering for solo-operator fleets: every token of always-on instruction competes with the actual work for the model's attention.

How does agent memory differ from CLAUDE.md?#

Sessions end; lessons shouldn't. I run a memory system — an indexed set of markdown files — that persists across every conversation. The architecture is deliberately two-tier:

• MEMORY.md is an index, not a document. It's a compressed table of contents: one line per lesson, each linking to a dedicated memory file with the full detail. A "TOP RULES — read first" section sits at the very top so the most dangerous rules are the first thing any new session sees.
• The linked files carry the detail. Each is small, single-topic, and named by type, so the index stays scannable while nothing gets lost.

The naming convention is the system. Files prefixed feedback_ are corrections — "never do X, always do Y," written the moment I correct an agent. Files prefixed reference_ are facts — infrastructure maps, account structures, deploy gotchas an agent needs but shouldn't rediscover. Files prefixed project_ are state — where a long-running effort stands, so the next session resumes instead of restarting.

Real entries from my own index, so you can see the texture: a feedback_ file that says a link must be published and return HTTP 200 before it's ever emailed; one that says certain live pages are frozen and must never be touched unless explicitly asked; one that locks a brand's manufacturing claim to exact permitted wording; a reference_ file documenting a launchd PATH gotcha that silently kills scheduled jobs — the kind of thing that cost an evening once and will never cost an evening again.

The pattern of encoding every correction as a permanent rule is the highest-leverage habit in this entire post. Every time I correct an agent, that correction becomes a feedback_ file and a line in the index before the session ends. Without this, every session starts naive and repeats last month's mistakes; with it, the fleet compounds instead of resetting. I go deeper on the mechanics — file formats, index hygiene, what to prune — in the agent memory primer.

How do you make an agent verify its own work?#

The most dangerous agent behavior is declaring victory. "Done" from a language model means "I produced output," not "it works." So completion is defined operationally, never rhetorically:

An agent may not report a task complete until it has exercised the thing end-to-end — loaded the page, run the script, checked the HTTP status, viewed the generated image. I keep a standing rule that any asset must be viewed before being presented, because generation pipelines fail silently and an unexamined "success" is how a broken image ends up in front of a customer.

For scheduled automation the bar is higher still: "armed" means the launchd job or cron entry is verified as loaded and a manual end-to-end run has succeeded — not that the config file exists. My memory index literally contains a rule titled "24/7 = actually scheduled" for this reason: a schedule earns the label "running" only when the schedule itself was tested, not assumed. More on that failure class in scheduled AI agents that work while you sleep.

Customer-eye QA#

Technical verification catches broken; it doesn't catch bad. The last gate is looking at the output the way the end user will: open the page at real size in a real browser, read the email as the recipient, watch the video without the creator's forgiveness. Agents check DOM elements and exit codes; a customer sees an overlapping header and an off-brand headline. I encode this as an explicit final step — render it, look at it, compare it against a known-good reference — because "the tests pass" and "a buyer would trust this" are different claims.

What is the checklist for preventing agent drift?#

If you're running agents on real work, here's the system in order:

1. Put non-negotiable, cross-project rules in a global CLAUDE.md that loads everywhere
2. Write each project's CLAUDE.md as an operations manual — positioning, voice, formulas, forbidden actions — not a sticky note
3. Include good AND bad examples side by side; agents calibrate on contrast
4. Mark hard rules explicitly and separate them from preferences
5. Convert every workflow you've corrected twice into a skill — a named, documented procedure
6. Maintain a persistent memory index; write a feedback_ record the moment you correct an agent, and link it from the index
7. Define "done" operationally: the agent must exercise the output end-to-end before reporting completion
8. Require customer-eye QA as the final gate — view the deliverable as the buyer will
9. Verify scheduled automation is actually armed (job loaded, manual run succeeded), never just configured

None of this is exotic. It's the same discipline any operations leader applies to a human team — documented procedures, explicit non-negotiables, institutional memory, inspection before shipping — applied to a workforce that reads instructions perfectly and forgets everything between shifts.

This is also the layer most people skip, which is why "we tried agents and they were unreliable" usually means "we ran agents without SOPs." The tooling matters less than the operating system around it — more on that in what an AI systems builder actually does.

FAQ#

How long should a CLAUDE.md file be?#

As long as an onboarding doc for a competent stranger needs to be — mine run from one page for simple projects to several pages for a full brand. The constraint isn't length; it's that every line must earn its place, because always-on context competes with the actual task for the model's attention.

What goes in the global CLAUDE.md vs. a project CLAUDE.md?#

Global holds rules that must hold everywhere regardless of project: execution doctrine, safety rules, standards you will never compromise on. Project files hold everything specific to one brand or codebase: voice, claims, architecture, forbidden actions. If a rule breaking in any project would be unacceptable, it's global.

What's the difference between putting something in CLAUDE.md and a skill?#

CLAUDE.md holds always-relevant context: identity, rules, constraints. Skills hold task-specific procedures loaded on demand: how to produce a blog post, how to cull a photo shoot. If it applies to everything, it's context; if it applies to a workflow, it's a skill.

How do I stop an agent from repeating a mistake I already corrected?#

Write the correction down as a permanent rule the moment you make it — in my system, a feedback_ memory file linked from a top-level MEMORY.md index that every session reads first. A correction that lives only in one conversation is deleted the moment that conversation ends.

Can this work with agents other than Claude Code?#

Yes. The pattern — persistent SOP context, hard-rule separation, on-demand procedures, memory records, verification gates — is tool-agnostic. Claude Code happens to make it natural with CLAUDE.md and skills, but the discipline is what stops drift, not the file format.

— Italo Campilii. If you're building something that needs this kind of operator, get in touch.