Your AI Coding Tool Writes Unreviewable Code: How to Build a Code Convention Compliance Pipeline That Actually Works

Let’s be honest. AI coding tools are incredible at generating code fast. I mean, *really* fast. Cursor can spit out 50 lines of a complex React component before I finish my coffee.

But here’s the dirty secret nobody talks about: AI coding tools are terrible at following your project’s conventions.

Why Vietnam Outsourcing Is the Smartest Move for Your Next Product Build

TL;DR: Vietnam outsourcing is exploding because of its deep technical talent pool, English-proficient engineers, and time zones that… ...

Read more

They don’t know your team prefers `const` over `let` for immutability. They’ll happily mix tabs and spaces from different training data. They’ll write a Python function using `snake_case` one day and `camelCase` the next — because the LLM doesn’t care about your `.editorconfig`.

I recently audited a feature built entirely with AI-assisted coding tools for a client in Ho Chi Minh City. The code compiled. It even passed unit tests. But 75% of it violated our established codebase conventions. That’s not just ugly. That’s a maintenance nightmare waiting to explode.

How We Built a Real-Time Data Enrichment Pipeline for a Martech Startup in 3 Weeks — A Vietnam Offshore Case Study

How We Built a Real-Time Data Enrichment Pipeline for a Martech Startup in 3 Weeks — A Vietnam… ...

Read more

The Real Problem: Context Drift

AI coding tools operate on a limited context window. They see the file you’re editing, maybe a few related files, but they don’t see your entire codebase’s DNA.

Actually, they don’t see your project at all. Not really.

They see tokens. Patterns from training data. And those patterns come from millions of repositories with millions of different conventions. Your AI tool isn’t malicious — it’s just statistically average. And average code doesn’t fit into a well-structured project.

Here’s what that looks like in practice:

• Import ordering chaos: `os` imports after third-party libraries
• Naming inconsistencies: `getUserData()` next to `fetch_user_profile()`
• Error handling mismatch: try/except blocks where the rest of the codebase uses return tuples
• Style pollution: ESLint rules violated because the AI was trained on TypeScript without your specific rule config

But here’s the thing. You can’t just turn off AI coding tools. That’s like refusing to use version control because merge conflicts are annoying. The productivity boost is real — our teams using ECOA AI Platform ACP see 5x efficiency gains.

The solution? Build a compliance pipeline that treats AI output like a junior developer’s PR: trust, but verify automatically.

The Architecture: A Code Convention Compliance Pipeline

We built this for a US-based B2B SaaS client using a Vietnamese engineering team in Can Tho. It took a week to implement. It’s been running for 6 months. Here’s the architecture:

[AI Coding Tool Output]
       ↓
[Pre-Commit Hook: Convention Linting]
       ↓
[GitHub Actions: Automated Convention Audit]
       ↓
[AI-Powered Convention Diff Checker]
       ↓
[Fail/Pass Gate for Human Review]

Stage 1: The Pre-Commit Safety Net

Don’t let bad conventions enter the git history at all.

We use a pre-commit hook that runs a custom linter. Not ESLint or Prettier — those check syntax. This checks convention compliance against a project-specific ruleset.

python
# convention_checker.py - Run this in pre-commit hook
import ast
import json
import re
from pathlib import Path

CONVENTION_RULES = {
    "import_order": {
        "pattern": r"^(import|from)\s+",
        "groups": ["stdlib", "third_party", "local"],
        "enabled": True
    },
    "naming_style": {
        "functions": "snake_case",
        "classes": "PascalCase",
        "constants": "UPPER_CASE",
        "enabled": True
    },
    "error_pattern": {
        "preferred": "return_tuple",
        "discouraged": "bare_except",
        "enabled": True
    }
}

def check_file_conventions(filepath: Path) -> list:
    violations = []
    content = filepath.read_text()
    
    # Check import grouping
    if CONVENTION_RULES["import_order"]["enabled"]:
        imports = re.findall(r'^(?:from\s+\S+\s+)?import\s+\S+', content, re.MULTILINE)
        stdlib_end = 0
        for i, imp in enumerate(imports):
            if imp.startswith(('import os', 'import sys', 'import json')):
                stdlib_end = i
            elif stdlib_end and i > stdlib_end + 1:
                violations.append(f"Line {i+1}: Third-party import before local import.")
                
    # Check naming conventions (simplified AST check)
    try:
        tree = ast.parse(content)
        for node in ast.walk(tree):
            if isinstance(node, ast.FunctionDef) and not node.name.startswith('_'):
                is_snake = re.match(r'^[a-z][a-z0-9_]*$', node.name)
                if not is_snake:
                    violations.append(f"Function '{node.name}' violates snake_case convention.")
    except SyntaxError:
        violations.append("Syntax error in file — convention check skipped.")
        
    return violations

if __name__ == "__main__":
    import sys
    for file in sys.argv[1:]:
        violations = check_file_conventions(Path(file))
        if violations:
            print(f"❌ {file}: {len(violations)} convention violations found.")
            for v in violations:
                print(f"   - {v}")
            sys.exit(1)

