Золотые правила разработки с ИИ
Хороший ИИ-ориентированный репозиторий должен быть устроен так, чтобы новая сессия сразу продолжила работу, а не начала восстанавливать историю проекта по коммитам, логам и обрывкам документации.
Независимо от стека, 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. Тесты и проверки — рамки дозволенного.
Привет, каким образом держишь рамки этих правил для модели? Скиллы, которые делают постобслуживание документации после завершения задачи или правила в корневом agent.md/claude.md?
С философией согласен полностью. У меня два скилла для этих целей: - Первый: обязывает агента вести внутри репо папку docs, где сохраняет результаты исследований, research, результатов e2e тестов. Внутри папки обновляемый index.md, который является картой раздела. Ключевая мысль, всё важное храним в артефактах а не контекстном окне
- Второй: пост-обслуживание всех внутренних артефактов (включая agent.md проекта) и wikillm. По результатам каждой завершенной задачей ищутся все связанные документы и документы, которые попадают в зону аффекта. Всё эти документы обновляются, вносится актуальная информация и обновляются связанные index.md
Может немного коряво, но я всегда уверен, что вся важная информация сохранена и не потеряется с закрытием терминала.
В начале каждой разработки есть скилл, который сначала собирает не только информацию из репозитория, но и ищет весь связанный контекст в других артефактах.
У меня немного иначе: скиллы для постобслуживания документации я пока не использую. Основная рамка держится на AGENTS.md + структуре документации + механических проверках.
В корне лежит общий AGENTS.md, а в отдельных подкаталогах свои. Например, рядом с конфигами правило про недопустимость дрейфа между сервером и репозиторием, рядом с историей, что она append-only и задним числом не переписывается.
Мне нравится принцип "правило как можно ближе к тому, что оно регулирует". Тогда модели не нужно помнить весь корневой AGENTS.md, когда она работает в конкретном домене.
Плюс есть карта документации: для конкретного типа задачи указано, что читать, а что не читать. status.md хранит только текущее состояние, блокеры и следующий шаг, история вычленяется отдельно. То есть примерно тот же принцип, что у тебя с index.md: важное живёт в репозитории, а не в контекстном окне.
И отдельно стараюсь всё, что можно, не оставлять на решение модели. Есть валидатор, который запускается в CI: проверяет размеры контекстных документов, ссылки, YAML, структуру, некоторые контракты между документами, отсутствие секретов и т. п. Если агент раздул AGENTS.md или сломал структуру документации получает ошибку валидатора и идёт доделывать.
То есть правило "обнови документацию вместе с кодом" есть в AGENTS.md, но часть его выполнения дополнительно проверяется машиной.
Скилл, который после задачи ищет всю "зону аффекта" по связанным документам идея понравилась. Буду внедрять у себя)
Спасибо за пост🔥
После прочтения решил проверить, а насколько у меня большой AGENTS.md, неужели он может сильно разрастаться.
Увидев AGENTS.md гермеса весом 171кб моему удивлению не было предела.
У меня похожая система, ее предложил сам opus когда я попросил организовать структуру документации для разработки. Из лучших практик. Пока все устраивает и мне удобно читать и есть лог принятых решений и не сильно сложно сопровождать.