Золотые правила разработки с ИИ

Хороший ИИ-ориентированный репозиторий должен быть устроен так, чтобы новая сессия сразу продолжила работу, а не начала восстанавливать историю проекта по коммитам, логам и обрывкам документации.

Независимо от стека, Evolution CMS, Laravel, Payload CMS, 1С или bash-автоматизации, стараюсь следовать нескольким простым правилам.

Первое. ADR.

Architecture Decision Records. Каждая запись фиксирует:

+ какую проблему решали;
+ какие варианты рассматривали;
+ почему выбрали определённый вариант.

Это сильно экономит время новой сессии. Она понимает, почему система устроена именно так, и не предлагает решение, которое уже забраковали неделю назад.

Второе. Документ с текущим состоянием проекта.

ADR отвечает на вопрос «почему мы так решили».

Условный CURRENT_STATE.md отвечает на вопросы: что сейчас работает, что сломано, что уже проверили, на чём остановились и что делать дальше.

Важное замечание: обновлять это состояние нужно каждый раз вместе с завершением текущей задачи. Устаревший CURRENT_STATE хуже, чем его отсутствие.

Третье. AGENTS.md должен быть картой, а не энциклопедией.

В AGENTS только основные правила и ссылки.

Работаешь с импортом — читай документацию импорта.
С API — правила API.
С инфраструктурой — документацию инфраструктуры.

Не нужно каждый раз скармливать агенту половину репозитория в виде 200к токенов на входе.

Четвёртое. Тесты.

Нашли плохой сценарий, добавили тест.

Если ошибку можно больше не объяснять словами, а превратить в строгое ограничение и проверять тестом, делайте это.

Тем более стоимость написания и поддержки тестов с ИИ сейчас сильно снизилась.

Получается определённая философия.

1. Чат (текущая сессия) — это расходник.
2. Репозиторий — память проекта.
3. AGENTS.md его карта, а не энциклопедия.
4. ADR — обоснование принятых решений.
5. CURRENT_STATE.md — память о текущем состоянии.
6. Тесты и проверки — рамки дозволенного.