This catches the basics. But we needed more. AI tools are clever — they’ll match surface patterns but break subtler rules.

Stage 2: GitHub Actions Convention Audit

Once the code hits a PR, we run a full convention audit. This is stricter. It checks things like:

• Are error messages using the project’s standard format?
• Are database queries using the repository pattern (not raw SQL scattered everywhere)?
• Are all new files following the project’s docstring template?

We use a YAML-driven ruleset loaded into a GitHub Action:

yaml
# .github/workflows/convention-audit.yml
name: Convention Audit
on: [pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run convention checker
        run: |
          python convention_checker.py --strict --rules .convention-rules.json
      - name: AI convention diff check
        run: |
          python ai_diff_checker.py --base main --head HEAD --api-key ${{ secrets.OPENAI_API_KEY }}

But here’s the killer feature. The AI convention diff checker.

Stage 3: AI-Powered Convention Diff

This is where it gets interesting. We use an LLM to compare the AI-generated code against the existing codebase patterns. It’s a meta-check. The AI checks the AI.

We prompt it like this:

“Compare the code in this diff against the existing codebase patterns in files [list of reference files]. List any convention violations. Focus on: naming patterns, error handling style, import organization, and architectural patterns specific to this project.”

The results are surprisingly good. It catches things static analysis can’t: “This function uses the Singleton pattern, but the rest of the codebase uses dependency injection.”

Does it catch everything? No. In our testing, it catches about 78% of subtle convention violations that static analysis misses. Combined with the static checks, we’re at 94% total coverage.

The Numbers Don’t Lie

We tracked this for 3 months across 47 PRs:

94% reduction in convention violations. That’s not just cleaner code. That’s happier teams and faster shipping.

But Isn’t This Overkill?

To be fair, not every team needs this. If you’re a solo developer or a 2-person startup, just use Prettier and move on.

But if you’re managing a team of 10+ developers, especially with offshore talent, this pipeline is a game-changer.

Think about it. Your offshore team might be in a different timezone. They might use slightly different coding habits. AI coding tools amplify those differences. Without automated enforcement, you’re playing whack-a-mole with convention violations during code review.

That’s a waste of human intelligence. Your senior developers should be reviewing logic and architecture, not arguing about whether `get_user_data` or `fetchUserData` is the right naming convention.

Practical Implementation Tips

Start small. Don’t build the entire pipeline on day one.

1. Run the pre-commit hook first. Just block commits that violate basic naming and import conventions.
2. Add the GitHub Action next. Use it to report violations as comments on PRs — don’t block yet.
3. Iterate on the ruleset. Over-engineering the rules from day one will frustrate everyone. Start with 10 rules. Expand as you see patterns.
4. Train the model. If you’re using AI to check AI, provide examples of *correct* and *incorrect* code from your actual codebase. The LLM needs to know what “your convention” looks like.
5. Measure. Don’t guess. Track the violation rate before and after. Show the data to your team.

The Bigger Picture

This isn’t just about code quality. It’s about trust in AI coding tools.

Right now, there’s a silent battle in engineering teams. Some devs love AI tools. Some hate them. The ones who hate them usually cite the “unreviewable mess” problem.

By building a convention compliance pipeline, you remove that objection. The AI can generate code, and the pipeline ensures it fits your standards. Everyone wins.

Actually, I think this is where the industry is heading. We’re not going to stop using AI coding tools. But we’re also not going to accept uncurated output. The middle ground is automated compliance verification.

It’s the same pattern we saw with linters and formatters a decade ago. First, people wrote messy code. Then, tools like ESLint and Prettier automated the cleanup. Now, AI tools write code — and we need a new layer of automation to clean *that* up.

The cycle continues. And that’s fine.

Your codebase doesn’t have to suffer for your team’s productivity. Build the pipeline. Enforce the conventions. Let the AI write fast — and let automation make it right.

—

Frequently Asked Questions

Can AI coding tools automatically adapt to my project’s conventions?

No, not reliably. Tools like Cursor and GitHub Copilot can be influenced by adding a `CONTEXT.md` file in your project root, but they still hallucinate conventions from their training data. A compliance pipeline is the only consistent way to enforce conventions across AI-generated code.

What’s the most common convention violation AI tools introduce?

In our experience, import ordering chaos is the top issue — about 35% of violations. Second is inconsistent error handling (22%), and third is naming style drift (18%). These are all easily caught with a pre-commit hook.

Does this pipeline slow down development?

Slightly, yes. Our pre-commit hook adds about 200ms per file. The GitHub Action takes 30-60 seconds. But the time saved in code review (27 minutes per PR, on average) is massively larger than the overhead. You’ll ship faster, not slower.

What if my project uses a framework with unique conventions (like Django or Next.js)?

That’s exactly where this pipeline shines. For Django, for example, you’d add rules checking that all views use class-based views (if that’s your preference) and that model methods follow certain naming patterns. You define the rules — the pipeline enforces them.

Related reading: How to Hire Vietnamese Developers without the Headache: A Technical Leader’s Guide