VibeCoderzVibeCoderz

Конспекты

Смарт-конспекты YouTube-видео — ключевые идеи и инсайты без необходимости смотреть часовые ролики

Все конспекты
📝 Конспект2026/03/03

Agent-First Documentation: Как превратить документацию в интерфейс управления AI-агентами

Пошаговое руководство по созданию когнитивной среды для AI-агентов. Как писать Agent.md, .cursorrules и настраивать иерархию истины в проекте.

Содержание (6)+
📝

Смарт-конспект

🎯 О чём этот конспект: Разбор смены парадигмы в разработке: переход от документации для людей к созданию «когнитивной среды» для AI-агентов (Cursor, Claude Code и др.). Рассматривается структура проекта, где документация становится набором жестких политик и ограничений, а не просто описанием кода.

👤 Кому будет полезно: Вайбкодерам и инженерам, использующим AI-агентов для написания кода, которые сталкиваются с тем, что агент «галлюцинирует», нарушает архитектуру или игнорирует стиль проекта.

✨ Что получите: Пошаговую иерархию «единого источника истины» (Single Source of Truth), шаблон файла политик и чек-лист для проверки репозитория на готовность к работе с агентами (Agent-Ready).

1. Смена парадигмы: Документация как инструмент управления

Контекст: Раньше документация была нужна для онбординга людей и объяснения логики проекта спустя время. В мире, где код пишут агенты, её роль меняется на 180 градусов. Теперь это интерфейс управления поведением модели. Если документация расплывчата, агент оптимизирует код под локальный контекст (то, что увидел первым), нарушает паттерны и создает параллельные реализации. Мы переходим от роли «написателя кода» к роли «проектировщика когнитивного пространства».

Выгода: Снижение стоимости разработки (меньше лишних итераций и токенов), повышение стабильности кода и предсказуемости поведения агента.

Как применить:

  • Шаг 1: Разделите контуры — Перестаньте смешивать инструкции для людей и агентов. Файл README.md оставьте для людей (нарратив, мотивация), а для агентов создайте слой политик.
  • Шаг 2: Установите иерархию истины — Определите, что является главным. Высший приоритет — автоматические проверки, затем файлы политик (.cursorrules, agent.md), затем архитектурные решения.

2. Иерархия Single Source of Truth (SSoT)

Контекст: «Единый источник истины» — это не один файл, а многослойная структура. Чем ниже уровень, тем больше деталей; чем выше — тем жестче ограничения. Ошибка многих — пытаться запихнуть всё в один промпт или один agent.md. Это перегружает контекст и снижает качество работы модели.

Выгода: Агент четко понимает приоритеты и не тратит бюджет на «исследование» всего репозитория, если есть прямой указатель.

Как применить:

  • Уровень 1: Enforcement (Принуждение) — [CI/CD, Linters] — Настройте автоматические проверки. Если правило нельзя проверить скриптом, агент рано или поздно его нарушит.
  • Уровень 2: Policy Layer (Политики) — [Agent.md / .cursorrules] — Создайте «шлюз», который содержит только критические ограничения и ссылки на другие документы.
  • Уровень 3: Architecture (Архитектура) — [ADR - Architecture Decision Records] — Фиксируйте изменения архитектуры в отдельных файлах.
  • Уровень 4: Operations (Операционка) — [Guides] — Пошаговые инструкции по деплою, дебагу и тестированию.
  • Уровень 5: Examples (Примеры) — [Reference Code] — Эталонные примеры кода, которые служат каноном.

3. Создание Policy Layer (Agent.md / .cursorrules)

Контекст: Файл политик — это контракт поведения. Он не должен объяснять проект, он должен диктовать правила. Исследования показывают, что огромные файлы, сгенерированные AI, снижают успех на 4% и увеличивают расход токенов на 20%. Лучший файл политик — короткий, написанный или вычитанный человеком.

Выгода: Агент работает быстрее и точнее, не «галлюцинируя» в рамках дозволенного.

Структура идеального Agent.md:

  1. Цель: 1-2 строчки, что делает система.
  2. Тулинг: Конкретные команды для тестов и линтеров.
  3. Архитектурные рамки: Ссылки на каноны.
  4. Безопасность: Правила работы с секретами и критическими зонами.
  5. Definition of Done: Критерии завершенности задачи.

