Джордж Нуриджанян: лучшие практики написания CLAUDE.md и AGENTS.md

По мере того как AI-агенты для написания кода и инструменты автоматизации продуктовых процессов становятся частью повседневной работы, команды начинают понимать: то, как вы пишете инструкции для агентов, имеет не меньшее значение, чем выбор самих инструментов. Эта статья Джорджа Нуриджаняна, опубликованная в апреле 2026 года в его рассылке PM OS, доказывает, что интуитивное желание писать подробные контекстные файлы для AI-агентов приводит к обратному результату — и объясняет, что действительно работает.

Ключевое утверждение подкреплено исследованием ETH Zurich: автоматически сгенерированные файлы CLAUDE.md, которые были длинными и детальными, снизили показатель успешности задач на 3% и увеличили затраты на токены на 20% по сравнению с более короткими файлами, написанными вручную. Причина структурная: AI-агенты работают примерно со 100 доступными слотами для инструкций после учёта системных промптов. Чем длиннее контекстный файл, тем равномерно ниже точность выполнения всех инструкций — каждая дополнительная строка делает все остальные строки чуть менее надёжными.

Что включать

Нуриджанян выделяет небольшой набор элементов, которые реально улучшают работу агентов. Чёткое описание проекта и целевых пользователей. Точный технологический стек с конкретными версиями. Команды CLI для типовых задач — написанные точно, а не описательно. Соглашения, которые линтер не поймает: например, правила именования или порядок вызова API. И жёсткие ограничения, сформулированные как явные запреты (конструкции «NEVER»), которые агенты воспринимают как сигналы с более высоким приоритетом.

Что исключать

Дерево директорий, автогенерируемый контент и полная документация по API не должны появляться в файле CLAUDE.md. Если документация существует в другом месте, дайте на неё ссылку. Расплывчатые инструкции по персоне («вы — опытный PM-ассистент») добавляют шум без улучшения результатов. Правила, которые линтер уже применяет, избыточны — агенту не нужно знать то, чем уже управляет инструментальная цепочка.

Структурные рекомендации

Рекомендованный корневой файл CLAUDE.md не должен превышать 80 строк. Для более крупных кодовых баз или проектов с несколькими доменами, специфические инструкции лучше размещать в поддиректориях .claude/rules/, а не раздувать корневой файл. Статья также рекомендует писать AGENTS.md как основной источник информации и импортировать его в CLAUDE.md, чтобы инструкции для агентов оставались отдельными от документации, которую читают люди.

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

Для кого это материал

PM, которые используют Claude Code, Cursor или аналогичные агентные инструменты в собственной работе — для документации, синтеза исследований, написания PRD или автоматизации процессов — получат от этого немедленную пользу. Технические руководители, стандартизирующие взаимодействие продуктовой команды с AI-агентами, также найдут структурные рекомендации полезными. Принципы применимы к различным инструментам, а не только к экосистеме Anthropic.