ai-rules: a rule compiler that feeds AI coding agents before the merge gate

The problem ai-rules targets: agents that write correct code in the wrong place

The README frames the problem as architectural decay in AI-driven development. An agent asked to add a feature will often call a data layer straight from a UI component, bypass a service boundary, ignore project-specific directories, leak secrets into logs, or return an audit report in a shape that a downstream repair flow cannot parse. Each of those outcomes is locally reasonable and globally wrong.

The project's own positioning makes the boundary explicit: repository governance tools protect the merge boundary, while ai-rules guides the AI while it is still writing and repairing code. That is a meaningful distinction. A linter or a CI gate reacts after the code exists. ai-rules tries to supply the agent with an operating contract before it writes anything.

The intended user is a team that already has engineering standards written down somewhere and wants those standards to reach the agent's context window in a structured form rather than as a pasted paragraph. The README names Cursor, Windsurf, Copilot, Codex and Claude Code as the kind of prompt-driven setups it is meant to serve.

How the rule compiler works: Rule IR, evidence IDs and merged extends chains

The pipeline starts with project-authored rules in `.ai-rules/.ai-rules.md` and `rules-config.json`. The CLI parses both, merges `extends` chains for rules and config, then resolves high-level AST configuration from three sources in order: template defaults, detected project configuration, and local ai-rules overrides. The output is a normalized Rule IR.

From that compiled model the CLI produces several artifacts. It collects lightweight local evidence for `regex` and `import/include` style rules, for minimal `count` rules such as `function-lines` and `params-count`, and AST-backed evidence for what the README calls a first supported slice of frontend JS/TS/Vue rules. Evidence is linked with stable evidence IDs. Validator artifacts are written alongside audit context, and the audit, validation and fix flows all consume the same compiled rule model.

Two config-level mechanisms shape what survives into a prompt. `thresholds` control active parameterized rule behavior, so a line-count or parameter-count rule fires at a value you set. `exceptions` suppress known-safe files per rule pattern. Path aliases in `config.json` handle non-standard repository layouts, which the README presents as an alternative to editing every rule when your directories do not match the template's assumptions.

The design intent is stated plainly: move from rules as text toward rules as compiled execution context, so a future agent runtime can reason over rule metadata, validator decisions, evidence references and repair guidance. The repair side is where the compiled model pays off. Fix prompts are generated from both the normalized report and local rule metadata, which is a different input than a static prompt pack could offer.

Getting it running: init, inspect-logic and the report file

The README gives the initialisation step as generating reusable rule templates for different stacks, with output landing in `.ai-rules/`. The two artifact paths it names explicitly are `.ai-rules/.ai-rules.md` and `rules-config.json`, with `config.json` carrying path aliases. The one command shown in the supplied material is `ai-law inspect-logic`, which generates a separate business-logic inspection flow and writes `.ai-rules/cache/logic-audit-context.json` and `.ai-rules/cache/ai-logic-report.template.json`.

The report schema is `ai-rule-report.json`, which the CLI normalizes and validates. That validation step matters more than it looks. If the agent returns a report in an unexpected shape, the fix prompt built from it will be unreliable, and the README lists exactly that failure among the reasons the project exists.

What the material does not give is a package installation line, a version number, or a list of supported Node versions. There are no retrieved releases. Treat the install path as unverified until you read the repository's package manifest yourself. The commands above are the ones the documentation states, and `ai-law inspect-logic` is the only one quoted verbatim.

Logic risk inspection is a prompt generator, not a detector

The inspect-logic mode targets problems that resist reduction to framework misuse: missing authorization or ownership checks, unsafe state transitions, idempotency or replay gaps, tenant-isolation mistakes, and trust-boundary problems between input validation, permissions and persistence. For native `c-cpp` projects the same command shifts its review model toward resource ownership and lifetime transitions, unchecked critical return values and error propagation, inconsistent lock or atomic protocols, parser length, offset and state validation gaps, privileged file, process or socket trust-boundary failures, and partial cleanup and rollback inconsistencies.

The README is direct about the limit: the CLI does not claim deterministic local detection for all of these. Instead it compiles the current rule context, validator output, candidate evidence and high-risk context files into a focused prompt for AI-assisted logic review. That is an honest description and it should shape your expectations. You are not buying a static analyser for authorization bugs. You are buying a better-constructed question to ask a model that is already in your workflow.

The consequence is that inspect-logic inherits whatever the underlying model gets wrong. A missed ownership check in a codebase with unusual permission conventions will still be missed if the compiled context does not surface the relevant files. The value is in the context assembly, not in a decision procedure.

Built-in coverage is broad on frontend and Python, thin elsewhere

