Контекст и соглашения для AI

Как устроить проект, чтобы ассистент писал код, который в него вписывается: записанные соглашения, единообразные паттерны и машиночитаемые инструкции, которые живут вместе с репозиторием.

Почему это важно. Агент выводит ваши соглашения из того, что видит. Кодовая база, где одна и та же задача решена тремя способами, учит его, что допустимы все три, — и он придумает четвёртый. Единообразие ценилось всегда; теперь оно работает как сложный процент.

Что понимать

• Что агент на самом деле видит — а это меньше, чем весь репозиторий
• Что он выведет из кода — верно или нет
• Какие правила существуют только в головах у людей
• Где лежат инструкции, чтобы их находили, а не вставляли в каждый запрос
• Соответствуют ли инструкции коду до сих пор

Основные темы

Инструкции в репозитории

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

Что записывать

• Структура: что где лежит и кому что разрешено импортировать
• Именование и раскладка файлов
• Команды сборки, тестирования и проверок
• Паттерны, которым стоит следовать, и антипаттерны, которых стоит избегать, — с обоснованием
• Чего нельзя делать никогда — правила с реальными последствиями

Единообразие как контекст

• Один способ для каждой задачи, чтобы паттерн читался однозначно
• Правильные примеры — потому что их будут копировать
• Удаление мёртвого кода: это контекст, вводящий в заблуждение
• Типы и понятные сигнатуры как машиночитаемое выражение замысла

Проверки как контекст

• Тесты, линтеры и проверка типов как источник истины, по которому агент может себя сверить
• Быстрая обратная связь, чтобы агент мог исправиться сам
• Пусть сборка громко падает, а не тихо предупреждает

Как поддерживать это в актуальном состоянии

• Инструкции протухают ровно так же, как документация
• Обновлять их в том же изменении, что и код
• Замечать, когда агент раз за разом делает одну и ту же ошибку: это недостающее правило

Уровни

Уровень	Как это выглядит
Junior	Следует соглашениям проекта и пользуется его файлами инструкций.
Middle	Пишет и поддерживает инструкции, удерживает единообразие паттернов, замечает, где ошибки агента вскрывают пробел.
Senior	Устраивает проект так, чтобы корректность проверялась машиной, следит, чтобы соглашения обеспечивались инструментами, и относится к инструкциям как к части кодовой базы.

Практика

Для начала

• Запишите правила Заведите файл инструкций проекта: структура, команды и три самых важных правила.

• Найдите разнобой Найдите в своей кодовой базе задачу, решённую тремя разными способами, и приведите её к одному решению.

• Проверьте инструкции Дайте агенту задачу и посмотрите, следует ли он им. Исправьте то, что он упустил.

Глубже

• Ограничьте область инструкций Добавьте инструкции на уровне каталога для области со своими правилами.

• Сделайте правило проверяемым Превратите записанное соглашение в правило линтера, которое роняет сборку.

• Замкните цикл Заметьте ошибку, которую агент повторяет, добавьте недостающее правило и убедитесь, что она исчезла.

Проверьте себя

• Что агент поймёт о ваших соглашениях по одному только коду?
• Какие из ваших правил живут только в комментариях к code review?
• Соответствуют ли ваши файлы инструкций текущей кодовой базе?
• Какую ошибку ассистент раз за разом повторяет в вашем проекте?
• Как агент проверит собственную работу в вашем репозитории?
• Какой мёртвый код лежит и учит неправильному паттерну?

Ресурсы

• Claude Code memory and CLAUDE.md — как загружаются инструкции проекта и на какие области они распространяются. Самая внятная модель инструкций, которые живут вместе с репозиторием.
• GitHub Copilot custom instructions — та же идея в другом инструменте: полезно, чтобы увидеть, что здесь общего.
• Effective Dart — образец того, как писать соглашения: каждое правило вместе с причиной — именно это и позволяет правилам выживать.
• llms.txt — соглашение о том, как сделать сайт или проект читаемым для моделей. Актуально, если поверх вашего проекта что-то строят другие.
• Customizing static analysis — потому что самая сильная инструкция — та, которую обеспечивает инструментарий, а не та, что написана прозой.