Файл контекста проекта

написать один раз вместо того, чтобы объяснять каждый день

Что это

Файл контекста — текстовый файл в корне проекта, который ИИ читает в начале работы. В него складывают то, что иначе приходится объяснять в каждом новом разговоре: стек и версии, структуру проекта, принятые соглашения, команды запуска.

Файл закрывает причину 2 из статьи 3.1 — «он не видит» — раз и навсегда. Признак того, что он нужен: ты второй раз пишешь в чат одно и то же про свой проект.

Называется по-разному в зависимости от инструмента: CLAUDE.md, AGENTS.md, правила в .cursor/rules/. Суть одна, и содержимое переносится между ними почти без правок.

Как выглядит в коде

# Бот подписок на погоду

## Стек
Python 3.12, aiogram 3.x, SQLite через aiosqlite.
Зависимости в requirements.txt, виртуальное окружение в .venv.

## Структура
bot.py          точка входа, запуск polling
handlers/       хендлеры команд, по файлу на тему
storage.py      работа с БД, все запросы здесь
db.py           подключение, get_conn()
config.py       чтение переменных окружения

## Соглашения
- Все обращения к БД — через функции storage.py.
  В хендлерах SQL не пишем.
- Хендлеры асинхронные, тяжёлые операции не блокируют цикл.
- Тексты ответов пользователю — в locales/ru.py, не в коде.
- Логи через logging, не print.

## Запуск
python -m venv .venv && .venv/bin/pip install -r requirements.txt
python bot.py              запуск
pytest -q                  тесты

## Чего не делать
- Не добавлять зависимости без необходимости.
- Не трогать migrations/, они применяются по порядку.
- Токены только из переменных окружения, в коде их нет.

Это полный файл, а не фрагмент. Короткий — и в этом его ценность.

Как сказать ИИ

Пять разделов, и этого достаточно

Раздел «Стек» с версиями — самый важный: он закрывает причину 3 из статьи 3.1, ту самую, которую нельзя вылечить подробностью запроса.

Раздел «Соглашения» — второй по отдаче. Именно он заставляет ИИ писать в стиле проекта, а не в своём.

Главное правило: коротко

Файл читается в начале каждого разговора и занимает место в контексте. Длинный файл вытесняет собой код, который ИИ мог бы прочитать, и внимание размывается.

Ориентир: одна-две страницы. Если не помещается — значит, в файл попало то, что ИИ может узнать сам, прочитав проект.

Как поддерживать

Проще всего — обновлять его тем же ИИ, который в проекте работает:

Прочитай CLAUDE.md и сравни с тем, что сейчас в проекте.
Что в файле устарело? Только список расхождений, без правок.

Хороший момент для такой проверки — когда добавил модуль, сменил версию библиотеки или поменял способ запуска.

На что смотреть

Файл есть, а ИИ его не читает. В чате файл надо вставлять вручную, сам он туда не попадёт. Агенты в терминале обычно читают его сами, но не все и не всегда — проверь, спросив: «что ты знаешь о структуре этого проекта?»

В файле описано желаемое, а не действительное. «Все запросы к БД через storage.py» — а на деле в трёх хендлерах SQL прямо в коде. ИИ будет считать написанное правдой.

Файл разросся до десяти страниц. Туда переехала документация, история решений, список всех эндпоинтов. Вынеси это в отдельные файлы, а в контекстном оставь ссылки.

Шпаргалка