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

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:

1. 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.




2. Compiles to 13 targets — each in the tool's native format, with correct frontmatter and activation patterns.

Here's what one command generates:

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.

Some highlights:

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