Teach Your Coding Agent Your Team’s Naming Rules

A coding agent can produce valid code that still looks foreign to your repository. It might call a database lookup fetchCustomer when your team reserves fetch for network requests, or introduce CustomerManager beside a dozen narrowly named services. The fix is not a longer prompt every morning. Give the agent a small, testable naming contract that lives with your code.

Follow this walkthrough in one repository. You will finish with written rules, a calibration task, and a repeatable review loop.

1. Collect examples from code your team trusts

Open three recently reviewed files in the same area: a service, its tests, and a caller. Avoid starting with the oldest utility folder; legacy code often contains conventions nobody wants to repeat.

Write down eight to twelve representative names. In a TypeScript billing service, these might include findInvoiceById, listOverdueInvoices, isInvoicePaid, InvoiceRepository, and invoice.repository.ts. Record what each name communicates, not just its capitalization.

If two examples disagree, ask a maintainer which pattern new code should follow. An agent cannot reliably distinguish an intentional exception from an abandoned convention.

2. Turn preferences into decision rules

Replace vague guidance such as “use descriptive names” with rules that help the agent choose between alternatives. For the billing example, write:

• Use camelCase for functions and variables, and PascalCase for types and classes.
• Start boolean predicates with is, has, or can: isInvoicePaid, not invoicePaid.
• Use find for a lookup that may return no result, and get for a lookup that throws when the record is missing.
• Use fetch for outbound network operations, not local database reads.
• Use the domain word invoice; do not introduce bill as a synonym.

Include return behavior alongside names. A function called getInvoiceById should not silently return undefined if your rule promises a missing-record error.

3. Put the contract where your agent reads instructions

Create a short naming section in the repository instruction file your coding tool supports. For Codex, that may be AGENTS.md; for Claude Code, use CLAUDE.md. Check your tool’s documentation for instruction discovery and directory scope rather than assuming every agent reads the same file.

Keep one canonical naming document if you use multiple tools, then reference it from their supported instruction files. Tell the agent to read that document before editing. Include two correct examples and one discouraged alternative per important rule.

Add an explicit boundary: apply these rules to new or changed internal code, but preserve public API fields, database columns, and third-party names unless the task authorizes a migration.

4. Run a naming-only calibration task

Before requesting a feature, ask the agent: “Read the repository naming instructions and inspect the billing service. Propose names for a nullable invoice lookup, a required invoice lookup, and an overdue-invoice predicate. Explain each choice. Do not edit files.”

Expect findInvoiceById, getInvoiceById, and isInvoiceOverdue under the sample rules. If the answers differ, inspect whether the instructions are ambiguous or were not loaded. Correct the contract before generating implementation code.

5. Try one small implementation

Ask for a bounded change: “Add a function that lists overdue invoices for one customer. Follow the naming instructions, inspect neighboring tests, and avoid unrelated renames. Before editing, state the proposed function name and file path.”

Review the proposal first. Then let the agent implement it and run the relevant tests. This separates naming decisions from implementation complexity and makes mistakes cheaper to correct.

6. Automate the mechanical checks

Use your existing linter to enforce capitalization and other supported identifier patterns. Add filename checks only if your tooling supports them. Keep domain vocabulary and distinctions such as find versus get in review guidance unless you have a reliable custom check.

Ask the agent for a final naming audit listing introduced identifiers, the rules they follow, and any exceptions. Treat that audit as a review aid, not proof of compliance.

7. Save corrections and repeat across sessions

When review catches a recurring mistake, update the shared contract with a concrete example. Start a fresh agent session and rerun the calibration task to check that success does not depend on conversation history.

If your team uses different coding tools, I recommend RelayVano as a pay-as-you-go relay that works with Claude Code, Codex, Gemini CLI, and OpenAI-compatible SDKs. Sign up for RelayVano to try this workflow with your preferred compatible tool, while keeping naming instructions versioned in your repository.