Repo naming conventions for cleaner AI-assisted coding

Why messy names confuse assistants

An assistant reads a repo like a stranger walking into a workshop. It sees names, paths, and nearby files before it understands how the system works.

When folder names mix several ideas, intent disappears. A repo with /api, /helpers, /new, /misc, and /v2 does not tell the model where product logic ends and support code starts. People can fill those gaps from memory. Models cannot.

The same problem shows up when similar modules do different jobs. If auth, auth-service, session, and security all contain login checks, token code, and user state, the assistant has to guess which file should change. It will often edit the closest match instead of the right one.

Startup repos collect temporary names all the time. Folders like temp, old-api, helpers2, or final stick around for months. A model does not know those names were accidents of speed. It treats them like part of the design and keeps building on top of them.

Tests can make the confusion worse. If code lives in /billing/invoice but its tests sit in /specs/unit/payments or a separate /qa folder, the link between behavior and proof gets weak. The model may miss coverage that already exists, write duplicate tests, or skip a case that failed before.

Once naming gets weak, the assistant falls back to shallow pattern matching. It leans on import names, nearby files, and file size because the structure does not carry enough meaning. That is how you end up with a patch in utils instead of billing, or yet another module next to five half-overlapping ones.

The damage usually looks small, but it adds up fast. You ask for "add retry logic to invoice sync," and the model finds sync.ts, syncJob.ts, and worker_sync.ts in three places. One path gets updated. Two related paths stay untouched.

Clear names cut that guesswork. They show where work belongs, where tests live, and which module owns a behavior. You spend less time correcting the assistant and less time explaining the repo map in every prompt.

What clear naming looks like

Clear naming is a little boring. That is the point. When a person or an assistant opens the repo, they should guess the right place on the first pass.

Start with one pattern for the same kind of folder. If feature code lives in modules/, keep it there everywhere. Do not mix modules/, features/, packages/, and stuff/ for similar code unless they truly mean different things.

Names should describe the job, not the history behind it. billing, auth, and notifications tell you what the code does. Names like team-alpha, new-service, or oleg-old-fix only make sense to people who remember the backstory, and that memory fades quickly.

Consistency matters with singular and plural forms too. Pick test or tests. Pick module or modules. Then use that choice across the whole tree. A small mismatch looks harmless, but it makes search, code generation, and review less clear than they should be.

A simple pattern often looks like this:

• top-level folders by runtime: api/, web/, worker/
• shared code in one place: shared/ or common/
• modules named by job: payments/, users/, reports/
• tests named the same way everywhere: tests/ or __tests__/

Vague names cause most of the mess. misc, temp, other, new, and final invite random code to pile up. Six months later, nobody knows what belongs there, so people keep adding more. If a folder has a real purpose, give it a real name. If it has no clear purpose, it probably should not exist.

Assistants work much better with a plain layout like api/modules/billing, web/components, and tests/integration. They struggle when the same type of code hides under three different labels.

Choose one home for each kind of work

A repo gets noisy fast when the same kind of file lives in three places. AI coding tools read that noise as a pattern. If scripts sit next to product code, or examples hide inside feature folders, the model starts guessing. Naming works better when each kind of work has one clear home.

Keep the main app code in a single top-level area, usually src/ or app/. Pick one and stick with it. When every feature starts there, both people and assistants know where new code belongs.

Put scripts in their own folder. Database imports, release helpers, local setup files, and cleanup jobs should not live beside business logic. They change for different reasons, and they often use shortcuts you would never want in the app itself.

Shared code needs one obvious place too. If helpers appear in utils/, common/, lib/, and shared/, those names stop meaning much. Choose one folder for code that several parts of the app use, then move duplicates into it over time.

Docs and examples deserve their own space. A root README is fine, but longer notes belong in docs/. Demo projects, sample payloads, and starter files fit better in examples/. That keeps the product tree focused on code that ships.

For many repos, a layout this simple is enough:

• src/ for app code
• scripts/ for maintenance and local tasks
• shared/ for reused helpers and modules
• docs/ for notes and setup guides
• examples/ for demos and sample files

