Yeda AI Tips · #063

Record the Local Dialect So AI Code Blends In

AI code that looks AI-generated? You skipped the conventions step. When you onboard a repo you map the stack and trace one real request — but the thing that makes new code blend in is the local dialect: the naming, patterns, and house rules that your codebase follows and no generic model default ever will.

Why the dialect matters more than the map

A coding agent that knows your stack still writes in its style: its favorite error-handling shape, its default naming, its idea of a log line. Every one of those defaults that differs from your repo is a diff comment waiting to happen. PEP 8 puts it plainly: "Consistency within a project is more important" than consistency with any external guide — and consistency within one module matters most of all. Your reviewers feel that instinctively; that's why AI code "smells" AI-generated even when it works.

The fix is 15 minutes of recording, once per repo.

The 3-item dialect checklist

Record these three things in a file the agent reads every session:

#	What to record	Where to find it	Example entry
1	Naming	Scan 3–5 core modules	"snake_case functions, PascalCase classes, `_private` helpers"
2	Patterns	One real request path, end to end	"Errors: raise `AppError` subclasses, never return error codes; log with `structlog`, one event per line"
3	House rules	CONTRIBUTING, lint config, .editorconfig	"Max line 100 (overrides Black's 88); no barrel imports; tests mirror `src/` layout"

Item 3 is the one most people skip. House rules are exactly the places where your repo deviates from language defaults — GitHub surfaces a CONTRIBUTING file (root, docs/, or .github/) to every contributor for this reason, and your ESLint config's rules block or your .editorconfig is the machine-readable half of the same contract. Those overrides are invisible to a model that only saw language-default training data, so write them down explicitly.

Where to put the recording

Put the checklist where your agent loads it automatically. In Claude Code that's CLAUDE.md at the project root — it's read at the start of every session and is documented as the place for "coding standards, workflows, project architecture." Other agents read AGENTS.md or equivalent; the principle is identical: conventions belong in persistent context, not in a prompt you retype.

Concrete beats vague. "Use 2-space indentation" works; "format code properly" doesn't. Write each convention so a reviewer could verify it mechanically.
Record the deviations, not the defaults. "We use snake_case in Python" wastes tokens — the model already assumes that. "We use 100-char lines, not 88" earns its place.

Power-user moves

Trace one real request and quote it. Don't describe your error-handling style — paste a 10-line excerpt of a real handler into the conventions file as the canonical example. Models imitate examples more reliably than they follow descriptions.
Scope conventions to paths. Claude Code supports path-scoped rules in .claude/rules/ with a paths: frontmatter glob, so your frontend naming rules only load when the agent touches src/**/*.tsx. Big monorepos with two dialects need this.
Point at the lint config instead of copying it. A line like "lint rules live in eslint.config.js; run the linter before proposing code" stays true when the config changes. Copy out only the 2–3 rules that most often surprise newcomers.
Update on review friction. Every time a human reviewer flags AI-generated code for style, that's a missing checklist entry. Add it the same day — the docs' own heuristic is "Claude makes the same mistake a second time."
Steal structure from published style guides. Google's style guides show what a complete conventions document covers per language; you need a fraction of that, but their section headings are a good scan list for what your repo might have opinions about.

Resources

Building an AI feature? Yeda AI designs, audits, and ships production LLM systems.

Talk to us · Read the blog