раздел 00

Системные документы агентного подхода

Когда ты пишешь код с AI-агентом (Claude Code, Cursor, Codex), его поведение задают не только твои сообщения в чате. Рядом лежат специальные файлы, которые агент подхватывает сам: инструкции по проекту, навыки, правила, память, команды, настройки прав. Ты их один раз написал - и агент дальше действует с учётом этого, без напоминаний.

Это и есть системные документы агента. Мануал разбирает каждый: что это, зачем нужно и как написать так, чтобы агент делал то, что нужно.

Системный документ - это способ один раз объяснить агенту правила игры, вместо того чтобы повторять их в каждом чате. Хорошо написанные файлы экономят тебе десятки одинаковых сообщений.

Зачем агент их вообще читает

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

Без них ты каждый раз объясняешь заново: где запускать тесты, почему нельзя трогать вот этот модуль, как оформлять коммиты. С ними - агент уже в курсе.

Карта категорий

Системные файлы делятся на несколько групп по роли. Вот они целиком - дальше каждой посвящена отдельная глава.

Инструкции проекта
AGENTS.md и CLAUDE.md - команды, стек, стиль, ограничения, критерии готовности. Главный файл про проект.
Навыки (skills)
Готовые способности под типовые задачи. Агент сам подключает нужный навык по его описанию.
Правила (rules)
Точечные условные подсказки, часто привязаны к типам файлов и областям кода.
Память (memory)
Устойчивые факты между сессиями: решения, договорённости, накопленный фидбэк.
Слэш-команды
Переиспользуемые промпты и процедуры, которые вызываешь одной командой.
Субагенты и MCP
Отдельные роли-помощники и подключение внешних инструментов к агенту.
Настройки (settings)
Права доступа, выбор модели, переменные окружения. Что агенту можно, а что нельзя.
Хуки (hooks)
Скрипты, которые запускаются автоматически на события. Это не контекст, а автоматизация.

Иерархия загрузки: где что лежит

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

  • Глобальные - в домашней папке (например, каталог настроек агента у тебя в системе). Действуют во всех проектах сразу: твой личный стиль, общие привычки.
  • Проектные - в корне репозитория. Действуют в этом проекте: команды сборки, стек, договорённости команды.
  • Вложенные - в подпапках проекта. Действуют только внутри своей папки: например, особые правила для фронтенда в его каталоге.

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

Главное разграничение: контекст против автоматизации

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

Почти все системные файлы - это контекст. Агент читает их как знание и учитывает, когда думает и действует. Инструкции, навыки, правила, память - всё это текст, который агент держит в голове. Он может им следовать точно, а может отступить, если задача требует другого.

Хуки - это автоматизация. Это не текст для чтения, а скрипты, которые система запускает сама на определённые события: перед вызовом инструмента, после правки файла, при остановке агента. Хук выполняется всегда и одинаково, агент на него не влияет.

Контекст-документы
Инструкции, навыки, правила, память. Агент читает как знание и учитывает. Может следовать, может гибко отступить под задачу.
Автоматизация (хуки)
Скрипты на события. Выполняются системой всегда и детерминированно. Не текст для чтения, а действие по триггеру.

Путать эти две вещи - частая ошибка. Если тебе нужно, чтобы форматтер прогонялся строго после каждой правки, - это работа для хука, а не для строчки в инструкции (её агент может забыть применить). А если нужно объяснить стиль кода - это контекст, хук тут ни при чём. Подробно про хуки - в главе 08.