Вы уже несколько дней разрабатываете приложение с ИИ. Нейросеть знает, где лежат компоненты, какие библиотеки используются и почему авторизацию нельзя менять. Но стоит открыть новый чат, и помощник снова предлагает установить ненужный пакет, создаёт папки с другими названиями или переписывает работающую функцию.
Повторять все договорённости перед каждой задачей необязательно. В Codex, Claude Code, Cursor и GitHub Copilot есть способы передавать постоянные инструкции вместе с проектом. Разберёмся, как они работают, что записывать в AGENTS.md и CLAUDE.md, как настраивать Cursor Rules и сохранять важный контекст между рабочими сессиями.
Почему ИИ забывает устройство проекта и прежние договорённости
Языковая модель работает с информацией, которая доступна ей в текущем запросе. Это могут быть ваши сообщения, содержимое файлов, результаты поиска по проекту, инструкции и ответы инструментов.
Совокупность этих данных называют контекстом. Его максимальный объём ограничен контекстным окном, которое измеряется в токенах. Токены представляют собой единицы обработки текста. Их количество зависит от содержимого, поэтому один токен не равен фиксированному числу символов.
Когда диалог становится слишком длинным, инструменты могут сокращать историю, сохраняя её в виде пересказа. Например, из предыдущего обсуждения останется информация, что вы работаете над формой регистрации, но исчезнет договорённость не менять определённый компонент.
При открытии нового чата прежняя переписка также не обязательно передаётся модели. Даже если история сохранена в интерфейсе, это ещё не означает, что все её сообщения включены в новый запрос.
Отсюда появляются знакомые проблемы:
- Нейросеть выбирает библиотеку, которую вы ранее решили не использовать.
- Создаёт новые компоненты вместо повторного использования существующих.
- Меняет названия функций и файлов вопреки соглашениям проекта.
- Переписывает работающий код при исправлении небольшой ошибки.
- Забывает решения, согласованные в предыдущей сессии.
Решить часть этих проблем помогает context engineering, или управление контекстом ИИ. Так называют организацию информации, которую получает модель для выполнения задачи: от постоянных правил проекта до конкретных файлов и результатов тестирования.
У Visual Studio Code есть отдельное руководство по устройству контекста ИИ-агентов. Важная идея заключается в том, что помощнику нужно передавать сведения, относящиеся к текущей работе. Весь исходный код проекта необязательно загружать в каждый запрос.
Как подготовить проект, чтобы нейросеть понимала его архитектуру
Представим небольшое приложение для учёта задач на React и TypeScript. В нём уже есть интерфейс, серверные запросы, тесты и несколько десятков файлов.
Если попросить ИИ просто добавить фильтрацию задач, он может создать дополнительный модуль запросов или изменить хранение данных. Лучше предварительно объяснить структуру приложения и существующие соглашения.
Для начала полезно подготовить пять видов информации.
- Назначение проекта. Что делает приложение и какие функции входят в текущую версию.
- Архитектура. Где находятся компоненты, бизнес-логика, обращения к API и тесты.
- Технологии. Используемые языки, фреймворки, основные библиотеки и версии.
- Соглашения. Правила именования, оформления кода и использования существующих модулей.
- Ограничения. Какие решения менять нельзя, где требуется согласование и как проверять результат.
Например, структура проекта может выглядеть так:
task-app/
├── src/
│ ├── components/
│ ├── pages/
│ ├── services/
│ ├── hooks/
│ └── types/
├── tests/
├── package.json
├── tsconfig.json
└── AGENTS.md
Здесь components содержит повторно используемые элементы интерфейса, pages страницы, services функции обращения к серверу, hooks пользовательские хуки React, а types описания типов TypeScript.
Такая структура служит примером. У реального приложения папки могут называться иначе. Важно описывать существующее устройство проекта, иначе нейросеть начнёт ориентироваться на структуру, которой в нём нет.
Полезно также зафиксировать архитектурные решения. Например, все запросы к серверу должны проходить через src/services, а компоненты интерфейса не должны самостоятельно работать с fetch(). Тогда агент сможет учитывать это правило при добавлении новых функций.
При этом не стоит копировать в инструкции полный список из сотен файлов. Структура постоянно меняется, а объёмный перечень быстро устаревает. Лучше указать основные папки и объяснить, где искать подробности.
Для крупных проектов можно создать отдельный ARCHITECTURE.md с описанием модулей, важных зависимостей и потоков данных. Нужные сведения из него агент будет получать при работе над соответствующей задачей.
AGENTS.md: как создать постоянные инструкции для Codex и других ИИ-агентов
AGENTS.md представляет собой Markdown-файл с инструкциями для программирующих ИИ-агентов. Обычно его размещают в корневой папке проекта и сохраняют вместе с остальным кодом.
Формат поддерживается OpenAI Codex, Cursor и рядом других инструментов. В актуальных версиях Claude Code также появилась поддержка AGENTS.md. Однако правила обнаружения файлов различаются, поэтому нельзя считать, что все агенты обрабатывают их одинаково.
В AGENTS.md стоит записывать сведения, которые пригодятся при выполнении разных задач. Например, архитектуру, команды проверки, правила именования и ограничения на изменение существующего кода.
Пример AGENTS.md для приложения на React и TypeScript:
# Project: Task App
## Stack
- React and TypeScript.
- Use the dependencies from package.json.
- Do not add packages without approval.
## Architecture
- Components: src/components/
- Pages: src/pages/
- API requests: src/services/
- Shared types: src/types/
- Tests: tests/
## Code conventions
- Use PascalCase for React components.
- Use camelCase for functions and variables.
- Reuse existing components and services.
- Follow the patterns in nearby files.
## Change rules
- Read related files before editing.
- Keep changes within the requested scope.
- Do not change API contracts without approval.
- Do not rewrite unrelated working components.
- Do not modify generated files.
## Verification
- Run npm run lint.
- Run npm test.
- Report failed or skipped checks.
- List changed files in the final response.
Такой файл можно адаптировать под Python, Vue, Next.js или другой проект. Команды npm run lint и npm test должны действительно существовать в package.json. Если они не настроены, сначала добавьте соответствующие скрипты либо замените команды на используемые в вашем проекте.
В примерах работы с Codex AGENTS.md используют для хранения постоянных соглашений, а планы и результаты отдельных этапов записывают в дополнительные файлы. Это позволяет не превращать основной документ в историю всей разработки.
Можно ли создавать несколько AGENTS.md? Да. В Codex поддерживается иерархия инструкций по каталогам. Например, в корне можно описать общие соглашения, а в tests/AGENTS.md правила тестирования.
В таком случае агент учитывает инструкции, обнаруженные для соответствующего рабочего каталога. Но у других инструментов механизмы загрузки вложенных файлов могут отличаться.
Если вы используете несколько ИИ-помощников, AGENTS.md удобен как общий набор правил. Дополнительные настройки, специфичные для каждого инструмента, можно хранить отдельно.
CLAUDE.md и Cursor Rules: настройка инструкций для разных инструментов
У Claude Code и Cursor есть собственные форматы проектных инструкций. Они решают похожие задачи, но отличаются расположением файлов и способом применения правил.
| Инструмент | Файлы инструкций | Особенности |
|---|---|---|
| OpenAI Codex |
AGENTS.md
|
Поддерживает инструкции проекта и каталогов. |
| Claude Code |
CLAUDE.md, .claude/rules/
|
Есть правила для отдельных путей, импорт файлов и автоматическая память. |
| Cursor |
.cursor/rules/*.mdc, AGENTS.md
|
Правила могут применяться постоянно, по пути файла или по запросу. |
| GitHub Copilot |
.github/copilot-instructions.md, AGENTS.md
|
Поддерживает общие и специализированные инструкции. |
Как работает CLAUDE.md
Claude Code использует файл CLAUDE.md в корне проекта или .claude/CLAUDE.md. Личные инструкции для разных проектов можно хранить в ~/.claude/CLAUDE.md.
Файл можно создать вручную или выполнить команду /init в Claude Code. Инструмент изучит проект и предложит начальный вариант инструкций, который затем стоит проверить.
Пример содержимого:
# Task App
## Architecture
- React components are in src/components/.
- API requests belong in src/services/.
- Shared types are in src/types/.
## Development
- Use existing dependencies.
- Preserve public component interfaces.
- Run npm run lint and npm test.
- Explain any changes to API contracts.
## Workflow
- Inspect relevant code before editing.
- Propose a plan for large changes.
- Keep unrelated files unchanged.
Для дополнительных правил можно использовать папку .claude/rules/. Например, создать api.md с инструкциями, которые применяются только к файлам API.
---
paths:
- "src/services/**/*.ts"
---
# API rules
- Use the existing API client.
- Handle unsuccessful HTTP responses.
- Keep response types in src/types/.
- Do not change endpoint paths without approval.
Параметр paths позволяет ограничить применение правил подходящими файлами. Подробности описаны в документации Claude Code.
Здесь есть важная особенность актуальных версий. Claude Code начиная с версии 2.1.277 может читать AGENTS.md напрямую. Но если в проекте присутствует CLAUDE.md, по умолчанию используются именно инструкции CLAUDE.md. Чтобы совместить оба файла без повторения текста, можно добавить в CLAUDE.md строку импорта:
@AGENTS.mdТогда Claude загрузит содержимое общего файла. Другой вариант предусмотрен настройкой Project instructions в Claude Code. Это пригодится командам, которые используют одновременно Codex и Claude.
Как работают Cursor Rules
В Cursor правила проекта находятся в папке .cursor/rules/. Для них используют файлы с расширением .mdc. Обычный файл .md в этой папке не распознаётся механизмом Project Rules как правило.
Например, создадим .cursor/rules/react-components.mdc:
---
globs: src/components/**/*.tsx
alwaysApply: false
---
# React component rules
- Use TypeScript for new components.
- Follow the style of nearby components.
- Reuse existing hooks where possible.
- Do not introduce new UI libraries.
- Preserve existing component props.В данном примере инструкция автоматически применяется, когда подходящий файл находится в контексте работы агента.
В Cursor доступны четыре режима применения Project Rules:
- Always Apply. Правило включается в каждую соответствующую сессию.
- Apply Intelligently. Агент определяет необходимость правила по его описанию.
- Apply to Specific Files. Правило применяется при работе с файлами, соответствующими шаблону.
- Apply Manually. Пользователь подключает правило вручную через упоминание.
Настройка описана в официальной справке Cursor. Если нужны только общие инструкции без условий применения, Cursor также умеет использовать AGENTS.md в корне проекта.
Для GitHub Copilot аналогичную задачу решает .github/copilot-instructions.md. А правила для отдельных файлов можно хранить в .github/instructions/ с расширением .instructions.md и параметром applyTo.
Необязательно создавать все перечисленные форматы сразу. Выберите основной инструмент и начните с одного файла. Если затем добавите другого агента, проверьте его поддержку существующих инструкций.
Как управлять контекстным окном и сохранять решения между сессиями
Постоянные инструкции помогают модели придерживаться архитектуры, но не заменяют историю текущей задачи. Например, агент может знать правила проекта, однако в новой сессии не помнить, почему вчера была выбрана конкретная реализация и какие ошибки остались неисправленными.
Для продолжительной разработки полезно хранить три типа документов:
AGENTS.mdилиCLAUDE.mdс постоянными правилами.ARCHITECTURE.mdс устройством программы и важными техническими решениями.PROGRESS.mdс состоянием текущей работы, выполненными задачами и нерешёнными проблемами.
Последний файл можно обновлять после каждого существенного этапа. Например:
# Current progress
## Completed
- Added task filtering.
- Updated API response types.
- Added filtering tests.
## Decisions
- Filtering is performed on the client.
- Existing API endpoints remain unchanged.
## Remaining
- Add a reset button.
- Check the mobile layout.
## Verification
- npm run lint: passed
- npm test: passedЭто пример пользовательской организации проекта, а не обязательный формат конкретного агента. Главное, чтобы указанные результаты тестирования действительно были получены.
Перед завершением сессии можно попросить помощника подготовить такую запись:
Подведи итог текущей работы. Перечисли изменённые файлы, реализованные функции, важные технические решения, результаты выполненных проверок и оставшиеся задачи. Обнови PROGRESS.md, не изменяя другие документы. Не указывай тест как пройденный, если он не запускался.
В новой сессии достаточно попросить агента прочитать этот документ вместе с инструкциями проекта и проверить фактическое состояние файлов.
Что делать, если контекстное окно переполнено?
Для начала перестаньте передавать всю историю работы и большие файлы без необходимости. Например, при исправлении ошибки в одном компоненте обычно достаточно соответствующего файла, вызывающего кода, сообщения об ошибке и применимых правил.
В Claude Code есть команда /context, показывающая использование контекста, и /compact, которая сокращает историю беседы. Команда /clear начинает новую беседу, сохраняя проектные инструкции. Но сокращённый пересказ может потерять подробности, поэтому важные решения лучше фиксировать в файлах.
В Claude Code также есть автоматическая память, которая сохраняет некоторые сведения о проекте и прежних исправлениях. Её можно просматривать через /memory. Однако для обязательных архитектурных решений надёжнее использовать контролируемые вами инструкции.
Отдельное правило касается больших проектов: не загружайте все файлы в модель на всякий случай. В руководстве VS Code рекомендуют начинать с необходимого контекста и подключать дополнительные материалы по мере выполнения задачи.
Пошаговая настройка для существующего проекта
- Откройте проект в редакторе и проверьте реальную структуру каталогов, зависимости и команды запуска.
- Создайте AGENTS.md или другой файл инструкций, соответствующий вашему агенту.
- Запишите основные архитектурные правила, соглашения об именовании и команды проверки.
- Добавьте отдельные инструкции для модулей, которым нужны особые правила.
- Начните новую сессию и попросите агента перечислить загруженные инструкции. При необходимости проверьте их через диагностические средства инструмента.
- Дайте небольшую тестовую задачу. Убедитесь, что агент использует существующие компоненты и не меняет посторонние файлы.
- Сохраните утверждённые правила в Git и регулярно обновляйте их при изменении архитектуры.
Есть важное ограничение: файлы AGENTS.md, CLAUDE.md и Cursor Rules направляют поведение модели, но не обеспечивают строгий запрет действий. Инструкция «не удалять файлы» сама по себе не блокирует команду удаления. Для реальной защиты нужны ограничения разрешений, изоляция среды и контроль команд.
Поэтому перед серьёзными изменениями сохраняйте рабочее состояние через Git, проверяйте список затронутых файлов и запускайте тесты. Секретные ключи, пароли и токены не следует помещать в общие файлы инструкций.
И ещё: слишком длинный AGENTS.md способен мешать не меньше, чем его отсутствие. Десятки общих советов, противоречивые требования и устаревшие команды увеличивают объём контекста. Лучше оставить конкретные правила, которые модель действительно должна учитывать, а подробную документацию хранить отдельно.
Вопросы и ответы
Что такое AGENTS.md и зачем он нужен?
AGENTS.md содержит постоянные инструкции для ИИ-агентов, работающих с кодом. В нём можно описать архитектуру проекта, правила именования, ограничения на изменения и команды тестирования. Формат поддерживается Codex, Cursor и другими инструментами.
Куда положить AGENTS.md в проекте?
Обычно файл размещают в корне репозитория. Для отдельных каталогов можно создавать дополнительные AGENTS.md, если используемый агент поддерживает вложенные инструкции и соответствующие правила их обнаружения.
Чем отличаются AGENTS.md и CLAUDE.md?
Оба файла содержат инструкции для работы ИИ с проектом. AGENTS.md поддерживается несколькими инструментами, а CLAUDE.md предназначен для Claude Code. Актуальные версии Claude Code умеют читать AGENTS.md, но при наличии проектного CLAUDE.md по умолчанию выбирают его. Файлы можно объединить через импорт или настройку загрузки.
Как создать CLAUDE.md автоматически?
Откройте Claude Code в каталоге проекта и выполните команду /init. Инструмент проанализирует доступный код и предложит начальные инструкции. Перед использованием проверьте созданный документ и исправьте неточности.
Где находятся Cursor Rules и как их настроить?
Правила проекта Cursor хранятся в .cursor/rules/ в файлах с расширением .mdc. Можно настроить постоянное применение, выбор по типу файлов, автоматический выбор по описанию или ручное подключение правила.
Как сохранить контекст ИИ между сессиями программирования?
Сохраните постоянные правила в AGENTS.md или CLAUDE.md, архитектуру в отдельной документации, а текущий прогресс в рабочем файле. В новой сессии попросите агента прочитать эти документы и проверить состояние проекта.
Почему ИИ не соблюдает правила из AGENTS.md?
Возможно, агент не обнаружил файл, инструкции противоречат друг другу или содержат слишком общие формулировки. Проверьте поддерживаемые пути, загрузку файла и применимость правил. Даже правильно загруженные инструкции не гарантируют полного соблюдения, поэтому необходимы проверка изменений и тестирование.
