I Audited My AI's Briefing File. It Had Turned Into a Diary.

Coding agents like Claude Code read a plain-text briefing file before they do anything else. Mine is called CLAUDE.md, and it sits in the home directory of the small server I run my automation on. It tells the agent who I am, what's installed, which services run where, what the cron jobs do, and the handful of rules I don't want broken. It loads into every session, whatever I'm working on.

I'd been adding to it for six months. After two model releases in ten days, I ran Claude Code's new prompt audit on it (/checkup prompt-audit). The audit reads your instruction files and flags text written for older models: ALL-CAPS warnings, "think step by step", rigid scripts. It writes a report and a patch and changes nothing until you say so.

I expected it to find shouting. It found almost none. What it found instead was more useful, and it changed how I think about the file.

What I expected

The audit's main checklist is about prompting habits that used to help and now hurt. Older models needed forceful instructions to follow anything reliably, so people wrote IMPORTANT: and NEVER everywhere. Current models follow instructions closely and literally, so the same shouting makes them over-apply a rule and behave rigidly in situations it was never meant for.

My file had exactly one of those: a rule in capitals about using a site-specific command-line tool only for the site it was built for. The fix was to say it at normal volume and keep the reason: "the other sites have no command center." Two other spots used capitals for emphasis, but they stated facts, not rules, so the audit left them alone.

That was the whole outdated-prompting section of the report. One finding.

What it actually found

A quarter of the file was history.

The cron section was meant to list my scheduled jobs. Over the months its header had grown into an 880-word paragraph about what I'd removed: which jobs were cut on which date, why, where the backups went, the traffic numbers that made me drop three sites, which repository was left untouched. Every entry had been accurate when I wrote it. None of it was something the agent needed to do anything.

Several facts had quietly gone wrong.

• The file listed the Gemini CLI at a specific path. It wasn't installed there, or anywhere.
• It gave a version for one of my agent gateways that was two months out of date.
• It listed four API keys in my environment file. There were more than a dozen.
• It listed the tools wired into my voice assistant and was missing one.

None of these would cause a crash. They'd cause a confident wrong answer: the agent telling me "use the Gemini CLI at this path" and spending a turn finding out it isn't there.

One rule was a security habit dressed as documentation.

Under my blog's repository it said: "Git push requires the token in the remote URL", followed by the exact command to paste a GitHub token into the repo's config. That was true once, because nothing else was set up to handle the login. But it's an instruction, so every time the agent pushed, it would write a live credential into a plain-text file. I'd already cleaned that exact pattern out of two other repos a few weeks earlier, and the instruction file was still teaching it.

The flip

I'd been treating CLAUDE.md as documentation, a notebook about my server that the agent happens to read.

It isn't documentation. It's a prompt that runs every session, and every sentence in it is a sentence the model acts on.

Once you see it that way, the findings stop looking like housekeeping:

• History in a prompt isn't a record, it's noise the model has to work around. "Removed on 2026-08-25, backup at this path, 82 days of rank history pruned" reads as context to me. To a model that treats everything in its instructions as relevant, it's a pile of half-relevant facts competing with the ones that matter. The one useful rule hidden in that paragraph ("these jobs were removed on purpose, so check before adding them back") was the part hardest to find.
• A stale fact in a prompt isn't out-of-date documentation, it's a wrong instruction. A wiki page with an old version number just sits there. The same line in a prompt gets acted on.
• A how-to in a prompt isn't a note, it's a standing order. "Put the token in the URL" stopped being a description of how I once got a push to work. It became the default.

The audit's own guide puts it in one line: the job is to find "specific instructions that no longer fit", not to make prompts shorter. My file didn't have an old-model problem. It had the problem every long-lived config file gets: it kept accumulating and nothing ever removed anything.

What I changed

The patch had nine hunks, each tied to one finding, so I could take or skip them one at a time. I took all of them.

• Moved the history out. The 880-word paragraph went verbatim into a separate cron-history.md that isn't loaded automatically. The cron header is now one line with the job count and a pointer: "read it before re-adding a removed job." The schedule itself stayed.
• Fixed the facts. Dropped the Gemini line, corrected the version, listed the real key names, and added the missing voice-agent tool.
• Kept rules, dropped stories. Several sections had a current rule with an incident wrapped around it, like "Seen on 2026-09-22: a session started at 14:48 picked up the new package but still ran the old code…" The rule (restart the process after a config change, because clearing the session isn't enough) stayed, with its reason. The timestamped story went.
• Fixed the token rule properly, not just the wording. I set git to use the GitHub CLI's existing login for pushes (gh auth setup-git), confirmed a dry-run push worked, and only then replaced the line with "plain git push, never put a token in the remote URL." Then I checked every local repo for a token in its remote URL. There were none.

Two smaller things went too. I removed account-balance figures from a list of fallback models, since balances drift and nothing on the machine could confirm them. I also moved four skills for a framework I'd stopped using out of the global skills folder: their descriptions were loading into every project.

The file went from about 3,700 words to 2,760. That wasn't the goal, just a side effect of removing what didn't belong.

What the audit left alone, and why that matters

The audit has an explicit list of things it must not delete, and it followed it. It kept:

• the rules that carry a reason, like "don't re-optimize this page's title, the low click rate comes from the search results layout, not the title";
• two identical copies of a scaffold file in two project folders, because they agree;
• my one-line note that I prefer short, direct answers, because that's context about me, not an outdated trick.

That restraint is the part I'd have got wrong doing this by hand. My instinct with a bloated file is to cut it hard, and a hard cut removes exactly the lines that only I could have written: the reasons. The model can work out how to be thorough by itself. It can't work out why I don't trust a particular page's metrics.

If you keep one of these files

Some things I'm doing differently now:

• Write the rule, not the story. If a line describes something that happened, ask what the agent should do differently because of it, and write that sentence instead.
• Give history its own file. A changelog is valuable. It just shouldn't load into every session. Point to it from the briefing file, and the agent can read it when it's relevant.
• Check facts against the machine, not your memory. Paths, versions and key names drift silently. The audit caught four because it checked them, not because they looked wrong.
• Read every how-to as a standing order. If you wouldn't want the agent to do it every time without asking, it doesn't belong in the file as an instruction.

The file is shorter now, but that isn't the improvement. The improvement is that everything left in it is something I actually want the agent to act on.