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

Кросс-вендорный стандарт, который объясняет coding-агенту правила проекта, фиксирует контекст между сессиями и передаёт смену между заходами. Используется в 60 000+ репозиториев, поддерживается ведущими coding-агентами и IDE.

Что это такое

AGENTS.md — файл в корне репозитория, который описывает проект для ИИ-агентов: команды сборки, архитектуру, конвенции, границы и правила ревью. Операционный контекст для LLM-агента, которому нужно стать продуктивным за 60 секунд.

Стандарт курируется Agentic AI Foundation при Linux Foundation с декабря 2025 года. К апрелю 2026: 60 000+ репозиториев используют AGENTS.md, поддержка встроена в OpenAI Codex, Cursor, Jules, GitHub Copilot, Zed, JetBrains и другие инструменты. Сам OpenAI Codex использует 88 таких файлов в своём монорепозитории.

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

Checkpoint — отдельный документ-«передача смены» для крупных рабочих потоков. Содержит полный контекст: где лежит код, как запускать, что сделано, что нельзя трогать.

Какую проблему решают

Coding-агент просыпается в новом мире каждую сессию. Без контекста даже сильная модель:

• путает production с preview, потому что границы проекта ей неизвестны;
• теряет всё, что было сделано вчера;
• рискует затронуть файлы, которые менять нельзя;
• выполняет действия, требующие отдельного approval;
• начинает каждый заход с археологии по истории чата.

AGENTS.md снижает этот риск, давая агенту правила до начала работы. SESSION_NOTES.md убирает проблему потери контекста между сессиями. Checkpoint передаёт полный контекст при смене «смены» — когда новый агент или новый чат берётся за сложный рабочий поток.

Структура AGENTS.md

GitHub опубликовал исследование (How to write a great agents.md: Lessons from over 2 500 repositories, ноябрь 2025) с практическими выводами о том, какие паттерны работают лучше всего:

Рекомендованный каркас

## Project overview        (1 абзац: что это, какой стек)
## Setup                   (команды для быстрого старта)
## Common commands         (build, dev, test, lint)
## Architecture            (карта директорий)
## Code conventions        (именование, экспорты, фреймворки)
## Boundaries              (yes edit / ask / never — таблица)
## Testing                 (команды и паттерны)
## PR guidelines           (формат коммитов, модель веток)
## Review guidelines       (рубрика для автоматического ревью)

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

# AGENTS.md

## Project overview
MyApp — fullstack-приложение на Next.js 14 + PostgreSQL + Prisma.

## Setup
npm install && cp .env.example .env.local && npm run db:migrate

## Common commands
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Boundaries
| Область           | Можно    | Спросить       | Нельзя         |
|--------------------|----------|----------------|----------------|
| src/               | ✅ edit  |                |                |
| prisma/migrations/ |          | ✅ ask         |                |
| .env*              |          |                | ❌ never       |
| CI/CD configs      |          | ✅ ask         |                |

Что НЕ включать (7 антипаттернов)

1. Инструкции для конкретной модели («when using Claude Opus, do X»)
2. Секреты и переменные окружения — AGENTS.md коммитится в git
3. Датированные факты («as of March 2025...») — агент будет действовать на устаревших данных
4. Большие архитектурные обзоры — агент должен исследовать код сам
5. Личные предпочтения под видом правил
6. Конфигурация инструментов — для этого есть конфиг-файлы
7. Role-play преамбулы («You are a senior engineer with 20 years...»)

SESSION_NOTES.md

SESSION_NOTES фиксирует не план, а реальность:

• что было сделано;
• какие файлы добавлены или изменены;
• какие проверки прошли;
• какие решения приняты;
• что не трогали и почему;
• какой следующий безопасный шаг.

Новый заход читает хвост SESSION_NOTES и продолжает работу без повторной раскачки. Особенно ценно при длинных многоэтапных задачах: агент видит точку остановки и продолжает с неё.

Checkpoint — передача смены

Для крупных рабочих контуров SESSION_NOTES недостаточно. Checkpoint — отдельная страница, содержащая:

• где лежит код и как запускать;
• что сделано в каждой версии;
• какие API доступны;
• что выяснили на практике;
• что нельзя делать без approval;
• следующий шаг.

Это полноценная передача смены. Любой новый агент или сессия может открыть checkpoint и получить полную карту.

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

Как начать

Минимальный старт (5 минут)

1. Создать AGENTS.md в корне репозитория
2. Заполнить три секции: Project overview, Setup, Common commands
3. Добавить секцию Boundaries с таблицей «yes edit / ask / never»
4. Закоммитить

Полная настройка (30 минут)

1. Выбрать подходящий архетип из шаблонного пакета (web app, monorepo, library, CLI, ML pipeline, content site, API service, IaC, mobile, data project)
2. Заменить плейсхолдеры: пути, команды, инструменты
3. Добавить SESSION_NOTES.md в корень — первая запись: текущее состояние проекта
4. Добавить симлинк ln -s AGENTS.md CLAUDE.md если используете Claude Code
5. Настроить ## Review guidelines для автоматического ревью PR

Поддержание

Относитесь к AGENTS.md как к коду. Ревьюйте при каждом PR-цикле (~30 секунд). Признаки дрейфа:

• Setup-команды не работают у нового участника → AGENTS.md врёт
• Агент повторяет одну и ту же ошибку → добавьте правило
• Карта архитектуры описывает несуществующие директории → почистите

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

Ссылки

• Спецификация: agents.md — Linux Foundation / Agentic AI Foundation
• GitHub-исследование: How to write a great agents.md (2 500 repos)
• OpenAI Codex docs: Custom instructions with AGENTS.md
• Пример: openai/codex: github.com/openai/codex/AGENTS.md
• Пример: vercel/next.js: github.com/vercel/next.js/AGENTS.md
• GitHub: 60 000+ репозиториев с AGENTS.md

По теме

• Статья: Codex, Саркис и два месяца боли: как я наконец-то собрал рабочую инфраструктуру ИИ-агентов
• Блог: Сделали pimenov.ai agent-ready: что реально внедрили и зачем
• База знаний: OpenAI Codex — облачный coding-агент для параллельной разработки

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