AGENTS.md / SESSION_NOTES — проектная память для coding-агентов

AGENTS.md хранит постоянные инструкции для AI-агентов, работающих с кодом: карту проекта, команды, границы изменений и обязательные проверки. Этот материал показывает, как передавать состояние между сессиями, не смешивая постоянные правила с журналом работы.

В этой схеме AGENTS.md — открытый формат, который Codex поддерживает нативно. SESSION_NOTES.md и checkpoint — соглашения команды без специального режима Codex; их нужно явно подключить правилом, текущей задачей или настройкой.

Оглавление

1. Целевая архитектура проектной памяти — какие вопросы решает каждый слой.
2. Как Codex загружает AGENTS.md — области действия, приоритеты и лимит.
3. Что писать в AGENTS.md — практическое содержание постоянных правил.
4. Минимальный рабочий шаблон — пример файла для репозитория.
5. SESSION_NOTES.md — краткий журнал подтверждённого состояния.
6. Checkpoint для большой задачи — передача рабочего контура.
7. Совместимость с другими агентами — Copilot CLI и Claude Code.
8. Чеклист быстрой проверки — контроль перед внедрением.

Целевая архитектура проектной памяти

Каждый слой отвечает на отдельный вопрос:

Пример разделения:

AGENTS.md:
deploy требует отдельного подтверждения.

SESSION_NOTES.md:
локальное исправление готово, тесты прошли, deploy не выполнялся.

Checkpoint:
указаны репозиторий, ветка, commit, результаты тестов,
блокер, разрешённый следующий этап и способ отката.

Постоянные правила не должны превращаться в журнал. Датированный checkpoint нужно сверять с веткой, файлами и текущим состоянием системы перед продолжением.

Как Codex загружает AGENTS.md

Описание ниже проверено 9 сентября 2026 года по документации Codex и исходному коду Codex. Цепочка инструкций создаётся при запуске задачи; в терминальном интерфейсе Codex (TUI) обычно один раз при открытии новой сессии.

Глобальный уровень

В каталоге конфигурации Codex, по умолчанию ~/.codex/, сначала проверяется AGENTS.override.md. Если файл отсутствует или пуст, используется AGENTS.md. При заданной переменной CODEX_HOME глобальные инструкции ищутся в указанном каталоге. На этом уровне используется первый непустой файл.

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

Уровень проекта

Codex идёт от корня проекта до текущей рабочей директории. Реализация определяет корень по настроенным project_root_markers; по умолчанию используется маркер .git. Если корень не найден, проверяется только текущая директория.

В каждой директории Codex ищет не более одного файла в таком порядке:

1. AGENTS.override.md;
2. AGENTS.md;
3. дополнительные имена из project_doc_fallback_filenames.

Найденные файлы объединяются от корня к текущей директории. Более близкие инструкции оказываются в контексте позже и при конфликте обычно имеют больший приоритет. AGENTS.override.md занимает место обычного AGENTS.md в той же директории, поэтому его используют только для осознанной локальной замены правил.

Лимит инструкций

Суммарный бюджет проектных инструкций задаёт параметр project_doc_max_bytes; значение по умолчанию — 32 KiB. Это лимит всей цепочки, а не одного файла. Пустые файлы пропускаются. Если бюджет заканчивается, текущий файл может быть усечён, а следующие документы в контекст не попадут.

Практические меры:

• оставляйте в AGENTS.md только сведения, которые нужны регулярно;
• не копируйте туда весь README и большие архитектурные документы;
• размещайте специализированные правила рядом с соответствующим модулем;
• удаляйте устаревшие команды и конфликтующие формулировки;
• длинные повторяемые процедуры выносите в отдельную документацию или Skills.

AGENTS.md направляет поведение модели, но не является технической защитой. Для опасных операций нужны sandbox, минимальные права, отдельные credentials, подтверждения, branch protection и ограничения CI или инфраструктуры. В инструкциях нельзя хранить токены, пароли, ключи, содержимое .env, персональные данные и закрытые строки подключения.

Что писать в AGENTS.md

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

Назначение и источники правды

Опишите состав репозитория, его границы и системы, которые находятся вне области изменений. Зафиксируйте порядок доверия при конфликте: исполняемое поведение, конфигурация, код, актуальная документация, task tracker, исторические отчёты.

Команды и архитектура

Укажите точные команды установки, запуска, lint, typecheck, тестов и сборки вместе с рабочей директорией. Объясните владельцев данных и поведения, допустимые зависимости и части системы, которые нельзя менять в одном изменении.

Правила редактирования и проверки

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

Production и внешние системы

