Structure decides what every change costs. In a well-organised codebase you can find where something lives, change it in one place and test it on its own. In a tangled one, every fix touches five files and breaks a sixth. AI coding agents struggle with tangled code too, for the same reasons people do.
Last reviewed by the Forge team
Each one: why it hurts, and how to spot it in your own project.
Each top-level area should have one job you can name in a few words. When responsibilities are spread around, nobody knows where a change belongs.
How to spot it: Look at your top-level folders. Can you say what each one owns? Does auth, billing or email live in one place, or in five?
When components query the database and route handlers hold business rules, you can't test or reuse the rules, and changing the database means editing the UI.
How to spot it: Look for database queries in components or pages, and for business rules (prices, permissions, limits) inside route handlers.
// app/orders/page.tsx
const rows = await db.query("select * from orders where user_id = $1", [userId]);
const total = rows.reduce((s, r) => s + r.price * 1.2, 0); // VAT, again// app/orders/page.tsx
const { orders, total } = await listOrders(userId);
// lib/orders.ts owns the rules; lib/db owns the queriesWhen A imports B and B imports A, neither can change on its own. A 'utils' file everything imports turns every edit into a risk for the whole app.
How to spot it: Use a dependency graph tool (madge, dependency-cruiser) or your bundler's warnings to find cycles, then look at the files with the most importers.
The same rule, type or query in several places means every change has to be made several times, and one copy is always forgotten.
How to spot it: Search for repeated function names, constants, regular expressions, SQL and fetch calls across folders.
A file that does five jobs is hard to read, review and test, and AI tools edit it less reliably because they see only part of it.
How to spot it: List your largest files and longest functions in the areas you change most. Split them along clear seams, one job each, not just by line count.
If errors, config and data fetching are handled three different ways, every reader has to relearn the codebase in each folder.
How to spot it: Pick three files from different areas and compare how they handle errors, fetch data and read config.
Unused files, exports nobody imports, commented-out blocks and stale feature flags look like real code. People (and agents) keep them working for nothing.
How to spot it: Use a tool such as knip or ts-prune to find unused exports and files, then delete them. Git keeps the history.
Unused packages, two libraries doing the same job, and packages declared in the wrong place make builds slower and upgrades riskier.
How to spot it: Check that each package in your manifest is imported, and that you don't have two date, HTTP or validation libraries.
The modules everything depends on are the ones whose breakage hurts most. If they have no tests, every refactor is a gamble.
How to spot it: Find the modules with the most importers and check that each has tests in a predictable place.
const total = items.reduce((s, i) => s + i.price * 1.2, 0);same VAT rule in lib/invoice.ts:18 and app/api/quote/route.ts:9, already drifting