Anatomy of a project

where things live and what you can leave closed

What it is

A project is dozens of files, but not all of them need reading. Most are either housekeeping or generated by tools. This article teaches you to tell one from the other, and to find where execution begins.

You need the skill every time you open someone else's project — or your own, forgotten one — and every time you have to tell the AI which file to work in.

What it looks like in code

weather-bot/
├── .git/                 history, don't touch by hand
├── .venv/                installed libraries
├── .env                  secrets: tokens, passwords
├── .gitignore            what never goes into git
├── requirements.txt      list of dependencies
├── README.md             where to start
├── bot.py                entry point
├── config.py             reading settings
├── db.py                 database connection
├── storage.py            database queries
├── handlers/             command handlers
│   ├── __init__.py
│   ├── start.py
│   └── weather.py
├── migrations/           database structure changes
└── tests/                tests

What to read and what not to

The rule is simple: if a file was created by a tool rather than a person, you don't need to read it. A .venv folder may hold hundreds of thousands of lines; not one of them is yours.

How to find the entry point

Three ways, fastest first:

1. By name. main.py, bot.py, app.py, manage.py, index.js, main.dart — nine times out of ten that's it.
2. By README. It usually gives the run command, and the command names the file.
3. By search. if __name__ == "__main__" for Python, "scripts" in package.json for JavaScript.

Names that mean something

Some folder names are stable and turn up across many projects:

utils/ is a special case: it is where everything that found no home gets dumped. If it has grown large, that is a sign the structure needs revisiting.

What to tell the AI

Show the project file tree without .venv, .git and __pycache__.
For each top-level folder, one line saying what is in it.

When you need to know where to begin:

I am opening this project for the first time. Name three files
I should read to understand how it is built, in order.

And the most practical one — before stating a task:

I need to add a /stats command. Which files would have to
change? Don't write anything yet.

The answer to the last one doubles as a check on whether the AI understood the project structure correctly.

What to look for

A .env file in git. Checked in one line: is .env in .gitignore? If not, the tokens are already in the repository history.

Logic in the entry point. If bot.py is five hundred lines, there is no separation, and the project will be hard to change. That is bad for the AI too: it cannot work on one part without disturbing the rest.

Two folders for one job. utils/ and helpers/, or services/ and core/, in the same project is a sign code was filed away without looking. Ask the AI how they differ: if it cannot explain, they should be merged.

An empty tests/. The folder exists, the tests do not. Which means nobody will know what a change broke (article 3.9).

Cheat sheet