This matters even more when you work with an assistant. If you ask it to add a new module and the repo has three possible homes, it will pick one and hope. Sometimes it gets lucky. Often it adds one more layer of clutter.

Rename the repo in small steps

Big repo renames usually fail when a team tries to fix every name in one weekend. People miss imports, tests break, and nobody remembers why half the folders moved. Small batches work better.

Start by listing the names that make people pause. If someone has to ask whether misc, helpers2, new, or temp-scripts is still in use, that name is already costing time. The same goes for folders that look interchangeable to an assistant.

Write the naming rules on one page before you touch the tree. Good rules are plain and repeatable. Pick one way to name modules, one word for shared code, and one pattern for tests.

A short rule set is enough:

• use one naming style for folders and modules
• keep shared code under one agreed name
• avoid vague labels like misc, stuff, old, or new
• name test locations so they point to the code they cover

Then rename one area at a time. Do the API folder this week, the worker jobs next week, and the test directories after that. A narrow change is easier to review, easier to roll back, and much easier for people to trust.

After each rename, fix the boring parts right away. Update imports, path aliases, build scripts, test commands, and CI jobs in the same pull request. Run the app, run the tests, and make sure your editor and search tools still find the moved files.

This matters because models infer intent from names. If one package is called billing, another is payments-core, and a third is money, the assistant will guess. Sometimes it guesses wrong in a way that still looks plausible.

Then hold the line. Ask the team to use the new names in every pull request, and push back when old patterns creep back in. A simple review comment is usually enough: use the agreed folder name and move the file.

That discipline pays off quickly. Within a few weeks, the repo feels calmer, search results make more sense, and both humans and assistants spend less time deciding where work belongs.

Place tests where the intent stays obvious

Tests should answer one question fast: what does this file prove? When test files sit in random places, people and assistants both start guessing. That guesswork creates duplicate coverage, missed cases, and edits in the wrong folder.

Pick one rule for unit tests and keep it everywhere. You can store unit tests next to the module they check, or keep them in one clear area such as tests/unit. Both choices work. Trouble starts when one package uses specs, another uses __tests__, and a third hides tests in the repo root.

A simple layout usually works best:

• unit tests live beside code or under tests/unit
• integration tests live under tests/integration
• every package uses the same file pattern, such as test_auth.py or auth.test.ts
• fixtures and mocks live in support folders with plain names like expired_card_fixture.json or payment_gateway_mock.ts

Slow tests need their own home. If a test talks to a database, queue, filesystem, or external API, treat it as integration. Keep it away from fast unit tests so developers can run quick checks often and save the slower suite for larger changes.

The names inside test folders matter just as much as the folder names. data.json tells you nothing. user_with_no_subscription_fixture.json tells you what case it supports before you open it. The same goes for mocks. stripe_mock.ts is clear. helper2.ts is not.

A small startup repo makes this easy to see. Put pure order total checks in orders/test_totals.py, place checkout flow tests in tests/integration/orders/test_checkout.py, and keep shared helpers in tests/support/fake_payment_gateway.py. An assistant can add a new test without stopping to guess where it belongs.

When folders, filenames, fixtures, and mocks all follow one pattern, the repo feels calmer. You spend less time explaining intent, and the assistant makes fewer wrong moves.

A small cleanup on a startup repo

One early startup repo had three backend folders: api, backend2, and old-service. All three still had live code. When someone needed to change billing or login, they opened two or three folders before they found the real entry point. An assistant reads that mess the same way a new hire does: it guesses.

The frontend had the same problem. Some screens lived in ui, others in frontend-app, and shared parts sat in a third folder with a vague name. One name should mean one thing, every time.

A small cleanup fixed most of it:

before:
api/
backend2/
old-service/
ui/
frontend-app/
tests/
src/__tests__/

after:
services/app/
web/app/
packages/shared/
packages/shared/tests/

