Your CLAUDE.md Is Full of Lint Rules in Disguise

Every team using coding agents eventually ends up with a growing CLAUDE.md or AGENTS.md.

"Inject a Clock, never call now() directly." "Fetch data through query composables, never call fetch() in a component." "Log messages start lowercase."

And twenty more instructions, each added after an agent got something wrong.

The file keeps growing, and every line eats into a limited context window. So you split it into folders and linked docs. Now less gets loaded, but a doc the agent never opens is a rule it breaks.

The agent keeps making the same mistakes.

There's a better split: prose for what only prose can say (business logic, domain knowledge, the why ), lint rules for everything a machine can check. A lint rule stays silent while the agent gets it right. When it doesn't, the feedback loop points to the exact line within seconds, and the agent fixes it on its own.

Take the Clock rule. In CLAUDE.md, it's a sentence the agent may or may not follow:

- Always inject a `Clock`. Never call `LocalDateTime.now()` or `Instant.now()` directly. Enter fullscreen mode Exit fullscreen mode As an ast-grep rule, it's a check that runs on every edit:

id: inject-clock language: kotlin severity: error message: Don't call now() directly. Inject a Clock and use now(clock). rule: pattern: $TYPE.now() Enter fullscreen mode Exit fullscreen mode When the agent writes Instant.now(), it gets feedback like this a few seconds later, while it's still working on the file:

error[inject-clock]: Don't call now() directly. Inject a Clock and use now(clock). src/main/kotlin/.../InvoiceService.kt:42 Enter fullscreen mode Exit fullscreen mode It fixes the code before it ever reaches review. The CLAUDE.md line shrinks to a one-line pointer, or disappears entirely.

I ran about 500 headless Claude Code sessions on four real projects in Kotlin, Java, Python and TypeScript. Each run compared a rule written as prose with the same rule as a lint rule plus a feedback loop.

Methodology, data and harness to rerun it on your own repo: agent-rules-bench.

codemyrules is an agent skill that turns your existing decisions, coding conventions, and agent instructions into executable lint rules.

It works with the knowledge your team already has:

Nothing is changed without your approval. The feedback loop is private by default: it installs into.claude/settings.local.json and is git-excluded, so no tracked file changes until you decide to share it with your team.

The goal isn't to replace your CLAUDE.md or AGENTS.md with a giant collection of lint rules. It's to stop using prose for conventions a machine can check, and keep your docs for the context only prose can give.

The skill picks the first option that fits:

Not every convention is a lint rule. "Keep services small and focused" or "name things after the domain, not the framework" need judgment, and they stay in your docs. codemyrules is for the rules a pattern match can catch.

It also won't turn your CI red on day one. Rules your existing code already breaks go into a separate suggestions layer, so they guard new code without forcing you to fix legacy code first. And the feedback loop only blocks on lines the agent changed, so it never drags the agent into unrelated cleanup.

The generated lint rules work with any coding agent or harness (the tool that runs the agent): Claude Code, Codex, Copilot, Cursor and others.

The feedback loop is built on Claude Code hooks, so for now it's only offered in Claude Code. I'm working on bringing it to Codex, pi, OpenCode, and other coding-agent environments.

claude plugin marketplace add clirimajeti/codemyrules claude plugin install codemyrules@codemyrules Enter fullscreen mode Exit fullscreen mode codemyrules drives one sub-skill per stack, so add the ones you need: eslint-pattern-rules for frontend and backend-pattern-rules for backend. The README has the commands, plus setup for other agents.

Turn our ADRs and AGENTS.md into lint rules. Enter fullscreen mode Exit fullscreen mode Feedback welcome This is the first public release, and I'd love to see what happens when you run it against a real codebase.

Tell me what it found, what it missed, and how much of your CLAUDE.md turned out to be lint rules in disguise.

Comments here and issues on GitHub are both welcome.