How to describe the architecture to an AI

twenty lines that save you an evening

What it is

An AI has no memory of your project. In each new conversation it knows only what it can see right now — and if it can't see the structure, it invents its own. Hence answers like "create a helpers.py file" while a services/ folder is alive and well, and a fourth way of reading settings.

The cure is one short text — an architecture brief. Article 3.14 talked about the context file in general: what the project is, what the commands are, how to run it. This is about the part of it that answers "how is it put together", and that is worth writing separately, because it is the part an AI breaks most often.

What it looks like in code

The template

The brief consists of six blocks. No more are needed: a long text reads worse and goes out of date faster.

1. WHAT IT IS        — one sentence on what the program does
2. STACK             — language, framework, database, versions
3. STRUCTURE         — the folder tree, one line of explanation per folder
4. DEPENDENCIES      — who is allowed to import whom
5. WHERE THINGS LIVE — data, settings, secrets, logs
6. WHAT NOT TO DO    — decisions that are not up for discussion

The sixth block is the most underrated. Without it, in every third answer an AI proposes adding a library, switching databases, or "refactoring this while we're here".

A filled-in example

WHAT IT IS
A Telegram bot: subscribe to the weather in chosen cities,
a morning digest.

STACK
Python 3.12, aiogram 3, SQLite, requests.
Run with: python -m bot. One server, systemd.

STRUCTURE
bot/
├── handlers/   commands and buttons, only input parsing and the reply
├── services/   logic: weather, subscriptions, the digest
├── storage.py  all database access, no other DB calls anywhere
├── models.py   the City and Subscription dataclasses
└── config.py   settings via pydantic-settings

DEPENDENCIES
handlers -> services -> storage -> models
No reverse imports. models imports nothing from the project.

WHERE THINGS LIVE
Data: SQLite, the file data/bot.db
Settings: environment variables, see .env.example
Secrets: only in .env, never in the repository
Logs: stdout, picked up by systemd

WHAT NOT TO DO
- Don't add an ORM or other libraries without a separate conversation.
- Don't talk to the database from handlers directly.
- Don't change the table schema without a migration script.
- Don't add async where there isn't any.

A little over twenty lines. Pasted at the start of a request when the task is large, and sitting in ARCHITECTURE.md or the context file the rest of the time.

Why this works better than it looks

The brief removes exactly the uncertainty an AI would otherwise close with a guess. It doesn't guess where database access lives — it is written down. It doesn't choose between SQLite and PostgreSQL — written down. It doesn't invent a name for a new file — there is a scheme.

The side effect matters more than the main one: to write such a brief you first have to know it. If the "dependencies" block won't write itself because everything in the project imports everything, the brief has already paid for itself, just differently.

A check that takes a minute

The fastest way to find out whether the AI has understood the architecture:

Retell in your own words how my project is put together:
what depends on what and where things live. Five lines.
If anything is missing from the description for you to start
work, say exactly what.

The retelling shows up the discrepancies at once. The second part of the question is no less useful: what the AI is missing is usually the hole in the brief.

When to update the brief

Not when the code changes but when a decision changes. Added a library, switched storage, introduced a new layer, dropped a rule — the brief gets rewritten the same day.

The sign that the brief is out of date: the AI does it "wrong", but exactly as written.

What to tell the AI

Here is my project's tree and a few key files.
Assemble a draft architecture brief in six blocks:
what it is, stack, structure, dependencies, where things
live, what not to do.
Where you aren't sure, write "?" — don't invent.

The instruction about ? is mandatory: without it the gaps are filled with plausible fiction (article 1.6).

Here is the project's architecture brief: <text>.
The task: <what needs doing>.
First say which files you'll touch and whether that breaks
the dependency rules. Write the code after I say yes.

Here is the brief, and here is the code you just wrote.
Check your code against the brief: dependencies, file
locations, the ban on new libraries.
List the violations.

That last technique — the AI checking itself against your rules — works noticeably better than the same rules stated at the start of the conversation: the check runs against finished code rather than against an intention.

What to look for

A brief written by the AI and not read by you. It may describe a project other than yours.

No "what not to do" block in the brief. The most useful block, and the most often forgotten.

An out-of-date brief. The AI follows what is written, and what is written is no longer true.

A three-page brief. You can't paste that into a request or read it with your eyes; anything longer than a screen stops working.

No versions. "Python and a Telegram bot" is both aiogram 2 and aiogram 3, and they are incompatible.

The brief exists but isn't used in requests. A file in the repository won't insert itself into the conversation — unless it is the context file the tool picks up by itself (article 3.14).

Cheat sheet