{"slug": "your-claude-md-is-full-of-lint-rules-in-disguise", "title": "Your CLAUDE.md Is Full of Lint Rules in Disguise", "summary": "A developer built codemyrules, an agent skill that converts coding conventions and agent instructions into executable lint rules, and benchmarked the approach with roughly 500 headless Claude Code sessions across four real Kotlin, Java, Python and TypeScript projects. The benchmark, published as agent-rules-bench, compared rules written as prose in CLAUDE.md against the same rules enforced as lint rules with a feedback loop, arguing that machine-checkable conventions belong in lint rules while prose docs should hold domain knowledge and the why. The generated rules work with any coding agent, though the hook-based feedback loop currently runs only in Claude Code.", "body_md": "Every team using coding agents eventually ends up with a growing **CLAUDE.md** or **AGENTS.md**.\n\n*\"Inject a `Clock`, never call `now()` directly.\"*\n\n*\"Fetch data through query composables, never call `fetch()` in a component.\"*\n\n*\"Log messages start lowercase.\"*\n\nAnd twenty more instructions, each added after an agent got something wrong.\n\nThe 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.\n\nThe agent keeps making the same mistakes.\n\nThere'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.\n\nTake the `Clock` rule. In CLAUDE.md, it's a sentence the agent may or may not follow:\n\n```\n- Always inject a `Clock`. Never call `LocalDateTime.now()` or `Instant.now()` directly.\n```\n\nAs an ast-grep rule, it's a check that runs on every edit:\n\n```\nid: inject-clock\nlanguage: kotlin\nseverity: error\nmessage: Don't call now() directly. Inject a Clock and use now(clock).\nrule:\n  pattern: $TYPE.now()\n```\n\nWhen the agent writes `Instant.now()`, it gets feedback like this a few seconds later, while it's still working on the file:\n\n```\nerror[inject-clock]: Don't call now() directly. Inject a Clock and use now(clock).\n  src/main/kotlin/.../InvoiceService.kt:42\n```\n\nIt fixes the code before it ever reaches review. The CLAUDE.md line shrinks to a one-line pointer, or disappears entirely.\n\nI 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.\n\nMethodology, data and harness to rerun it on your own repo: **[agent-rules-bench](https://github.com/clirimajeti/agent-rules-bench)**.\n\n**[codemyrules](https://github.com/clirimajeti/codemyrules)** is an agent skill that turns your existing decisions, coding conventions, and agent instructions into executable lint rules.\n\nIt works with the knowledge your team already has:\n\nNothing 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.\n\nThe 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.\n\nThe skill picks the first option that fits:\n\n`sgconfig.yml`.\nNot 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.\n\nIt 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.\n\nThe generated lint rules work with any coding agent or harness (the tool that runs the agent): Claude Code, Codex, Copilot, Cursor and others.\n\nThe 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.\n\nIn Claude Code, install the plugin:\n\n```\nclaude plugin marketplace add clirimajeti/codemyrules\nclaude plugin install codemyrules@codemyrules\n```\n\ncodemyrules drives one sub-skill per stack, so add the ones you need: [eslint-pattern-rules](https://github.com/clirimajeti/eslint-pattern-rules) for frontend and [backend-pattern-rules](https://github.com/clirimajeti/backend-pattern-rules) for backend. The [README](https://github.com/clirimajeti/codemyrules#installation) has the commands, plus setup for other agents.\n\nThen ask your agent:\n\n```\nTurn our ADRs and AGENTS.md into lint rules.\n```\n\nThis is the first public release, and I'd love to see what happens when you run it against a real codebase.\n\nTell me what it found, what it missed, and how much of your CLAUDE.md turned out to be lint rules in disguise.\n\nComments here and [issues on GitHub](https://github.com/clirimajeti/codemyrules/issues) are both welcome.", "url": "https://wpnews.pro/news/your-claude-md-is-full-of-lint-rules-in-disguise", "canonical_source": "https://dev.to/clirimajeti/your-claudemd-is-full-of-lint-rules-in-disguise-6hb", "published_at": "2026-11-05 12:40:56+00:00", "updated_at": "2026-11-05 12:49:39.142419+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "large-language-models"], "entities": ["codemyrules", "agent-rules-bench", "Claude Code", "Codex", "Copilot", "Cursor", "ast-grep", "OpenCode"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/your-claude-md-is-full-of-lint-rules-in-disguise", "markdown": "https://wpnews.pro/news/your-claude-md-is-full-of-lint-rules-in-disguise.md", "text": "https://wpnews.pro/news/your-claude-md-is-full-of-lint-rules-in-disguise.txt", "jsonld": "https://wpnews.pro/news/your-claude-md-is-full-of-lint-rules-in-disguise.jsonld"}}