Представьте: вы даёте джуну задачу без контекста. Без документации, без code review, без архитектурных решений. Что получите? Хаос. С AI-агентами — та же истори

Когда я начал работать с Claude Code в production-проектах, первое время результат был посредственным. AI генерировал код, который "работал", но не вписывался в архитектуру. Нарушал границы модулей, игнорировал наши конвенции, создавал дублирование.

Решение оказалось неожиданно простым: CLAUDE.md — markdown-файл в корне проекта, который описывает архитектуру для AI-агента.

Что внутри моего CLAUDE.md:

1. Архитектурные границы. Какие модули существуют, как они связаны, какие зависимости допустимы. AI читает это и перестаёт импортировать domain-логику в presentation layer.

2. Конвенции кода. Naming, структура файлов, паттерны обработки ошибок. Вместо "исправь после генерации" — AI сразу пишет по стандартам команды.

3. Бизнес-контекст. Почему выбрали Event Sourcing, а не CRUD. Почему этот сервис stateless. AI перестаёт предлагать "оптимизации", которые ломают архитектурные решения.

4. Запреты. Не используй ORM X, не создавай God-объекты, не добавляй зависимости без обоснования. Работает как guardrails.

Результат: AI-агент с CLAUDE.md генерирует код, который проходит code review с первого раза в 80% случаев. Без файла — в 30%.

Ирония в том, что CLAUDE.md — это, по сути, то, что хороший тимлид делает для новых разработчиков: передаёт контекст, устанавливает правила, объясняет "почему". Только тимлид делает это в разговорах, а для AI нужен файл.

Главный инсайт: качество AI-генерации на 70% зависит не от модели, а от контекста, который вы ей даёте. CLAUDE.md — это ваш способ дать этот контекст системно.

А вы документируете архитектуру для AI-агентов? Или всё ещё надеетесь, что "модель и так разберётся"?