The shape of a project
Files, directories, dependencies, and configuration — how to orient yourself in any codebase.
- Recognise the common parts of a real project layout
- Explain what dependencies and a lockfile are
- Use conventions to find your way around an unfamiliar repository
A single file is a program; a real project is dozens or thousands of files arranged by convention. Those conventions are a map. Once you can read the map, you can drop into almost any codebase and find your bearings — a skill that compounds enormously, especially when reviewing what an AI agent has built.
The parts you'll always see
Project layouts vary, but the roles are consistent:
- Source code — the program itself, usually under
src/orapp/. - Configuration — files that tune how things build and run
(
package.json,tsconfig.json,.env). Often named with dots or sitting at the root. - Dependencies — third-party code your project uses, downloaded into a folder
like
node_modules/(and not committed to version control). - Build artifacts / output — generated files (
dist/,build/,.next/). Also not committed; they're produced from your source. - Tests — alongside the code or under
tests/. - Docs —
README.mdfirst; it's the front door of any project.
Entry points: where it begins
Every runnable program has an entry point — the file or function execution
starts from. Finding it is the fastest way to understand a project: it's the
top of the thread you can pull to see everything else unspool. Look for an obvious
main, index, or a "scripts" section in the config that names what runs.
Dependencies and the lockfile
Modern projects stand on a tower of other people's code. Two files manage this:
- A manifest (e.g.
package.json) lists what you depend on, in rough version ranges. - A lockfile (e.g.
package-lock.json) records the exact version of every dependency actually installed — so your machine, a teammate's, and the server all build the identical thing.
When you see "it works on my machine but not in CI," a version mismatch — a lockfile not respected — is a prime suspect.
Orienting in an unknown repo
A reliable first pass through a project you've never seen:
- Read the README — what is this, how do you run it?
- Open the config/manifest — what kind of project, what are the scripts?
- Find the entry point and skim outward from there.
- Glance at the directory names — they usually announce what lives where.
Conventions exist precisely so you can guess correctly. If a folder is called
utils, you can bet what's inside before you open it. Lean on that — and when
you create projects, follow conventions so the next person (or agent) can guess
too.
Where to go next
You can now find your way around. The natural companion skill — keeping a history of how a project changes over time — is version control, next.