You spend 20 minutes explaining to your AI assistant that this codebase uses tabs not spaces, that every function needs a docstring, that you prefer early returns over nested ifs, that this project uses snake_case for files even though the team uses kebab-case elsewhere. It nails the next three files. You're thrilled.
Then you start a new session the next morning. It's back to spaces, nested ifs, and JSDoc-style comments. Like the last conversation never happened.
Here's why that's built into how these tools work — and the one-file pattern I use to fix it permanently.
Why this keeps happening
LLMs have no persistent memory between sessions. Whatever you taught the model in yesterday's chat is gone the moment you open a new window. The only "memory" that survives is whatever you put into the prompt at the start of the new session.
Most people solve this by re-explaining conventions every time, or by copy-pasting a style guide into every prompt. Both are tedious and error-prone. You'll forget to include the "prefer early returns" rule three times a week, and the model will cheerfully write nested nightmares until you catch it.
The real fix is to make the conventions a file in your project, and to make reading that file the first thing any AI assistant does when it touches your code.
The CONVENTIONS.md pattern
Create a file at the root of your project called CONVENTIONS.md. It's short, specific, and written in imperative voice. Here's the template:
# Project Conventions
## Tone / voice (for generated content)
- Neutral, concise, no emojis in code comments
- Prefer active voice
## Formatting
- Indentation: 4 spaces (NOT tabs)
- Line length: 100 chars
- Trailing commas: yes (for diff-friendliness)
## Naming
- Files: snake_case.py
- Classes: PascalCase
- Functions: snake_case
- Constants: SCREAMING_SNAKE
- Never abbreviate except: `db`, `id`, `url`, `http`
## Code style
- Prefer early returns over nested `if`s
- No single-letter variable names except in comprehensions
- Docstrings on every public function (Google style)
- Type hints on every function signature
## Libraries
- HTTP: requests (NOT httpx)
- Testing: pytest (NOT unittest)
- Dates: datetime with explicit UTC (NOT pendulum, NOT arrow)
## Directory rules
- Tests live in tests/, mirroring src/ structure
- No code in __init__.py beyond imports
- One class per file unless they're tightly coupled
## Things to NEVER do
- Don't add new dependencies without asking
- Don't refactor unrelated code
- Don't "improve" existing code style to match elsewhere
- Don't add comments that explain what the code does (only WHY)
## Things to ALWAYS do
- Run mypy --strict on any file you modify
- Add a test for every new public function
- Update CHANGELOG.md for user-facing changes
Keep it under 100 lines. If it's longer, nobody (human or model) will internalize it.
The invocation ritual
At the start of every AI-assisted session on this project, paste this one line:
Before you do anything else, read CONVENTIONS.md in the project root. Follow it strictly. If anything I ask contradicts it, ask me which should win before proceeding.
That's it. The model now has explicit instructions to (a) load the conventions, (b) follow them, and (c) flag conflicts rather than silently deviating.
I bolt this onto my project scaffolding template, so every new project starts with a CONVENTIONS.md and the invocation line sits in my session-starter snippet.
Why one file beats a styleguide folder
You might be tempted to split this across multiple files — naming conventions in one place, formatting in another, library choices in a third. Don't. The model has to read all of them anyway, and when they're split, you lose the ability to just say "read CONVENTIONS.md." You're now juggling "which files do you need to load?" again.
One file. Root of the project. Always read first. Simple rule.
What happens when conventions change
When the team decides to switch from requests to httpx, you update exactly one line in CONVENTIONS.md. Every future AI session will pick up the change automatically. No hunting through old prompts. No "wait, which library did we standardize on?"
This is the same reason README files work: a single canonical source of truth beats a dozen scattered reminders.
A real test
I ran a blind test on a Python project with a complex convention set (40 rules across formatting, naming, libraries, and anti-patterns):
- Without CONVENTIONS.md: Across 10 new files, the model violated an average of 7.2 conventions per file. Mostly formatting and library choices.
- With CONVENTIONS.md and the invocation line: Across 10 new files, the model violated an average of 0.6 conventions per file. Three files were completely clean.
That's an order-of-magnitude improvement from one file and one sentence.
The broader lesson: anything you find yourself re-explaining to your assistant is a missing file in your project. Write it down once, reference it always.
Question for you: What's the one convention you're tired of re-explaining to your AI assistant? Mine is "early returns, not nested ifs" — I must have said it 200 times before I wrote it down.
Top comments (0)