DEV Community: Alexandru Cioc

AI Agents Don't Follow Your Rules. Here's a Compiler That Makes Them.

Alexandru Cioc — Fri, 10 Apr 2026 18:24:23 +0000

The Problem Nobody Talks About

You've set up Claude Code with a careful CLAUDE.md. Your Cursor rules are dialed in. Your AGENTS.md covers Codex. Maybe you've got copilot-instructions.md too.

They all say roughly the same thing:

Run npm test before committing
Use TypeScript strict mode
Don't use any — use unknown
Follow conventional commits

But they're separate files. Maintained separately. And they drift.

We cloned 50 of the highest-profile open-source repos — grafana, django, vue, prisma, supabase, airflow, tokio — and ran a governance audit on each one.

46% had drift. Rules that reference commands that don't exist. Configs older than the governance they were compiled from. AI agents being told to run lint scripts that were removed months ago.

The Fix: Treat It As a Compilation Problem

crag is a CLI that takes one governance.md and compiles it to every AI tool format your team uses.

npx @whitehatd/crag

That single command:

Analyzes your repo — reads CI workflows, package.json, tsconfig, Makefiles, directory structure — and generates governance.md with your actual gates, architecture, testing profile, code style, and anti-patterns.
Compiles to 13 targets — each in the tool's native format, with correct frontmatter and activation patterns.

Here's what one command generates:

Target	Output	Consumer
`agents-md`	`AGENTS.md`	Codex, Aider, Factory
`cursor`	`.cursor/rules/governance.mdc`	Cursor
`copilot`	`.github/copilot-instructions.md`	GitHub Copilot
`gemini`	`GEMINI.md`	Gemini, Gemini CLI
`claude`	`CLAUDE.md`	Claude Code
`cline`	`.clinerules`	Cline
`continue`	`.continuerules`	Continue.dev
`windsurf`	`.windsurf/rules/governance.md`	Windsurf
`zed`	`.rules`	Zed
`amazonq`	`.amazonq/rules/governance.md`	Amazon Q
`github`	`.github/workflows/gates.yml`	GitHub Actions
`husky`	`.husky/pre-commit`	husky
`pre-commit`	`.pre-commit-config.yaml`	pre-commit.com

One file in, thirteen files out. Change a rule, recompile, done.

What the Analyzer Actually Finds

Run crag analyze on a real project and it reads:

25+ language detectors — Node, TypeScript, Python, Go, Rust, Java, .NET, Swift, Elixir, and more
11 CI system extractors — GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis, Azure Pipelines...
8 framework convention engines — Next.js, Django, Spring Boot, Rails...

The output is what a senior engineer would write after spending a week with your codebase:

## Gates (run in order, stop on failure)
### Lint
- npm run lint
### Test
- npm run test
### Build
- npm run build
- npm run typecheck

## Architecture
- Type: monolith
- Entry: bin/app.js

## Testing
- Framework: vitest
- Naming: *.test.ts

## Code Style
- Indent: 2 spaces
- Formatter: prettier
- Linter: eslint

## Anti-Patterns
Do not:
- Use `any` in TypeScript — use `unknown`
- Use `getServerSideProps` with App Router — use Server Components

Under 1 second. Zero config.

Then It Watches Your Back

$ crag audit

  Compiled configs
  ✗ .cursor/rules/governance.mdc     stale — governance.md is newer
  ✗ AGENTS.md                        stale — governance.md is newer
  ✓ .github/workflows/gates.yml      in sync
  ✓ .husky/pre-commit                in sync

  Gate reality
  ✗ npx tsc --noEmit                 tsc not in devDependencies
  ✗ npm run lint                     "lint" script not in package.json

  2 stale · 2 drift
  Fix: crag compile --target all

Install the hook and it auto-fixes on every commit:

crag hook install              # auto-recompile when governance changes
crag hook install --drift-gate # also block commits if drift detected

The Benchmark

50 repos. 20 languages. 7 CI systems. Monorepos to single-crate Rust libraries.

Metric	Result
Repos tested	50
Crashes	0
Total gates inferred	1,809
Mean gates/repo	36.2
Repos with drift	23 (46%)
Time per repo	~1.2s

Some highlights:

Repo	Stack	Gates Found
grafana/grafana	Go + React + Docker	67
calcom/cal.com	Next.js + React + Docker	53
hashicorp/vault	Go + Docker + Node	50
biomejs/biome	Rust + React + TS	47
django/django	Python	38

Plus a 101-repo stress test: 4,400 invocations, 0 crashes.

Full benchmark results

How It's Different

The agent governance space is heating up. Microsoft just released their Agent Governance Toolkit. Coder has an AI Governance Add-On. Kong has a gateway approach.

crag takes a fundamentally different angle:

Compile-time, not runtime. Your rules are compiled to static files that each tool reads natively. No sidecar, no proxy, no MCP server required.
Deterministic. Same input → byte-identical output, SHA-verified across Linux, macOS, and Windows.
No LLM. The analyzer uses pattern matching, not inference. It finds what's actually in your repo, not what an LLM thinks should be there.
Zero dependencies. Node built-ins only. No supply chain risk.
Works offline. No network, no API keys, no cloud account required (cloud sync is optional).

Get Started

# One command — analyze + compile
npx @whitehatd/crag

# Step by step
npx @whitehatd/crag analyze           # generate governance.md
npx @whitehatd/crag compile --target all   # compile to 13 targets
npx @whitehatd/crag audit             # check for drift
npx @whitehatd/crag hook install      # enforce on every commit

