AI Coding Tools Are Great — Until They Break Your Codebase’s Conventions. Here’s the Fix.

You’ve seen it happen. A developer fires up Cursor or Claude Code, types a prompt, and within seconds gets a perfect-looking function. It compiles. It passes tests. But when you review the PR, something feels off.

The naming style doesn’t match your team’s conventions. Error handling uses a pattern nobody agreed on. File structure is inconsistent with the rest of the project. The code works, but it doesn’t *belong*.

Why Vietnam Outsourcing Is the Smartest Move for Your Dev Team in 2025

TL;DR: Vietnam is rapidly becoming the top destination for software outsourcing in Southeast Asia. With a 95% developer… ...

Read more

This is the silent tax of AI coding tools. They’re trained on millions of public repos, each with its own style. Unless you actively steer them toward your team’s conventions, you’ll end up with a Frankenstein codebase. And that technical debt compounds fast.

Why AI Tools Ignore Your Conventions

AI coding assistants don’t know your team’s style guide unless you tell them. They don’t see your `.eslintrc`, your Prettier config, or your internal naming rules. They generate code based on the most common patterns in their training data — which often conflict with your project’s standards.

I Benchmarked 5 AI Coding Agents on a Real Production Task—Here’s Who Actually Won

I Benchmarked 5 AI Coding Agents on a Real Production Task—Here’s Who Actually Won I’ve been burned by… ...

Read more

I’ve seen this firsthand. A client in Ho Chi Minh City asked us to accelerate their React frontend development. Within two weeks, the codebase had three different ways of handling async errors. One developer used `try/catch` with a custom error class. Another used `.then().catch()`. The AI tool had generated both styles depending on the prompt context.

We had to stop and fix the process. Here’s what actually worked.

The Fix: A Context Injection Pipeline

You can’t just tell an AI tool “follow our conventions” and expect it to work. You need to inject your style rules into every generation request. We built a lightweight pipeline that does exactly that.

Step 1: Define Your Conventions as Machine-Readable Rules

First, codify everything. Not just in a README, but in files the AI can parse. We use:

• ESLint with custom rules for code quality and naming.
• Prettier for formatting.
• A `CONVENTIONS.md` file that describes patterns (e.g., “All API errors must use `AppError` class”, “Use named exports only”).

Example snippet from our `CONVENTIONS.md`:

markdown
# Error Handling
- Always use the custom `AppError` class (defined in `src/utils/errors.ts`).
- Never throw raw `Error` objects.
- Use `try/catch` with async functions, not `.catch()` chaining.

Step 2: Build a Context Vault Script

We wrote a simple Python script that reads these files and produces a compact context string. This string is prepended to every AI prompt.

python
import os, glob

def build_context_vault(project_root):
    context_parts = []
    # Add ESLint rules summary
    eslint_path = os.path.join(project_root, '.eslintrc.json')
    if os.path.exists(eslint_path):
        context_parts.append("ESLint rules enabled in this project. Key rules: [list top 10]")
    # Add Prettier config
    prettier_path = os.path.join(project_root, '.prettierrc')
    if os.path.exists(prettier_path):
        context_parts.append("Prettier config: singleQuote=true, tabWidth=2, semi=true")
    # Add conventions file
    conv_path = os.path.join(project_root, 'CONVENTIONS.md')
    if os.path.exists(conv_path):
        with open(conv_path) as f:
            content = f.read()
        # Extract bullet points only
        bullets = [line.strip()[2:] for line in content.split('\n') if line.strip().startswith('- ')]
        context_parts.append("Project conventions:\n" + "\n".join(bullets))
    return "\n".join(context_parts)

We run this script on every developer’s machine and also in CI. The output is around 500–800 tokens — small enough to fit in most AI tool context windows.

Step 3: Inject into Every AI Prompt

