Naming Conventions That Help Agents

Overview

Structure determines where an agent looks. Naming determines what the agent understands when it gets there. A directory tree full of files named service.ts, helper.ts, and utils.ts is like a filing cabinet where every drawer is labeled "stuff." In this lesson, we examine how naming conventions at every level -- files, directories, functions, variables, and types -- either accelerate or block an agent's ability to comprehend your code without reading every line.

Why Names Are Agent Context

When an agent lists a directory, every file name becomes a piece of context. The agent uses these names to decide which files are relevant to its current task and which can be skipped. This decision happens before the agent reads a single line of code, making file names the cheapest form of documentation in your project.

Comparison of vague versus descriptive names: Vague names (service.ts, helper.ts, utils.ts, manager.ts) leave the agent asking 'which one handles billing?' Descriptive names (billing.service.ts, invoice-generator.ts, payment-processor.ts, billing.test.ts) let the agent immediately identify billing.service.ts as the entry point.

A descriptive name is a free token. A vague name costs tokens to investigate.

File Naming Rules

Rule 1: Names Should Reveal Purpose

Every file name should answer the question "what does this file do?" without opening it.

Rule 2: Use Consistent Suffixes

Role suffixes tell the agent what kind of code a file contains. When every service file ends in .service.ts, every controller in .controller.ts, and every test in .test.ts, the agent can filter files by role without reading them.

The agent learns this pattern from one module and applies it everywhere. When it needs the database layer for billing, it goes straight to billing.repository.ts without scanning every file.

Rule 3: Match Case Convention to Language Ecosystem

Use the casing convention your language community expects. Agents are trained on millions of repositories and have strong priors about what casing means:

When you break the convention (e.g., using PascalCase for a Python file), the agent may misinterpret the file's role or generate code that follows the wrong style.

Directory Naming Rules

Rule 4: Directory Names Should Be Plural Nouns or Domain Concepts

Directories group related files. Their names should communicate what category those files belong to.

Rule 5: Avoid Deeply Qualified Directory Names

Long directory names with multiple qualifiers often indicate that the directory is trying to communicate too much hierarchy. Flatten when possible.

Function and Variable Naming

Agents do not just navigate file trees -- they also read function signatures to understand what code does. Function and variable names serve as inline documentation that tells the agent what to call, what arguments to pass, and what to expect back.

Rule 6: Functions Should Describe Their Action and Subject

The well-named functions tell the agent three things without reading the body: what the function does (validate, send, calculate), what it operates on (payment method, verification email, monthly invoice), and what it returns (ValidationResult, bool, Invoice).

Rule 7: Booleans Should Read as Questions

Boolean variables and functions should use prefixes that make their true/false semantics explicit: is, has, can, should, was.

When an agent sees if (canUserAccessResource(currentUser, targetResource)), it understands the condition without reading the function body. When it sees if (validate(token)), it must investigate to understand what is being validated and what the return value means.

Rule 8: Avoid Abbreviations and Acronyms

Agents handle full words better than abbreviations. They have been trained on enough code to understand getUserById instantly, but getUsrById or getUBI introduces ambiguity.

The only acceptable abbreviations are universally understood ones: id, url, http, api, db, config. Everything else should be spelled out.

Naming Anti-Patterns

The Generic Trap

Certain names are so generic that they communicate nothing:

• utils.ts -- could contain anything
• helpers.py -- helps with what?
• common/ -- common to whom?
• misc.ts -- miscellaneous is the opposite of organized
• core.ts -- core of what functionality?
• base.ts -- base for what derived classes?

Every one of these forces the agent to open the file and read it to determine relevance. Replace them with specific names: string-formatters.ts, date-calculations.py, shared/http-errors/, validation-rules.ts.

The Numbering Trap

Numbered files like handler1.ts, handler2.ts give the agent no information about what distinguishes them. Use descriptive names instead: webhook-handler.ts, scheduled-job-handler.ts.

The Inconsistency Trap

Using userService.ts in one module and billing-service.ts in another and NotificationSvc.ts in a third forces the agent to treat each module as an independent puzzle. Pick one convention and enforce it everywhere.

Inconsistent versus consistent naming: Inconsistent files (userService.ts, billing-service.ts, NotificationSvc.ts, order_service.ts) leave the agent asking 'is there a pattern?' Consistent files (users.service.ts, billing.service.ts, notifications.service.ts, orders.service.ts) let the agent recognize the pattern: every service is named {feature}.service.ts.

A Naming Convention Template

Here is a complete naming convention you can adopt and document in your project's CLAUDE.md:

Document this in your CLAUDE.md so the agent reads it at the start of every session and follows it consistently.

Summary

Naming conventions are the most cost-effective form of agent context. Descriptive file names let agents filter by relevance without reading contents. Consistent suffixes let agents predict file roles across modules. Clear function names communicate intent, inputs, and outputs without requiring the agent to read implementations. Avoid generic names (utils, helpers, misc), abbreviations, and inconsistent patterns -- all of which force the agent to spend tokens on investigation instead of action. In the next lesson, we will explore how documentation, type annotations, and inline comments serve as additional navigation aids for agents.