Requirements: Node.js 18+ and git. That's it.

Links:

GitHub: WhitehatD/crag
npm: @whitehatd/crag
Website: crag.sh
VS Code: Marketplace
Neovim: crag.nvim
Docs: crag.sh/docs

I checked 13 top open-source repos. 9 have zero AI agent config.

Alexandru Cioc — Tue, 07 Apr 2026 23:49:47 +0000

Django. Angular. Vue. Svelte. Tokio. Remix. Cal.com. Airflow. Tauri.

None of them have a CLAUDE.md. No .cursorrules. No AGENTS.md. No copilot-instructions.md. Nothing.

These are projects with hundreds of contributors. If they don't have AI agent config, your project almost certainly doesn't either.

The problem is worse than "no config"

The 4 projects that DO have AI configs?

Grafana has a CLAUDE.md. It's literally one line: @AGENTS.md. Their hand-written AGENTS.md has 157 lines, but it misses quality gates from their CI.

Prisma has a 166-line AGENTS.md that says:

"Your training data contains a lot of outdated information that doesn't apply to Prisma 7. Always analyze this codebase like you would analyze a project you are not familiar with."

If Prisma's own maintainers don't trust AI training data, why do you?

Supabase has three separate AI configs — one for Claude, one for Copilot, one for Cursor. Three tools, three configs, zero overlap.

What this means for your code

When you use Cursor, Claude, Copilot, or any AI coding agent, it needs to know:

What quality gates CI enforces (lint, test, build, typecheck)
Your architecture and key directories
Anti-patterns to avoid
Code style conventions

Without this, your AI is working off stale training data. It writes code that breaks in CI.

One command

I built crag to solve this.

npx @whitehatd/crag

It reads your project — CI workflows, package manifests, configs, directory structure — and generates a single governance.md that compiles to every AI tool's native format.

One file in, twelve files out:

Target	File	Consumer
agents-md	`AGENTS.md`	Codex, Aider, Gemini CLI
cursor	`.cursor/rules/`	Cursor
copilot	`copilot-instructions.md`	GitHub Copilot
claude	`CLAUDE.md`	Claude Code
gemini	`GEMINI.md`	Gemini
cline	`.clinerules`	Cline
continue	`.continuerules`	Continue
windsurf	`.windsurf/rules/`	Windsurf
zed	`.rules`	Zed
amazonq	`.amazonq/rules/`	Amazon Q
github	`gates.yml`	GitHub Actions
husky	`.husky/pre-commit`	husky

Change a rule in governance.md, run crag compile, all 12 update.

The benchmark

We tested on 50 of the most important open-source projects:

1,809 gates inferred across 50 repos
96.4% accuracy — 187/194 gates verified against codebase
20 languages, 7 CI systems, 0 crashes

Repo	Stack	Gates	Finding
grafana/grafana	Go + React + Docker	67	CLAUDE.md: 1 line
supabase/supabase	TS + React + Docker	43	3 configs, fragmented
prisma/prisma	TypeScript + Rust	40	"data outdated"
django/django	Python	38	No config
angular/angular	TypeScript	38	No config

How it works

Analyze. Reads CI workflows (GitHub Actions, GitLab, Jenkins, etc.), package manifests, tool configs. 25+ language detectors, 11 CI extractors.
Generate. Writes governance.md with quality gates, architecture, testing profile, code style, anti-patterns, framework conventions.
Compile. Converts to each tool's native format — MDC frontmatter for Cursor, numbered steps for AGENTS.md, YAML triggers for Windsurf.
Audit. Detects stale configs, missing tools, drift.
Hook. Pre-commit auto-recompile. Optional drift gate blocks commits.

No LLM. No network. No API key. 500ms. Deterministic.

Try it

npx @whitehatd/crag

Node.js 18+. Zero dependencies. MIT.

GitHub: WhitehatD/crag

I stopped copy-pasting my lint rules into 12 different config files

Alexandru Cioc — Mon, 06 Apr 2026 00:29:44 +0000

Every project I work on has the same problem: my lint/test/build rules exist in my CI workflow, my pre-commit hook, my .cursorrules, my AGENTS.md, my GEMINI.md, and 7 more files. When I change a rule in one place, the others drift.

I built crag to fix this.

What it does

You write one ~20-line governance.md. crag compiles it to 12 downstream files atomically:

.github/workflows/gates.yml (GitHub Actions)
.husky/pre-commit
.pre-commit-config.yaml
AGENTS.md (Codex, Aider, Factory)
.cursor/rules/governance.mdc
GEMINI.md
.github/copilot-instructions.md
.clinerules, .continuerules, .windsurfrules
.zed/rules.md
.sourcegraph/cody-instructions.md

Change one line, regenerate everything.

Try it in 3 seconds

npx @whitehatd/crag demo

No install. No config. No network. No LLM. ~500ms to a verified
12-target pipeline with a determinism SHA printed inline.

What backs it up

512 tests passing across Ubuntu + macOS + Windows × Node 18/20/22
Stress-tested on 101 OSS repos (4,400 invocations, 0 crashes)
Reference benchmark: 40/40 Grade A on ship-ready governance
Deterministic: same input → byte-identical output, SHA-verified on every CI push across 9 runners
Zero runtime dependencies

GitHub: https://github.com/WhitehatD/crag
npm: https://www.npmjs.com/package/@whitehatd/crag

MIT licensed. If you use more than one AI coding tool alongside CI,
this is for you.

Tags: devtools, opensource, javascript, ai