The project context file

write it once instead of explaining it every day

What it is

A context file is a text file at the root of the project that the AI reads at the start of work. It holds what otherwise has to be explained in every new conversation: the stack and the versions, the project structure, the conventions, the commands to run.

The file closes reason 2 from article 3.1 — "it cannot see" — once and for all. The sign that you need one: you are typing the same thing about your project into a chat for the second time.

Its name varies by tool: CLAUDE.md, AGENTS.md, rules in .cursor/rules/. The idea is the same, and the contents move between them with almost no edits.

What it looks like in code

# Weather subscription bot

## Stack
Python 3.12, aiogram 3.x, SQLite via aiosqlite.
Dependencies in requirements.txt, virtual environment in .venv.

## Structure
bot.py          entry point, starts polling
handlers/       command handlers, one file per topic
storage.py      database work, all queries live here
db.py           connection, get_conn()
config.py       reading environment variables

## Conventions
- All database access goes through functions in storage.py.
  No SQL in the handlers.
- Handlers are async; heavy operations must not block the loop.
- User-facing texts live in locales/en.py, not in the code.
- Logging via logging, not print.

## Running it
python -m venv .venv && .venv/bin/pip install -r requirements.txt
python bot.py              run
pytest -q                  tests

## What not to do
- Don't add dependencies without need.
- Don't touch migrations/, they are applied in order.
- Tokens come from environment variables only; they are not in the code.

That is the whole file, not an excerpt. It is short — and that is its value.

What to tell the AI

Five sections, and that is enough

The "Stack" section with versions is the most important: it closes reason 3 from article 3.1, the one that cannot be cured by adding detail to a prompt.

The "Conventions" section comes second for return on effort. It is what makes the AI write in the project's style rather than its own.

The main rule: keep it short

The file is read at the start of every conversation and takes up room in the context. A long file crowds out code the AI could have read, and attention spreads thin.

A guide: one or two pages. If it doesn't fit, something went in that the AI could find out for itself by reading the project.

How to keep it current

The easiest way is to update it with the same AI that works in the project:

Read CLAUDE.md and compare it with what is in the project now.
What in the file is out of date? Just a list of mismatches,
no edits.

A good moment for that check is when you have added a module, changed a library version, or changed how the project is started.

What to look for

The file exists and the AI doesn't read it. In a chat you have to paste it yourself; it will not get there on its own. Terminal agents usually read it, but not all of them and not always — check by asking: "what do you know about the structure of this project?"

The file describes the wish, not the reality. "All database access goes through storage.py" — while in fact three handlers have SQL right in the code. The AI will treat what is written as true.

The file has grown to ten pages. Documentation, a history of decisions and a list of every endpoint have moved in. Move those to separate files and leave links in the context file.

Cheat sheet