We Didn't Onboard Claude Opus 5.5. A File Did.

Anthropic released Claude Opus 5.5 on September 22, 2026. At 8:46 that evening, Chile time, the first commit crediting the new model landed on our main branch. By 1:27 a.m. there were 12 of them: 12 finished changes, each merged through a pull request. Among them: our About page's live feed of AI agent activity moved to the top of the page, a speed fix for how we verify email domains, two failing checks in our publishing pipeline fixed, new short videos queued for Instagram, and the news post about its own launch.

Nobody walked it through how we work. There was no onboarding call, no brand deck, no list of past mistakes to avoid. It read a file.

The file is called CLAUDE.md. It sits at the root of our repository, it runs 552 lines as of September 23, and every Claude Code session that works on our code loads it before doing anything else. It didn't change for the new model. The last edit before launch was on September 21, about something else entirely.

Ten models in six months

Commits that an AI co-writes in our repository carry a credit line naming the model. Counting those credits on our main branch on September 23, ten different Claude models have done real work here since April 2026:

• Opus 5: 597 commits
• Fable 5: 424
• Opus 4.8: 390
• Opus 4.7: 303
• Sonnet 4.6: 191
• Sonnet 5: 141
• Fable 5.1: 99
• Opus 4.6: 40
• Haiku 4.5: 40
• Opus 5.5: 12 on its first night, and counting

That's 2,223 commits with a Claude model named as co-author, out of 5,913 on the branch. Most of the rest are automated backups and scheduled publishing. The model with the most commits changed four times: Sonnet 4.6 led in April, Opus 4.7 in May, Opus 4.8 in June, Fable 5 in July, and Opus 5 in August and September. Opus 5.5 is the next handoff.

None of those models remembers anything the others worked out. Nothing a model figures out during a session carries over unless someone writes it down. If our know-how lived inside the models, we'd have started from zero every few weeks. It lives in a file instead, and every model since the file was created in late April has started by reading it.

Your AI doesn't learn from your mistakes. Your rules file does.

What's in the file

It isn't a style guide, and it isn't a prompt full of adjectives. It has four parts:

1. Hard constraints. Fifteen rules that override everything else, each pointing to the one place that holds the details. Three of them: we serve exactly 14 industry niches and never invent a fifteenth; English and Spanish copy change together or not at all; everything deploys to one host, never another.
2. A checklist before every commit. Each item maps to a known way to break production.
3. A symptom-to-cause table. "A new folder returns 404 while everything else loads" points straight to its cause: the folder was added to one of the two lists the deploy needs, not both. Every row in that table cost us a real deploy.
4. Pointers, not copies. The deep detail lives in nine separate documents that a model opens only when it works in that area, so the part it reads every time stays short.

Behind the file sit two stricter layers. Thirty automated tests block a deploy if a known failure comes back. A handful of hooks refuse specific actions outright, before a model can take them. A rule a model reads is good. A rule a machine enforces is better.

Every rule has a scar

Many of the rules carry the date something went wrong. Three examples:

"On-screen text comes from a font, never from a video model."

On September 5, 2026, a short video went live on our Instagram with the words "Numbers Don't Lie" rendered by an AI video model as "Numnees Dont Liie." The rule now says burned-in text is set in a real font by code, and a check reads the actual frames of a video and compares them with the words we expected before it goes out.

"A green run is not proof."

Some of our deploy jobs skip their upload when a credential is missing and still finish with a green checkmark. A site can look updated in the dashboard and keep serving the old page. The rule: check the live page, not the checkmark.

"Never publish a near-duplicate."

When three pages on one site cover the same thing, search engines struggle to decide which to rank, and often rank none of them well. Every draft on this blog is compared with everything already published before it can go out.

What Opus 5.5 did with it on day one

This post is the clearest example we have. The request was one line: write a post about Claude Opus 5.5 that could go viral. The model's first move wasn't writing. It searched our blog and found a launch recap of Opus 5.5 that had gone live about four hours earlier, co-written by Opus 5.5 itself. The file says never publish a near-duplicate, so it didn't write a second recap. You're reading the alternative.

Then it ran into a second rule: no figure without a source. Every number in this post comes from Anthropic's announcement or from our own repository, counted on September 23. There's no "10x productivity" claim here, because there's no source for one.

Why a better model makes the file matter more

Anthropic's announcement makes two claims that bear directly on this. It says Opus 5.5 is far less prone than recent models to irreversible actions or to "act outside the boundaries it's been given," and that it resists prompt injection better than Opus 5 (Anthropic). Boundaries only help if someone has written them down. A model that respects them more reliably makes the document that sets them worth more, not less.

The costs point the same way. Anthropic lists Opus 5.5 at $4 per million input tokens and $20 per million output tokens, down from $5 and $25 for Opus 5, and says it costs 40% less to run than Opus 5 (Anthropic). A rules file is sent at the start of every session, which makes it exactly the kind of repeated text prompt caching is built for, and Anthropic cut cache reads from $0.50 to $0.20 per million tokens (Anthropic).

How to write your own

You don't need a codebase for this. If your team uses Claude in the browser, the same idea is the standing instructions you give a project. Six habits that have held up for us:

1. Write rules, not vibes. "Be professional" changes nothing. "Never quote a price in a caption" changes behavior.
2. Attach the reason and the date. A rule without a why gets deleted by the first person who finds it inconvenient, human or model.
3. Write the rule the day it breaks. The details are freshest then, and the next session is only hours away.
4. Keep the always-read part short. Put deep detail in separate documents and link to them, so they're read only when they're needed.
5. Promote your top rules to checks. If breaking a rule would cost real money or trust, make a test or a hook enforce it instead of trusting anyone to remember.
6. Point to the source of truth instead of copying it. Copies drift. Each fact in our file links to the one place it lives.

The format we'd steal first is the shortest one. Every rule gets three parts:

Rule: on-screen text comes from a font. Why: a video model spelled "Numbers Don't Lie" as "Numnees Dont Liie" and it went live. Date: September 5, 2026.

Quick answers

What is a CLAUDE.md file?

A plain-text file of instructions that Claude Code loads at the start of every session in a project. Teams use it for rules, conventions and known pitfalls, so every session starts with the same context no matter which model is running.

Do I need to rewrite my instructions for Claude Opus 5.5?

Not in our experience so far: our file carried over from Opus 5 unchanged. One change from Anthropic's announcement is worth checking in your own setup: Opus 5.5 is no longer available with thinking switched off (Anthropic).

Does Claude remember what it learned in earlier sessions?

Only what's written down. A lesson that never makes it into a file the next session reads, such as CLAUDE.md, doesn't carry over to that session, and it doesn't carry over to the next model either.

The next model is weeks away

Anthropic says Claude Sonnet 5.5 and Claude Haiku 5.5 will follow in the coming weeks (Anthropic). When they arrive, they'll read the same file Opus 5.5 read, plus whatever we add between now and then. That's the whole plan. The model is the part we expect to replace. The file is the part we keep.

If you want to watch this happen, our About page shows what our AI agents are working on, live.

Want an outside read on where AI fits in your own marketing? Start with our free website audit, or message us on WhatsApp if you'd rather talk to a person.

How this post was made: Claude Opus 5.5 drafted it inside our repository on September 23, 2026, working under the same file it describes. Commit counts come from the commit history of our main branch on that date; model names are the co-author credits those commits carry.

← Back to all articles