Пример жестких инструкций (для моделей 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.

4. Принцип «Agent-First» в написании документации

Контекст: Пишите документацию так, как будто это системный промпт. Избегайте «человеческих» мягких формулировок. Фразы «желательно придерживаться» или «по возможности избегайте» для агента — это шум или разрешение игнорировать правило.

Выгода: Исключение двусмысленности и неверной интерпретации команд.

Как применить:

  • Шаг 1: Используйте императив — Замените «рекомендуется использовать» на «MUST USE».
  • Шаг 2: Указывайте конкретные пути — Вместо «в соответствующих папках» пишите «in /src/components/ui».
  • Шаг 3: Создавайте эталонные примеры — Вместо описания стиля теста дайте один идеальный файл.

Пример трансформации промпта в документации: Плохо: «Старайтесь писать тесты аккуратно». Хорошо:

 
---
 
## Testing Standard
Every new function MUST have a unit test in the `/tests` directory following this pattern:
[Example Code Block]

5. Реактивное обновление: Живая документация

Контекст: Документация не должна быть мертвым грузом. В Agent-First подходе она обновляется реактивно. Если агент совершил ошибку, не нужно просто её исправлять. Нужно зафиксировать это в системе.

Выгода: Ошибка не повторится дважды. Проект становится самообучающейся системой.

Алгоритм действий при ошибке агента:

  1. Сформулируйте короткое правило, запрещающее эту ошибку.
  2. Добавьте пример «как надо» в документацию.
  3. Добавьте проверку в линтер или тесты (если возможно).

Agent-First Documentation: ответы на частые вопросы

В: Почему нельзя просто использовать один большой файл .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

Редактор конспекта

Максим Наговицын

Маркетинг-стратег, IT-предприниматель, ментор по вайбкодингу

10+ лет в маркетинге, 300+ клиентских проектов: сайты, реклама, боты. Создатель GoBanana (228K+ пользователей, 11.6 млн ₽ выручки) и VibeCoderz. Делаю AI-продукты сам через Claude Code, Cursor, Windsurf и консультирую тех, кто хочет так же.

Об авторе →
Все конспекты

Источник

КаналVibeCoderz
Конспект добавлен2026/03/03
Смотреть на YouTube

Инструменты из конспекта

Похожие конспекты

📝 Конспект

Создание кроссплатформенного AI-ассистента за 1 день: Эмуляторы, скриншот-верификация и автомердж PR

Пошаговый разбор создания open-source AI-бота Ricazo: архитектурная изоляция, тестирование через эмуляторы API, скриншоты и автономный CI/CD.

2026/11/02
📝 Конспект

Анализ батча Y Combinator: Куда идут инвестиции в AI и как создавать прибыльные стартапы

Разбор 230 AI-стартапов батча Y Combinator: смерть B2C-оберток, переход к Service-as-a-Software, дистилляция моделей и инфраструктура агентов.

2026/11/02
📝 Конспект

Staret: Как запустить автономную команду AI-агентов в геймифицированной Agent OS

Пошаговый гид по Staret: запуск команды AI-агентов в пиксельном офисе, подключение ChatGPT и Grok без API, долгосрочная память и автономия.

2026/11/02
📝 Конспект

Eagle Lite: Локальный AI-браузер для Claude Code, Codex и автоматизации задач

Гид по настройке и использованию Eagle Lite: локального AI-браузера для Claude Code, Cursor и Codex. Автоматизация веб-задач и Bug Bounty.

2026/11/02
📝 Конспект

AI-скилл для анализа видео в Cursor и Claude Code: Как заставить нейросеть смотреть экран через Gemini API

Как бесплатно научить AI-агентов в Cursor и Claude Code смотреть видео с экрана через Gemini API: промпты, таймкоды и дебаг багов.

2026/11/02
📝 Конспект

ИИ-агенты от А до Я: Полное руководство по настройке, архитектуре и автоматизации рутины

Полный практический гид по ИИ-агентам: связка LLM и Harness, настройка agents.md, навыки в .agents/skills, выбор между подпиской и API.

2026/11/02

Читать далее

📢 Новость

MiniMax M2: убийца Claude Sonnet для Cursor и MCP-агентов?

Китайский стартап MiniMax представил модель M2, оптимизированную специально для кодинга и работы агентов. Она в 2 раза быстрее Sonnet 3.5 и стоит в 12 раз дешевле.

2026/06/01
📢 Новость

Grok V9-Medium: 1.5 трлн параметров и эксклюзивные данные Cursor

xAI представила Grok V9-Medium, обученную на реальных воркфлоу пользователей Cursor. Илон Маск готовит поглощение Anysphere за $60 млрд.

2026/05/30
📢 Новость

Grok V9-Medium: 1.5 триллиона параметров и обучение на данных Cursor

Илон Маск анонсировал новую модель Grok V9-Medium, обученную на реальных воркфлоу из Cursor. Релиз ожидается в середине июня 2026 года.

2026/05/28
📄 Статья

Qwen 3.8 Max 2026 обзор, доступ и как запустить локально

Qwen 3.8 Max стала первой моделью линейки Max, у которой Alibaba открыла веса. 12 августа 2026 года чекпоинт на 2,4 трлн параметров появился на Hugging Face, и скачать его может любой. А вот запустить дома не выйдет: даже 1-битная версия весит 397 ГБ…

2026/10/1212 мин
📄 Статья

GLM 5.3 Flash и GLM 5.3 в 2026, что нового у Z.ai и какую взять2222

GLM 5.3 Flash от Z.ai (бывшая Zhipu AI) вышла 26 августа 2026 и сразу стала самой дешевой моделью своего уровня для кода. Внутри 320 млрд параметров, из которых работают 18 млрд, открытая лицензия MIT, контекст 1 млн токенов и вход для картинок и вид…

2026/10/1211 мин
📄 Статья

Gemini 3.8 Flash в 2026 году, что умеет новая модель Google

Gemini 3.8 Flash это быстрая и дешевая модель Google, которая вышла 2 сентября 2026 года и сразу стала моделью по умолчанию для агента в Antigravity. Отдельной Gemini 3.8 Pro пока не существует, поэтому запросы «gemini 3.8 pro» и «gemini 3.8 flash pr…

2026/10/1214 мин