Артефакт недели: сам файл лежит в корне проекта GoRunWithAI. В конце статьи — пустой шаблон.
Весной 2026 года Андрей Карпати выложил свой CLAUDE.md — 65 строк личных правил работы с ИИ-агентом. Файл набрал больше 100 000 звёзд на GitHub. Не потому что там откровения — там простые вещи вроде «сначала план, потом код». А потому что это был рабочий конфиг живого человека, который можно забрать себе. Это самый недооценённый формат в теме ИИ-агентов: не обзоры возможностей, не «100 промптов», а конкретные правила, проверенные продом.
У меня признание похуже: полгода я писал проект с ИИ-агентами — сайт, который вы сейчас читаете, — и все правила держал в голове. В каждой сессии заново объяснял агенту одно и то же: не лезь в соседние файлы, сначала покажи план, запусти тесты. Пока во вторник мой сайт не лёг. Не от нагрузки, не от взлома — от фоновой задачи, которая заблокировала весь процесс. День я потратил на диагностику, починил перезапуском — и наконец сделал то, что откладывал полгода: записал все уроки в один файл.
Вот он целиком, с историями. Файл называется AGENTS.md — о выборе имени в конце.
Сначала короткий план изменения (что, где, зачем) — и жди подтверждения.
Единственное правило, которое экономит больше всего времени. Без него типичная сессия выглядит так: я прошу «добавь фильтр по тегам», агент молча пишет 400 строк, половина — про другое понимание задачи. С правилом он сначала выдаёт план из пяти пунктов, я вижу расхождение в пункте два — и мы не тратим 40 минут на код, который полетит в корзину.
По моим ощущениям, 80% недопонимания с агентом ловится именно на этапе плана. Это ровно то же, что техзадание для человека — только проверяется за 30 секунд, а не за час митинга.
Никаких «заодно поправил», «улучшил», «отрефакторил по пути». Заметил проблему вне задачи — скажи, не правь.
У агентов есть очаровательная черта джуниора: идёшь править баг в импорте, а тебе в пул-реквест приезжает «и ещё я немного почистил соседний модуль». Однажды такое «почистил» изменило поведение в месте, которое я вообще не смотрел на ревью, — к счастью, поймалось тестами, а не продом.
Ирония в том, что мусор AppleDouble (файлы ._*, которые macOS рассыпает по архивам) попал ко мне в прод ровно так же: приехал «заодно» с полезным изменением, и я его не заметил в диффе. С тех пор правило жёсткое: дифф должен быть про задачу и только про неё.
Новая логика — с тестом. Перед тем как отдать результат:
pytestиnpm run buildдолжны быть зелёными.
Без этого правила агент докладывает «готово» о коде, который не запускается. Буквально: «всё сделано» — и синтаксическая ошибка в файле, который он сам только что написал. Слово «готово» у агента должно означать «проверено», а не «написано».
Что это дало на моём проекте: ИИ-ревьюер с таким правилом за полгода поймал гонку двух планировщиков, тихий except Exception: pass в импорте контента и тесты, которые проходили только на моей машине из-за локальных env-переменных. Всё это дошло бы до прода.
alembic revision+alembic upgrade head, применяются при старте контейнера. Не вызывать миграции из кода приложения.
Шрам, который обнаружился случайно. В коде приложения при старте был вызов миграций — и месяцами в логах горела строчка:
RuntimeWarning: coroutine 'run_migrations_online' was never awaited
Корутина создавалась и молча не выполнялась. Миграции при этом работали — потому что дублировались в команде запуска контейнера. Но я полгода смотрел на код, который выглядел рабочим и ничего не делал. Хороший урок: «ошибок нет» и «работает» — не одно и то же. Правило теперь одно: миграции живут в одном месте, и это не код приложения.
Планировщик/воркеры не должны останавливать веб-сервер: всё долгое — в отдельный worker или с таймаутом и ретраями.
Свежий шрам, с него всё и началось. Мой сайт собирает новости по расписанию и кросспостит в Telegram. Планировщик жил в том же процессе, что и веб-сервер. Неделями в логах висели предупреждения «задача пропущена: предыдущая ещё выполняется» — я их игнорировал, потому что «ну а что такого». Во вторник какая-то из задач заблокировала цикл полностью: контейнер жив, метрики в норме, а сайт не отвечает даже на /api/health.
Починил перезапуском, правило записал в файл той же ночью. Если у вас фоновые задачи живут в том же процессе, что и прод, — это вопрос времени. У меня он наступил во вторник.
.env, зависимости — по запросуДва коротких гигиенических правила. Секреты не должны оказаться в коде, конфиге или — чего уж греха таить — в статье на сайте, потому что агент «привёл пример из жизни». А новые зависимости агент обожает тащить по любому поводу: у него всегда найдётся библиотека, которая «сделает всё сама». Каждая — это будущее обновление, уязвимость и конфликт версий. Сначала ищем решение в текущем стеке.
Проект у меня контентный, поэтому три правила — про тексты. Они появились позже остальных и, возможно, самые спорные:
Потому что агентов больше одного. Я работаю с разными инструментами, и держать по файлу под каждый — верный способ получить три расходящиеся версии правил. AGENTS.md — нейтральный формат, который читают все, а CLAUDE.md у меня состоит из одной строчки: «правила в AGENTS.md». Единый источник важнее лояльности к бренду агента.
Не копируйте мои правила целиком — они из моих шрамов, а не из ваших. Начните с пустого каркаса и заполняйте его инцидентами:
# Правила для ИИ-агентов — [проект]
## Стек
[2-3 строки: язык, фреймворк, как запускается, как деплоится]
## Правила работы с кодом
1. План перед кодом.
2. Не трогай код вне задачи.
3. Тесты запускай до того, как отдать результат.
4. [Правило из вашего последнего инцидента]
5. [Правило из предпоследнего]
## Проверка перед «готово»
- [ ] Тесты зелёные
- [ ] Ничего лишнего не изменено
Три совета по опыту:
Полгода я считал, что файл правил — это бюрократия для больших команд. Оказалось, это память. Агент забывает всё между сессиями, а файл — нет. Каждый инцидент, записанный в него, больше не повторяется. Тот, что не записан, — повторится, проверено во вторник.
Продолжение — в моём Telegram-канале: там я раз в две недели разбираю, какие правила дожили до продакшена, а какие пришлось выкинуть.