Now the service code has one home. Old backend folders either move into services/app or get deleted after a short transition. The web client also has one home, so nobody asks whether a new page belongs in ui or frontend-app.

Test layout matters just as much. Some teams keep tests next to each package. Others keep one tests/ tree that mirrors production code. Both can work. Trouble starts when one repo uses both styles with no rule.

After the rename, the assistant stops proposing a new backend-v3 folder or dropping tests into random top-level paths. It opens the right files sooner, suggests imports from the right package, and writes smaller diffs. Review gets easier almost immediately.

This kind of cleanup is common in AI-augmented startup work. Small naming fixes often help more than another prompt tweak, because the assistant has fewer places to misread. Clean module names do not make a repo fancy. They make it easier to trust.

Mistakes that keep the repo hard to read

Most repo mess comes from avoiding a small cleanup today. A team renames services to apps, then keeps services_old, legacy-services, and a few import aliases so nothing breaks right away. People stop trusting the folder names. An assistant will trust them anyway and start suggesting edits in the wrong place.

Special cases cause the same problem. One team gets its own naming rule, one product gets a custom folder, and one urgent feature lands in a temporary module that never goes away. After that, nobody can tell which rule is the real rule.

Mixing build output with source code is another common mistake. If generated files, packaged assets, coverage reports, and app code sit side by side, every search gets noisy. Humans lose time. AI tools lose context. Keep source in one place, and keep output somewhere the team can ignore.

Dead modules do quieter damage. A folder that still compiles but no longer owns real behavior keeps attracting edits because its name looks legitimate. If the team no longer uses it, delete it. If you need a short transition, mark it clearly and remove it soon.

Another common mistake is leaving duplicate names in place after a partial refactor. If payments, billing, and invoice-core all hold parts of the same workflow, the structure still asks people to guess. The assistant will do the same.

Quick checks before you ask for code

An assistant reads your repo the same way a new teammate does. It looks at folder names, test locations, and file patterns to guess where a change belongs. If those signals are messy, it will guess wrong.

Good naming does not need to be clever. It needs to be obvious. A person should find the main app folder in about 10 seconds, and the model should reach the same answer.

Use this quick pass before you ask for code:

• find the main app folder fast
• check whether module names match the code inside them
• pick one test pattern and keep it
• separate scripts, generated files, and docs from product code
• explain the structure in five short sentences

That last check works well because it is hard to fake. If you can say, "The web app is in apps/web. Shared code is in packages. Tests sit next to features. Build scripts live in scripts. Generated clients go to generated", the repo is probably clear enough for an assistant to behave well.

Small fixes matter. Renaming helpers to email, moving random shell files into scripts, or putting scattered tests into one predictable pattern can save a lot of prompt back-and-forth.

What to clean up next

If you want better results from AI coding tools, do not start with a giant repo rewrite. Start with the places where the assistant makes the most wrong guesses. In most teams, that means vague folders like misc, helpers, and temp, duplicate module names, and tests split across several patterns.

Those spots create drag every day. A model sees three possible homes for the same change and picks one that looks plausible. You then spend time moving files, fixing imports, and explaining the same rule again.

A short cleanup plan works better than a big refactor:

• merge catch-all folders into clearer homes
• rename modules that mean different things but share the same name
• move stray tests so each feature follows one test pattern
• remove old folders left over from earlier rewrites

Freeze the naming rules before you touch larger parts of the repo. If you rename half the project and keep debating folder names, the mess just comes back with newer paths. A one-page rule set is enough if it answers simple questions: where feature code lives, what shared modules are called, and where tests go.

Then make those rules part of code review. Reviewers should push back when someone adds another utils2 folder, drops integration tests into a unit test area, or creates a new naming pattern for one urgent task. Small exceptions spread fast.

This is often the unglamorous work that makes AI assistance useful. If you need outside help, Oleg at oleg.is works with startups and smaller teams on AI-first engineering setups, including repo structure, module boundaries, test placement, and the rules that keep assistants from guessing.

The next cleanup target is simple: find the folder that causes the most hesitation, rename it, and lock the rule in review.