Явно перечислите deploy, push, merge, публикацию, изменения базы и DNS, операции с billing и auth, отправку сообщений и удаление данных. Для каждого действия укажите необходимый approval-гейт.

Минимальный рабочий шаблон

# AGENTS.md

## Назначение

Это frontend-приложение проекта Example.
Серверная часть находится в другом репозитории.

## Команды

Рабочая директория: корень репозитория.

- Установка: `npm install`
- Development: `npm run dev`
- Lint: `npm run lint`
- Typecheck: `npm run typecheck`
- Tests: `npm test`
- Build: `npm run build`

Не придумывать команды, которых нет в `package.json`.

## Границы

Можно читать репозиторий, изменять файлы в `src/` и запускать локальные проверки.

Сначала спросить перед добавлением production-зависимости, изменением схемы данных, правкой CI или созданием миграции.

Без отдельного подтверждения нельзя выполнять deploy, push или merge, менять production, выводить secrets и удалять пользовательские данные.

## Проверка

1. Проверить diff.
2. Запустить lint, typecheck и релевантные тесты.
3. Проверить изменённый пользовательский сценарий.
4. Перечислить проверки и оставшиеся ограничения.

Начните с короткого файла и расширяйте его после повторяющихся проблем, подтверждённых в работе.

SESSION_NOTES.md

Codex не распознаёт SESSION_NOTES.md как специальный стандарт. Чтобы журнал использовался, добавьте явное правило в AGENTS.md, задачу или настройку fallback-файлов.

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

## YYYY-MM-DD — краткое название задачи

### Результат
Что фактически сделано.

### Изменённые файлы
- `path/to/file`

### Проверки
- `npm run lint` — прошло
- мобильная проверка — не выполнялась

### Решения
- Выбран вариант A, потому что…

### Не затронуто
- production;
- база данных;
- внешние сервисы.

### Блокеры и неизвестное
- Не подтверждено…

### Следующий шаг
Одно конкретное безопасное действие.

Не добавляйте в журнал токены, персональные данные, полные логи и приватные абсолютные пути.

Checkpoint для большой задачи

Checkpoint нужен, когда работа длится несколько дней, переходит между чатами или исполнителями, затрагивает несколько репозиториев либо зависит от точной версии, approval или отката.

# Checkpoint: название рабочего контура

Дата: YYYY-MM-DD
Статус: active / blocked / complete

## Цель
Проверяемый конечный результат.

## Текущее состояние
Что подтверждено на момент checkpoint.

## Источники правды
- репозиторий и ветка;
- документация;
- исполняемая система или внешний сервис.

## Выполнено и подтверждения
- изменение;
- проверка;
- commit, diff, результат теста или read-back.

## Границы и блокеры
Что разрешено, что требует подтверждения и что мешает продолжить.

## Откат
Как вернуть безопасное состояние.

## Следующий шаг
Одно конкретное действие.

Перед продолжением по старому checkpoint заново сверьте ветку, файлы, исполняемую систему и внешнее состояние.

Совместимость с другими агентами

OpenAI Codex

Codex нативно загружает глобальные и проектные AGENTS.md, поддерживает вложенную цепочку, AGENTS.override.md, дополнительные имена файлов и настраиваемый лимит в байтах.

GitHub Copilot CLI

GitHub Copilot CLI обнаруживает AGENTS.md в стандартных расположениях вместе с другими форматами инструкций. При наличии нескольких применимых файлов Copilot CLI объединяет их, но не задаёт общего порядка приоритета между этими форматами. Избегайте конфликтующих правил. Активные источники можно проверить командой /instructions.

Это описание относится именно к Copilot CLI. Его поведение нельзя автоматически переносить на все интерфейсы и режимы GitHub Copilot.

Claude Code

Claude Code использует CLAUDE.md, а не AGENTS.md. Чтобы переиспользовать общие правила, создайте CLAUDE.md с импортом @AGENTS.md, а ниже добавьте специфические инструкции Claude Code. Если отдельные правила не нужны, допустим симлинк:

ln -s AGENTS.md CLAUDE.md

На Windows импорт обычно проще, поскольку создание симлинка может требовать дополнительных прав.

Другие инструменты

Многие coding-агенты поддерживают AGENTS.md, но обнаружение файлов, область действия и разрешение конфликтов различаются. Перед внедрением проверьте документацию конкретного runtime.

Чеклист быстрой проверки

Следующий шаг

Codex App — единый справочник по среде от OpenAI

Эта схема полезна командам, которым нужно сделать работу coding-агентов воспроизводимой и безопасной. Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov