Agentic development lives or dies on how legible your repository is. An agent that can't find the seams of your codebase will thrash: reading whole files, guessing at conventions, and quietly reintroducing bugs you already fixed. Most of the work of "being good at AI development" is really the work of making a project easy to reason about — for the agent and for you.
Start with a map
The single highest-leverage file is the one that tells the agent how the project is organised. Where do routes live? Where do shared utilities go? What's generated and must never be hand-edited? Write it down once, explicitly.
Keep files single-purpose
One file, one job. When a file does three things, an agent editing the first thing has to load the context for all three — and it will happily "improve" the other two.
- Split large modules along their natural seams.
- Name files after what they contain, not how they're used.
- Co-locate tests with the code they exercise.
Encode the guardrails
Conventions that live only in your head are invisible to an agent. Put them in the repo:
# Never do
- Commit secrets or .env files
- Use `as any` type casting
- Modify generated files directly
An agent treats these as hard constraints. A human treats them as good advice. Both of you benefit.
The payoff
A well-scaffolded project turns the agent from an eager intern into a competent collaborator. You stop babysitting edits and start reviewing outcomes.