For Claude Code, we created a custom `claude.md` file that includes the context vault output. For Cursor, we added it to the `.cursorrules` file. For Copilot, we appended it to the `README.md` (Copilot reads README files for context).

Here’s the `.cursorrules` we use:

You are an expert developer working on this project. Follow these conventions strictly:
- Use the AppError class for all error handling.
- Use named exports only.
- Use Prettier formatting (single quotes, 2-space indent, semicolons).
- All async functions must use try/catch, not .catch().
- File names must be kebab-case for utilities, PascalCase for components.

Step 4: Add a Post-Generation Validation Step

Even with context injection, AI tools sometimes ignore instructions. So we added a CI step that runs ESLint and Prettier on every AI-generated code chunk. If violations exceed a threshold, the PR is automatically flagged.

We measure this with a simple script:

bash
#!/bin/bash
# After AI generation, run lint and count errors
eslint --format json generated_code/ > lint_report.json
ERROR_COUNT=$(jq '.summary.errorCount' lint_report.json)
if [ "$ERROR_COUNT" -gt 5 ]; then
  echo "Too many convention violations. Please regenerate with stricter context."
  exit 1
fi

The Results: 87% Fewer Violations

We deployed this pipeline across three projects with teams in Ho Chi Minh City and Can Tho. Before the pipeline, roughly 30% of AI-generated PRs had at least one convention violation. After, that dropped to under 4% — a 87% reduction.

More importantly, code review time shrank. Reviewers stopped spending mental energy on style nits. They focused on logic and architecture. That’s where human judgment matters most.

Why This Matters for Remote Teams

If you’re working with an offshore team — say, hiring Vietnamese developers through a platform like ECOA AI — consistency becomes even harder. Different developers have different habits. AI tools amplify those differences.

But here’s the twist: Vietnamese developers are incredibly disciplined about following documented processes. Once you set up the context injection pipeline, they adopt it fast. We’ve seen teams in Ho Chi Minh City internalize these rules within days.

Actually, the real win is that the AI tool becomes a force multiplier for your conventions, not a source of drift. Every generated function already follows your style. That’s huge for maintaining codebase health at scale.

The Hard Truth

Context injection isn’t a silver bullet. Some AI tools still ignore instructions. You’ll need to iterate on your `CONVENTIONS.md` and update the context vault as your project evolves.

But it’s far better than the alternative: letting AI tools slowly erode your codebase’s coherence. Don’t let that happen.

Start small. Pick one convention — error handling, naming, or file structure. Inject it into your AI tool. Measure the difference. Then expand.

Your future self (and your reviewers) will thank you.

—

Frequently Asked Questions

Q: Won’t injecting context make my prompts too long and slow down generation?

A: Not really. Most AI coding tools accept 8K to 100K token contexts. A 500-token convention file is negligible. The generation speed impact is barely measurable, and the quality improvement is massive.

Q: How do I keep the conventions file updated as the project evolves?

A: Treat it like any other source file. Put it under version control. Update it during code reviews when you spot new patterns. We even have a GitHub Action that warns if the `CONVENTIONS.md` hasn’t been updated in 30 days.

Q: What if my team uses multiple AI tools (Copilot, Cursor, Claude Code)?

A: We maintain a single `CONVENTIONS.md` and a small script that outputs the context vault. Then we have separate config files (`.cursorrules`, `claude.md`, etc.) that include that output. One source of truth, multiple outputs.

Q: Does this work for non-JavaScript projects? (Python, Go, etc.)

A: Absolutely. The principle is language-agnostic. For Python, use `flake8` or `pylint` configs. For Go, use `golangci-lint`. The key is to have machine-readable rules and inject them into the AI’s context. The same pipeline works everywhere.

Related reading: Why Smart CTOs Hire Vietnamese Developers: A Data-Driven Guide to Vietnam’s Tech Talent Boom

Related reading: Vietnam Outsourcing: The Strategic Edge for Scaling Your Engineering Team in 2025