В AI Assisted Coding есть два столпа, на которых держится эффективность: тестирование и документация. О тестах поговорим в другой раз, а сегодня — о том, что часто считают скучной рутиной, но для AI это база.
Какие есть способы передачи информации о проекте в разработке? Чатики (Slack, Telegram Chats, Microsoft Teams), email письма, таск трекер, документация, память синьора. Для работы с AI нам нужен единый, надежный источник правды. И это — документация прямо в репозитории.
Да, можно прикрутить Confluence через MCP, но зачем усложнять? Когда доки лежат рядом с кодом, агент может обращаться к ним и даже обновлять, "не отходя от кассы".
Фундамент: Что должно быть в документации?
Думайте о документации как об онбординг-гайде для нового сотрудника. Минимум воды, максимум сути, чтобы любой — человек или AI — мог быстро влиться в проект. Обязательный минимум:
▪️ Архитектура: Общая схема проекта, как всё связано.
▪️ Стэк: Какие технологии и почему мы используем.
▪️ Запуск: Пошаговая инструкция по настройке окружения.
▪️Концепции: Объяснение ключевых или неочевидных решений, которые были приняты.
Наличие такого гайда колоссально экономит время и токены, избавляя AI от необходимости "додумывать" за вас.
Наличие такой документации колоссально сэкономит вам время при работе с AI агентами.
Rules для агента
С AI Coding Tools у нас появляется новая сущность — rules. Это конституция вашего проекта для AI.
По сути, это та же документация в Markdown, но предельно сжатая, состоящая из тезисов. Это «шпаргалка», которую агент держит перед глазами при каждом действии. (Сниппет из файла AGENTS.md одного из моих проектов я оставлю в комментах).
Как понять, что писать в доках, а что в правилах?
Очень просто. Представьте, что правила — это стикер на вашем мониторе с самой важной информацией. Они маленькие и всегда передаются в контекст запроса к LLM. А документация — это книжный шкаф, к которому агент обращается только по необходимости.
Искусство написания правил
Самое сложное — это выгрузить неявные знания из вашей головы в четкие инструкции. Вот несколько советов:
▪️ Не учите AI основам. Модели знают всё про React, Django, принципы SOLID и DRY. Ваша задача — описать, как именно вы их используете в своем проекте (например: "Используем функциональные компоненты и React Hooks", "Все эндпоинты следуют RESTful конвенции").
▪️ Правила — это живой документ. Они должны эволюционировать вместе с проектом. На старте они одни, для MVP — другие, в продакшене — третьи. Безжалостно удаляйте, обновляйте и поддерживайте их в актуальном состоянии.
▪️ Агент ошибается? Проверьте правила. Если AI систематически допускает одну и ту же ошибку, скорее всего, проблема не в вашем промпте, а в нехватке или неточности правил. Дополните их.
▪️ Описывайте "что", а не "как". Вместо того чтобы диктовать AI полную имплементацию, опишите бизнес-требования и конечную цель. Ваша задача — быть архитектором, а не каменщиком. Отдайте реализацию агенту.
И главное...
Не пишите правила и документацию вручную!
Опишите свои мысли в свободной форме и попросите AI-агента структурировать их в краткие и четкие инструкции. Он сделает это лучше и быстрее. А для небольших правил, относящихся к конкретному участку кода, отлично подойдут обычные комментарии прямо в файле.
#ai_coding@the_ai_architect
