Structure Your Project So the AI Can Navigate It

AI models reason about your code by reading it. A messy, sprawling, inconsistent project is as hard for them as it is for you. You don't need a perfect architecture, but a few habits pay off immediately:

• Keep a predictable layout. Source in one place, tests beside or mirroring the source, config at the root.
• Use clear, descriptive names. calculateMonthlyInvoiceTotal beats calc2. The AI uses names as clues.
• Favor smaller files. A 200-line file is easier to change correctly than a 2,000-line one, for both of you.
• Co-locate related things. When a feature's code, styles, and tests sit together, the AI gathers context in one read.
• Keep a clear entry point. A single obvious place where the app starts gives the AI a thread to pull on when it's mapping the project.

A typical, AI-friendly layout might look like this:

my-app/
├── AGENTS.md            # project rules & context for the AI
├── README.md            # what the project is, how to run it
├── .env.example         # documents needed secrets (no real values)
├── .gitignore           # excludes .env, build output, node_modules
├── package.json         # scripts: dev, test, lint, build
├── src/
│   ├── features/
│   │   └── invoices/    # code + tests for one feature, together
│   ├── lib/             # shared helpers
│   └── index.ts         # entry point
└── tests/               # cross-cutting / integration tests

The payoff compounds: the easier your project is for the AI to navigate, the smaller and more surgical its changes become. A well-organized repo lets the AI touch three relevant files instead of guessing across thirty — which means smaller diffs, fewer accidents, and reviews you can actually read. If you ever find the AI making sweeping, unfocused edits, the structure is often the real culprit, not the prompt.