Загрузка...
Смарт-конспекты YouTube-видео — ключевые идеи и инсайты без необходимости смотреть часовые ролики
Пошаговое руководство по созданию когнитивной среды для AI-агентов. Как писать Agent.md, .cursorrules и настраивать иерархию истины в проекте.
🎯 О чём этот конспект: Разбор смены парадигмы в разработке: переход от документации для людей к созданию «когнитивной среды» для AI-агентов (Cursor, Claude Code и др.). Рассматривается структура проекта, где документация становится набором жестких политик и ограничений, а не просто описанием кода.
👤 Кому будет полезно: Вайбкодерам и инженерам, использующим AI-агентов для написания кода, которые сталкиваются с тем, что агент «галлюцинирует», нарушает архитектуру или игнорирует стиль проекта.
✨ Что получите: Пошаговую иерархию «единого источника истины» (Single Source of Truth), шаблон файла политик и чек-лист для проверки репозитория на готовность к работе с агентами (Agent-Ready).
Контекст: Раньше документация была нужна для онбординга людей и объяснения логики проекта спустя время. В мире, где код пишут агенты, её роль меняется на 180 градусов. Теперь это интерфейс управления поведением модели. Если документация расплывчата, агент оптимизирует код под локальный контекст (то, что увидел первым), нарушает паттерны и создает параллельные реализации. Мы переходим от роли «написателя кода» к роли «проектировщика когнитивного пространства».
Выгода: Снижение стоимости разработки (меньше лишних итераций и токенов), повышение стабильности кода и предсказуемости поведения агента.
Как применить:
CursorREADME.md оставьте для людей (нарратив, мотивация), а для агентов создайте слой политик..cursorrules, agent.md), затем архитектурные решения.Контекст: «Единый источник истины» — это не один файл, а многослойная структура. Чем ниже уровень, тем больше деталей; чем выше — тем жестче ограничения. Ошибка многих — пытаться запихнуть всё в один промпт или один agent.md. Это перегружает контекст и снижает качество работы модели.
Выгода: Агент четко понимает приоритеты и не тратит бюджет на «исследование» всего репозитория, если есть прямой указатель.
Как применить:
Контекст: Файл политик — это контракт поведения. Он не должен объяснять проект, он должен диктовать правила. Исследования показывают, что огромные файлы, сгенерированные AI, снижают успех на 4% и увеличивают расход токенов на 20%. Лучший файл политик — короткий, написанный или вычитанный человеком.
Выгода: Агент работает быстрее и точнее, не «галлюцинируя» в рамках дозволенного.
Структура идеального Agent.md:
Пример жестких инструкций (для моделей OpenAI):
# CRITICAL POLICIES
- MUST NOT modify files in `/core` without updating `/tests`.
- ALWAYS run `npm run lint:fix` before completing a task.
- NEVER add new dependencies to `package.json` without human approval.
- ONLY use Tailwind classes for styling; NO custom CSS in components.Контекст: Пишите документацию так, как будто это системный промпт. Избегайте «человеческих» мягких формулировок. Фразы «желательно придерживаться» или «по возможности избегайте» для агента — это шум или разрешение игнорировать правило.
Выгода: Исключение двусмысленности и неверной интерпретации команд.
Как применить:
/src/components/ui».Пример трансформации промпта в документации: Плохо: «Старайтесь писать тесты аккуратно». Хорошо:
---
## Testing Standard
Every new function MUST have a unit test in the `/tests` directory following this pattern:
[Example Code Block]Контекст: Документация не должна быть мертвым грузом. В Agent-First подходе она обновляется реактивно. Если агент совершил ошибку, не нужно просто её исправлять. Нужно зафиксировать это в системе.
Выгода: Ошибка не повторится дважды. Проект становится самообучающейся системой.
Алгоритм действий при ошибке агента:
В: Почему нельзя просто использовать один большой файл .cursorrules?
О: Большие файлы (более 500 строк) создают «архитектурный шум». Модель начинает путаться в приоритетах, тратит больше токенов и чаще ошибается. Используйте .cursorrules как индекс (оглавление) со ссылками на другие MD-файлы.
В: Работают ли файлы Agent.md одинаково для всех моделей?
О: Нет. Модели OpenAI (GPT-4o) лучше понимают жесткие запреты и императивы. Модели Anthropic (Claude) требуют более дескриптивного подхода: им нужно объяснять почему введено ограничение, иначе они могут начать задавать лишние вопросы.
В: Нужно ли писать документацию для агентов вручную?
О: Можно генерировать черновик с помощью AI, но человек обязан его вычитать. Важно удалить «воду», философские рассуждения и оставить только проверяемые факты и команды.
В: Что делать, если правило нельзя проверить автоматически?
О: Такое правило с большой вероятностью будет проигнорировано агентом в долгосрочной перспективе. Постарайтесь формализовать его через чек-листы в Definition of Done или через агентные проверки (когда один агент проверяет работу другого).
В: Как понять, что мой проект готов к работе с AI-агентами (Agent-Ready)?
О: Проверьте по чек-листу: есть ли явная иерархия документов, отделены ли политики от README, прописаны ли конкретные команды запуска тестов и есть ли эталонные примеры кода для каждой типовой задачи.
Конспект создан на основе видео «Документация для агентов: Как управлять AI-разработкой через контекст» канала [VibeCoderz / Денис]. Все права на оригинальный материал принадлежат авторам. Источник: https://youtu.be/cNsPzQdg7pA