ai-aware-code-structure

AI-aware code structure

How to organise code across files when an AI coding agent is one of the readers. This is not "AI changes everything" — good, well-abstracted code reads well for humans and machines alike. But at the margins (how aggressively to split, how much to co-locate, how self-contained each file must be), AI shifts the trade-offs, and this skill is about getting those margins right.

When this applies

Reach for this whenever the question is where code lives, not what it does: splitting a growing file, drawing a module boundary, deciding whether to peel logic out of a component, or reviewing an existing layout. It assumes an LLM will read or edit the result — which today is almost always true.

The core shift: a third reader

Code organisation has always balanced two readers: human readability (can someone understand this?) and maintainability (can it change safely?). AI adds a third: machine readability — can an agent operating in a limited context window understand and safely edit this?

For the most part these align. Clear structure with good abstractions serves all three. The interesting decisions are the ones where they pull apart.

The limitation to design around

AI tools are remarkably reluctant to look at other files. They work with what's in front of them, and getting them to proactively explore adjacent files is like pulling teeth. A human navigates a four-file component intuitively — glances at the sibling, holds the model across files without thinking. An agent doesn't. It works with the open file and makes confident changes that break because it never checked how a prop was shaped two files over.

This produces a genuine tension, and both halves are real:

• Focused files help. Everything in context costs tokens and attention quality. A 60-line presentational component is a far better prompt than a 300-line file that does everything. High signal-to-noise → better output.
• Split files hurt. When a component is spread across four files and the agent is in one of them, it often lacks context it needs — props shaped elsewhere, types defined elsewhere, theme variables elsewhere. A beautifully focused file with insufficient context is worse than a slightly busier file that's self-sufficient.

The resolution isn't "split less" or "split more." It's to split along boundaries that survive the agent's reluctance to look around.

The decision test

Don't ask "is this a separate concern?" Ask:

Can this concern be understood in isolation?

That single question resolves most cases:

• A purely presentational unit — props in, output out, no side effects — is a great candidate for its own file. The agent can work on it with almost no external context; the file is self-documenting.
• A "smart" unit that orchestrates state, effects, and data fetching is tightly coupled by nature. Separating its logic from its rendering doesn't help if understanding either half requires the other — you've just created two files that are each meaningless alone, and doubled the cross-file lookups the agent won't perform.

So separation is still good — but the boundary has to be one where each side stands on its own.

Heuristics

Co-locate tightly coupled code. If two pieces are always changed together and each needs the other for context, keep them in one file. This is the single highest-value move: it removes the cross-file lookup that an agent is most likely to skip, so it works from a complete picture instead of a partial one.

Raise the file-size threshold. The old rule — "if it doesn't fit on a screen, split it" — was calibrated for human scrolling. Agents handle larger files well, roughly up to a few hundred lines before quality degrades. A cohesive 150-line file that keeps logic and rendering together beats two 75-line files that are meaningless apart. There's still a ceiling: past ~300 lines signal-to-noise drops and you should split — but split for that reason, not out of reflex.

Prefer abstractions over file structure. A well-named custom hook (or function, or module) beats splitting files, because it's a real abstraction: it has an interface, it hides its implementation, and the consuming code is understandable without reading the internals. The agent reads useCheckout() at the call site and knows enough to proceed. Splitting a file only relocates code; an abstraction actually reduces the context needed to work with it. When tempted to split for readability, ask whether the right move is an abstraction instead.

When you do split, make each side self-contained. The test for a good split is whether each resulting file can be understood and edited without opening the others. If a file references props, types, or values that only make sense by reading a sibling, the boundary is in the wrong place — either move it or merge back.

Quick reference

Situation	Lean toward
Pure presentation (props → output, no side effects)	Separate — self-documenting, low external context
Logic + rendering that need each other to make sense	Co-locate — splitting just doubles unperformed lookups
File growing but still one coherent concern, < ~300 lines	Keep together — cohesion beats line count
File past ~300 lines or covering several concerns	Split — signal-to-noise is now the problem
Tempted to split a file purely for readability	Extract an abstraction (hook/function/module) instead
A proposed split leaves files that only make sense together	Don't split — the boundary is wrong

Applying this skill

• Deciding whether to split a file: run the "understood in isolation?" test on each proposed piece. If a piece can't stand alone, co-locate it. Recommend an abstraction before recommending a split.
• Reviewing organisation: look for splits that force cross-file context — the most common smell is a "dumb" render file whose props are shaped by a sibling the agent won't open. Flag files split below the human-era size reflex with no isolation benefit.
• Structuring something new: start coarser than the old instinct suggests. Let files grow to a few hundred lines while they stay coherent, and reach for an abstraction (not a new file) when one part earns a real interface.

This is a current trade-off, not a permanent law. The reluctance to read adjacent files is a limitation of today's tools, not a fundamental one — as agents get better at navigating codebases, the threshold will drift back toward aggressive separation. Structure for the tools you have.