Когда CLAUDE.md перестаёт помогать

Почти каждая команда, которая начинает работать с Claude Code, Codex или Cursor, приходит к одному и тому же: заводит файл с правилами. CLAUDE.md, AGENTS.md, cursor rules. Туда пишут, как запускать тесты, какие библиотеки не использовать и что не трогать в старом модуле. Первые недели это работает отлично.

Проблемы начинаются позже, и не сразу понятно, откуда они.

Файл отстаёт от кода

Модуль переехал в другую папку, а правило в файле осталось про старый путь. Решение пересмотрели на встрече, а файл никто не обновил. Агент честно выполняет инструкцию, которая уже не соответствует проекту, и ревьюер узнаёт об этом последним.

Правило в файле ничем не связано с кодом, к которому относится. Поэтому никто не замечает, когда оно устаревает.

У каждого свой файл

В команде из восьми человек через пару месяцев оказывается шесть версий правил: в разных репозиториях, в личных настройках, в заметках. Агенты разных разработчиков ведут себя по-разному, и спор «как у нас принято» переезжает на ревью.

Агент читает всё сразу

Файл растёт. Чтобы поправить одну функцию, агент получает в контекст всё: правила для фронтенда, для миграций, для платёжного модуля. Это стоит токенов, а главное, нужное правило теряется среди ненужных.

Совет без проверки

Файл подсказывает, но не проверяет. Если агент нарушил договорённость, это всплывёт на ревью, а это самое дорогое место для поиска ошибок. По данным CodeRabbit, в pull request, написанных с ИИ, примерно в 1,7 раза больше замечаний, чем в написанных людьми. А по данным LinearB, PR от агентов ждут начала ревью заметно дольше: проверяющие не доверяют такому коду без разбора.

Одна версия на все ветки

Когда агенты работают над несколькими задачами параллельно, решение, принятое в одной ветке, сразу попадает в общий файл. Другая задача начинает опираться на то, что ещё не прошло merge и может быть отменено.

Что с этим делать

Если проект небольшой и над ним работают один-два человека, файл с правилами — нормальное решение, и усложнять ничего не нужно.

Когда команда растёт, правилам нужны четыре свойства, которых у файла нет:

• связь с конкретными модулями и функциями, чтобы было видно, когда правило устарело;
• одна база на команду вместо личных файлов;
• доставка агенту только того, что относится к текущей задаче;
• проверка изменений по правилам до merge request.

В AI Council мы сделали именно это, плюс разделили знания по git‑веткам. Файл CLAUDE.md при этом можно оставить: обычно в нём остаётся короткое описание проекта, а договорённости переезжают в базу как правила уровня MUST и SHOULD.

Подробное сравнение AI Council и CLAUDE.md

Хотите посмотреть на своём проекте? Запишитесь на демо: подключим репозиторий и покажем первое ревью на вашем коде.