AGENTS.md, Skills и память проекта: что для чего нужно

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

Три сущности решают разные проблемы. AGENTS.md задаёт постоянные рабочие договорённости. Skill описывает повторяемый способ выполнить определённую работу. Память проекта сохраняет решения и опыт, которые должны повлиять на будущие циклы. Они связаны, но не заменяют друг друга.

Коротко

AGENTS.md отвечает: «По каким постоянным правилам здесь работать?»
Skill отвечает: «Как надёжно выполнить этот тип работы?»
Память отвечает: «Что мы уже узнали и не должны потерять?»
Текущее состояние не равно памяти: оно показывает, где работа находится сейчас.
Чем точнее разделены роли файлов, тем меньше повторных объяснений и скрытых противоречий.

AGENTS.md — договорённости рабочей среды

Официальная документация OpenAI описывает AGENTS.md как файл дополнительных инструкций и контекста проекта. Codex читает такие файлы до начала работы и может собирать их от общих правил к более локальным. Инструкции ближе к текущей папке уточняют правила верхнего уровня.

В AGENTS.md уместно закреплять:

границы ответственности;
источники правды;
обязательные проверки;
стандарты изменения файлов;
правила безопасности;
порядок согласования внешних действий;
принятые способы работы в конкретной части проекта.

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

Чего не стоит класть в AGENTS.md

Главный риск — превратить файл правил в архив всего важного. Там плохо живут:

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

Если правило применимо только к одному типу работы, ему может быть место в Skill. Если информация изменилась сегодня, это состояние. Если вывод накоплен из нескольких циклов, это память.

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

Skill — воспроизводимый способ действия

OpenAI определяет Skills как формат повторяемых рабочих сценариев. Skill содержит обязательный SKILL.md с инструкциями и при необходимости может включать скрипты, справочные материалы и шаблоны. Codex способен подключить Skill по явному запросу или выбрать его, когда описание соответствует задаче.

Skill нужен, когда вы уже поняли, как выполняется определённая работа, и хотите не изобретать процесс заново. Например:

подготовить коммерческое предложение по утверждённому стандарту;
проверить статью перед передачей сайту;
собрать отчёт из набора выгрузок;
провести ревью документа;
создать презентацию по бренд-системе;
обработать запись встречи и распределить решения.

Skill — это не хранилище общей мудрости. Это ограниченная способность с понятным условием применения, последовательностью, ресурсами и результатом.

Хороший Skill начинается после живого цикла

Есть соблазн сначала написать универсальную процедуру, а потом искать ей применение. Обычно надёжнее обратный порядок:

реальная работа
-> наблюдение шагов
-> ошибки и исключения
-> стабильный способ
-> Skill
-> повторная проверка

До живого выполнения мы не знаем, где не хватает данных, в какой точке нужен человек и что ломается на исключениях. Поэтому ранний Skill часто закрепляет не зрелый процесс, а красивую гипотезу.

В модели «Цифровой зрелости» Skill не является отдельным шестым слоем функции. Он фиксирует удачный сценарий прежде всего на пересечении задания и цикла, но всё равно опирается на контекст, инструменты и состояние. Устройство пяти слоёв объясняется в материале о цифровой зрелости в эпоху ИИ.

Память — отобранный опыт проекта

Память нужна не для сохранения всего прошлого. Её задача — удержать то, что должно изменить будущую работу.

В память стоит переносить:

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

Полезная запись памяти отвечает на три вопроса: что произошло, чему это научило систему и где вывод должен применяться дальше.

Например: «Ежедневная проверка маркетинга выбрала клиентскую отгрузку как собственный маркетинговый результат. После разбора закреплено правило владения: клиентская работа относится к продукту, а в маркетинг попадает только как разрешённый кейс или рыночный сигнал». Это не просто история. Вывод меняет следующие решения.

Состояние — это не память

У проекта может быть прекрасная память и устаревшая текущая картина. Поэтому нужен отдельный state-файл или краткая контрольная поверхность.

Состояние отвечает на вопросы:

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

Память накапливается медленно. Состояние может меняться каждый день. Если смешать их, временный приоритет станет вечным правилом, а важный принцип утонет в ленте статусов.

Как эти слои работают вместе

Представим редакционную функцию.

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

Skill описывает производственный сценарий: собрать поисковое намерение, подготовить доказательную базу, написать структуру, проверить один H1, ссылки, метаданные и заглушки, затем передать Markdown агенту сайта.

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

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

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

Минимальная структура проекта

Для начала достаточно простой схемы:

AGENTS.md              — постоянные правила
README.md              — карта проекта и точка входа
Current State.md       — текущая реальность и следующий шаг
Memory.md              — отобранные выводы
.agents/skills/...     — повторяемые процедуры
Sources/               — канонические материалы
Working/               — черновики
Outputs/               — готовые результаты

Конкретные названия можно изменить. Важнее сохранить семантические роли. Подробный способ организации описан в статье как собрать рабочий контекст для Codex.

Пять ошибок при настройке

1. Всё объявлено источником правды

Если у каждого документа одинаковый статус, агенту приходится угадывать. Нужны приоритет и владелец.

2. Skill написан как должностная инструкция «делай всё»

Хорошая процедура ограничена одним классом результата. Универсальность без границ снижает проверяемость.

3. Память копирует журнал событий

Сохранять нужно вывод, а не каждый шаг. Сырые события могут жить в логе.

4. Состояние не обновляется

Тогда агент действует в уже несуществующей реальности, даже если прочитал все правила правильно.

5. Инструкции заменяют проверку

Ни один файл не гарантирует качество. Результат нужно проверять по критериям, а высокорисковые действия — оставлять за человеком.

Как понять, что архитектура работает

Дайте новому потоку Codex задачу без пересказа всей истории и проверьте:

назвал ли он правильную цель;
нашёл ли актуальные источники;
применил ли нужную процедуру;
сохранил ли результат в правильном месте;
не нарушил ли границы;
обновил ли состояние только при реальном изменении;
может ли объяснить, чем подтверждается готовность.

Такой тест показывает качество системы лучше, чем длина инструкций. Он переводит работу от разговора к повторяемой функции.

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

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

Автор: Александр Шаров, основатель x10sion и автор практикума «Цифровая зрелость».