JQ Rules
Every team using AI coding agents ends up with a CLAUDE.md in each repo. They start as a good idea. Then they get copied to the next repo, drift apart, and fill with rules nobody remembers the reason for — and every session pays for all of them.
The thesis
The point of a rules tool is not to help you write more rules. It is to help you keep fewer of them.
The scarce resource is not storage — it is the agent’s attention, and the tokens every session spends re-reading your instructions before it does anything. A tool that makes adding rules easy without making removal easy is a ratchet: you end up with twenty thousand tokens of instructions where four thousand were doing the work.
So the measure of this thing working is rules retired, not rules managed. Everything else follows from that.
Our own repos, since that’s evidence you can check
We’re not going to tell you other people have this problem and ask you to take our word for it. Here is ours, measured today. Run the same command on yours:
find . -maxdepth 2 -name CLAUDE.md | xargs wc -c
Two things in that table are the whole product. The top repo spends twenty thousand tokens of instructions before it does any work, on every session, forever — and nothing in the workflow displays that. And the second repo is a fork of the first that has since drifted, so nobody can now say which differences were deliberate and which are just stale copies.
What it would do
Every rule carries why it exists
Not just the rule — the incident that caused it, the pull request you can go read, and the condition that would make it safe to delete. A rule with no incident behind it is somebody’s preference; a rule with no retirement condition is permanent by accident.
One baseline, per-repo overrides, and an override needs a reason
Repos differ, and they should be able to. But an override with a reason is a decision, and an override without one is drift — and right now every divergence is the second kind, because there is nowhere to put the reason.
A drift view
Which repos are behind the baseline, which have overrides nobody has reviewed, which rules exist in exactly one repo and probably shouldn’t. This is the part a lead opens weekly.
What your rules cost, per repo
Instructions are read on every single session. Nothing in your workflow shows you that bill, so the files only ever grow. Seeing the number is what makes anyone prune.
Retirement prompts — it asks, it never deletes
When a rule’s retirement condition looks met, or its incident is a year old and never recurred, it gets surfaced for a human to decide. The condition is a claim to check, not a trigger to fire.
What it will never claim
That your agent followed the rules. Nothing in a session’s record reliably shows a rule being applied, so a compliance score would be measuring nothing — and would be believed, which is worse than measuring nothing openly. It can show you which rules were in force when a change shipped, and whether that change needed reworking. That’s context for a person, not a number to manage people by.
Where this actually is
Not built. The idea came from repeatedly hitting the problem while working across other people’s codebases, and the numbers above are our own. If you run agents across more than one repo, or more than one person, tell us — that's what decides whether this gets built and which half comes first.
Part of JQ. Sibling of JQ Agents, which shows you what your running sessions are doing.