Every engineering team has two sets of rules. The first set lives in config files: your ESLint rules, your Prettier settings, your import order preferences, etc. These are explicit and reliably enforced on every commit. The second set lives in your team’s collective memory: which directory new API routes belong in, whether you use factory functions or classes for services, how state management flows through your application. These rules are just as important as the first set, but they’re dramatically harder to enforce.

This gap is where most code quality problems actually live, and it’s exactly what AI-powered convention enforcement is built to close.

What linters catch vs. what teams care about

Linters and formatters are indispensable. They’ve eliminated entire categories of debate and have made code review faster and less contentious across the industry. But think about the last time you left a substantive comment on a pull request. It probably wasn’t about a missing semicolon, right? It was more likely something like:

  • “We put data-fetching logic in /services, not in the route handler directly.”
  • “This should use the createService factory pattern, not a class. Check how userService is structured.”
  • “This component is reaching into the billing domain directly. We go through the billing API facade for that.”

These are architectural and organizational conventions. They’re what hold your codebase together at scale. And no linter rule can capture them because they’re specific to your team and your history of decisions.

New engineers violate these conventions constantly not because they’re careless, but because the conventions are invisible. AI coding agents have the same problem. They’ll generate code that runs, passes type checks, and even looks clean, but it doesn’t fit the way your team builds software. These inconsistencies can stack review time at best and cause major tech debt or app stability and security risks at worse.

Why documentation doesn’t solve this

The natural response to this is to write it all down, which works for about six weeks (if you’re lucky). Convention documentation has three fundamental problems. First, it gets stale fast. Your architecture evolves continuously, so the style guide from six months ago describes a codebase that no longer exists in important ways. Nobody owns the maintenance of these documents, so they drift silently out of date.

Second, nobody reads a 40-page style guide before opening their first pull request. Engineers learn by reading existing code and by getting feedback in review. A static document can’t compete with that feedback loop.

Third, conventions aren’t always conscious decisions. Many of the patterns your team follows emerged organically over time. Nobody decided “we use factory functions for services” in a meeting, it just became the pattern, reinforced through hundreds of code reviews. These emergent conventions are the hardest to document because nobody thinks to write them down.

How AI-powered convention enforcement works

The insight behind AI convention enforcement is simple: your git history already contains a complete record of your team’s actual conventions. Every commit is a data point about how your team builds software. Scrubby analyzes this history to discover conventions that actually exist.

This analysis covers several dimensions:

Naming patterns: How does your team name files, functions, variables, and types in each part of the codebase? Are there consistent prefixes, suffixes, or casing conventions that vary by domain?

File organization: Where do new files of each type go? What’s the expected directory structure for a new feature? When someone adds a route, what other files typically get created alongside it?

Architectural boundaries: Which modules import from which other modules? Where are the domain boundaries, and how do teams communicate across them? What facade patterns does your team use to keep coupling under control?

Co-change patterns: Which files change together? If you modify a database model, do you always update a migration, a serializer, and a test? These co-change relationships reveal implicit contracts that are easy to miss.

Once these conventions are extracted, Scrubby enforces them at review time. When a developer or an AI agent opens a pull request, Scrubby checks the changeset against the discovered conventions and flags violations with clear explanations. Not just “this is wrong” but “this file is in the wrong directory because your team consistently places API route handlers in /routes, not /controllers, based on the last 200 commits.”

The codebase intelligence approach

Scrubby takes this idea and makes it practical. Instead of requiring teams to manually define rules, Scrubby mines your git history and current codebase to build a model of your team’s actual conventions. It extracts co-change patterns to understand which files are logically connected and maps architectural boundaries so it can flag when a change crosses a domain boundary without updating the expected touchpoints.

This intelligence gets delivered through two channels. The first is an MCP server that connects directly to AI editors like Claude Code, Cursor, and VS Code. When an AI agent is about to edit a file, it can query Scrubby for the file’s domain context, related conventions, and expected co-changes. The AI gets the same institutional knowledge that a senior engineer on your team would have, so the code it produces has the same quality and organizational standards.

The second channel is a GitHub App that reviews pull requests directly. It checks changesets for missing co-changes, convention violations, and domain boundary crossings, and then leaves comments explaining what it found and why.

Best practices for adopting AI convention enforcement

If you’re considering AI-powered convention enforcement, here’s how to start effectively.

Begin with discovery, not enforcement. Before you enforce anything, understand what conventions your team actually follows. You’ll likely be surprised. Patterns you thought were universal might only apply to certain domains, and patterns you never consciously adopted might be remarkably consistent. Scrubby’s analysis makes this kind of discovery fast and painless.

Start with architectural boundaries. The highest-value conventions to enforce are architectural ones, like domain boundaries, file organization, and module dependencies. Why? Because these are the conventions that cause the most damage when violated, as they compound over time into tangled, hard-to-maintain code. Scrubby prevents this kind of compounding tech debt by stopping the violations before they occur.

Let the tool learn from feedback. The best convention enforcement systems adapt. When a reviewer dismisses a finding, that’s a signal that the convention may have changed, or that it was never a real convention in the first place. Scrubby incorporates this feedback into it’s knowledge graph of your system so that agent context and reviews get more accurate over time.

Moving beyond syntax

The tools we use to maintain code quality haven’t kept pace with how teams actually define quality. Formatting and syntax checking were solved years ago. The next frontier is convention enforcement: ensuring that code doesn’t just work and look clean, but that it follows the patterns and respects the boundaries your team has built over time. Scrubby is how you get there — by turning your git history into an enforceable set of conventions that stay current because they’re derived from your actual code, not from a document someone wrote and forgot about.