🎯 О чём этот конспект: Разбор смены парадигмы в разработке: переход от документации для людей к созданию «когнитивной среды» для 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. Добавьте проверку в линтер или тесты (если возможно).

FAQ

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