Your rules file is too long: what stays, what moves

The first version of the CLAUDE.md in my company's main repo (the rules file Claude Code reads in full at the start of every session) was 13 lines long.

That was late July. The commit message said: "This file is deliberately minimal: only project rules that must be followed without exception. Day-to-day conventions stay in their own skills and docs." Three months later it's 26 lines, and the first line still says the same thing:

This file holds only the project rules that must be followed without exception. Day-to-day conventions go in their own skills and docs. Don't pile things in here.

Rules files tend to grow. Tech stack, directory layout, naming conventions, how to run tests, how to deploy, plus one more "don't do that again" after every mistake. Each line makes sense on its own. But the agent reads the whole file into context every session, and "we use pytest," which it could learn by glancing at the code, sits right next to "never merge your own PR," which it must not get wrong. They look equally important. The few rules that really matter get diluted.

What stays: things that must hold every time

To decide whether a line stays, I ask one question: if the agent didn't read this today, would something go wrong?

What's left in those 26 lines, roughly: branch from the latest main; every PR description has Validation, Risk, and Rollback sections; decisions about user-facing copy, billing, or restricting users get listed under "open to veto"; changes to model behavior go in their own PR; follow-ups that aren't handled go into the ledger (a directory in the repo just for follow-ups). None of these depend on the task. They apply every time, breaking them is costly, and the agent can't infer them from the code.

The interesting part is that the first 13 lines covered exactly one thing: don't leave follow-ups only in the chat reply. I had written that rule as a skill first, and the same day I moved it into the rules file. The commit message says why: "auto-triggering from the skill description isn't reliable enough; things get missed." A skill depends on the agent deciding when to use it, and sometimes it decides wrong. The rules file gets read every time, no decision involved.

So the point of a short rules file isn't shortness. It's making sure the rules that must hold every time actually get read every time.

What moves, and where

Steps for doing something go into skills. Deploying, querying the database, publishing a page as a link: in that repo each is a skill. Normally only a short description sits in context, and the full text loads when the task comes up.

Code conventions go into docs. What lives in which directory, what's tricky about a module: the agent can read that when it touches that code. It doesn't need to memorize it every session.

The third kind is the easiest to miss: state. On October 8 I made two commits to the rules file back to back, and both did the same thing: remove statements that had gone stale. One said CI was stopped over billing, when it was already running again. The other described how CI worked before a rework. After the fix, the file said "Actions came back in early October." A few days later the quota ran out again and CI stopped for a while.

A rule, once written, holds for a long time. State, once written, becomes false the moment it changes, and the agent will still make decisions based on it. Where the project stands and what went wrong last time, I keep in memory instead. The memory index also loads every session, so in mid-September I cut it from 33KB to 9KB: one short line per entry in the index, the details in separate files read only when the topic comes up, finished projects moved to an archive index. The same day I turned off 34 unused skills in that project. Every skill's description sits in context too, and an unused one just takes up room.

How to start

Open your current rules file and ask three questions about each line. If the agent didn't read this today, would something go wrong? Is it a rule or a state? Could the agent figure it out from the code?

If the answer to the first is "no," or to the third is "yes," move it or delete it. If the second is "state," move it to docs or memory, and leave at most a pointer in the rules file.

What's left are your non-negotiables. Here's the skeleton of mine; adapt it as you like (Codex reads AGENTS.md, same idea):

# Project rules

> Only the rules that must be followed every time. Steps for doing
> things go in skills, code conventions go in docs, project state and
> lessons learned go in docs or memory. Don't pile things in here.

## Before adding a line, ask
- If the agent didn't read this today, would something go wrong?
  If not, it doesn't belong here
- Is it a rule or a state? State goes stale; put it in docs
- Can the agent figure it out from the code? Then don't write it

From 13 lines to 26, the one thing the first version covered is still there, and every line added since applies to every task. The first line, "Don't pile things in here," has never been removed.