The template set is uneven, and the README is fairly clear about that. Frontend coverage is the deepest. UI code must not call network or data layers directly. Raw HTML injection through `innerHTML` or `dangerouslySetInnerHTML` is flagged, with AST-backed evidence for supported files. Dynamic execution via `eval()` or `Function()` is flagged, also with AST-backed evidence. Hardcoded frontend secrets and API keys are flagged. Third-party HTML script tags without SRI are flagged. React hooks must follow call rules, React lists should not use array index as `key`, and effect-driven remote requests should use stable dependency control. On the Vue side, `computed` must stay pure, props must not be mutated directly, loop index as `:key` is flagged, and direct DOM access is discouraged. Electron and VS Code extension templates extend the frontend foundation for desktop and extension-host scenarios.

Python base and FastAPI get a different list: bare `except` and broad swallowed exceptions, mutable default arguments, weak password hashing such as MD5 or SHA1, logging patterns that may leak sensitive values, external HTTP calls without explicit timeouts, bounded wait or timeout policies for filesystem, database, cache, subprocess and model-serving I/O, subprocess and shell invocation that preserves argument boundaries, and function line-count and parameter-count thresholds.

Everything else is thin or absent from the supplied material. If your stack is Go, Rust, Java or a Python framework other than FastAPI, the built-in templates will not carry you, and the work of authoring rules falls on your team. The AST-backed evidence is also described as a first supported slice, which means some rules that exist as text may not yet produce evidence.

Where ai-rules is the wrong tool

If you want a guarantee that a class of defect cannot reach main, ai-rules is not that. It shapes what an agent produces. It does not enforce anything at the merge boundary, and the README says so in its own comparison with repository governance tools. A determined agent, or a developer working outside the agent, can still commit a boundary violation.

The second case is a repository with no written standards. The whole model depends on rules existing as Markdown that the CLI can parse and compile. If your conventions live in reviewers' heads, you will spend the first week writing `.ai-rules.md` before the tool does anything useful.

The third case is a stack outside the template set. With no built-in coverage for your language, you are authoring rules and possibly evidence patterns from scratch, and the return on that effort depends on how much of your review load is repetitive architectural feedback.

There is also a cost the README does not quantify: every rule you add to the compiled context consumes prompt budget. A large rule set with many enabled rules and low severity thresholds will produce a long audit prompt, and the material gives no guidance on trimming it beyond `exceptions` and `thresholds`.

Compared with ESLint and Semgrep: compiled context versus deterministic rules

ESLint and Semgrep are the obvious alternatives, and the difference is not quality. Both are deterministic. A rule either matches or it does not, and the result is reproducible on any machine. ai-rules compiles rules into context for a model to reason over, which means the outcome varies with the model, the prompt and the files selected as high-risk context.

What that buys you is reach. ESLint can flag a React list using an array index as `key` because that is a syntactic pattern. It cannot flag a missing ownership check, because that requires understanding what the endpoint is supposed to authorize. ai-rules routes that second class of question to a model with the relevant rule context attached. The README's own list of logic risks (authorization, idempotency, tenant isolation, trust boundaries) is a list of things deterministic linters generally do not attempt.

The cost is the loss of a pass or fail signal you can gate CI on. A practical split is to keep ESLint or Semgrep for the syntactic rules you can enforce mechanically and use ai-rules for the architectural and logic-review layer that sits before review. The README's framing supports this: governance tools protect the merge boundary, ai-rules guides the agent while it writes.

Maintenance, licence and what to verify before adopting

The repository metadata carries no licence identifier. That is not a detail you can defer. Without a declared licence, the terms under which you may use, modify or redistribute the code are unclear, and the README does not address it. Check the repository's licence file or ask the maintainer before you build anything on top of it. This is a description of the metadata, not legal advice.

Maintenance cost has two parts. The first is rule authoring and upkeep: as your architecture changes, `.ai-rules.md`, `rules-config.json` and path aliases in `config.json` need to change with it. The second is template drift. The README describes the project as evolving toward a rules compiler, and it lists several capabilities as first slices or first batches. If you depend on a specific rule producing AST-backed evidence, confirm it does so for your file types rather than assuming parity with the text rules.

The last push recorded for the repository is 2026-06-02 and there are no retrieved releases, so there is no versioned artifact to pin against. Before adopting, run the init step against a copy of your repository, inspect the generated `.ai-rules/` tree, and check whether the emitted `rules-config.json` resolves your directory structure or needs path aliases in `config.json`. If your layout is non-standard, that check is the one that decides whether the tool works on your codebase at all.

Editorial conclusion

Adopt ai-rules if your AI coding agent keeps producing code that passes review in isolation but crosses your layering or UI boundaries, and you already keep engineering standards in Markdown. Skip it if you need deterministic detection of every rule it lists: the README states the CLI does not claim deterministic local detection for all logic risks, and it compiles a focused prompt instead. Before committing, confirm the licence, since the repository metadata carries no identifier, and run ai-law init against a copy of your repository to check whether .ai-rules/rules-config.json path aliases cover your directory layout.

Official sources

1. fjb040911/ai-rules on GitHub
2. Issues
3. README