🚀 Когда документация дружит с ИИ: объединение инструкций для агентов и инженерной документации

Робот-агент считывает код и пояснения прямо из инженерной документации на ноутбуке; стрелки показывают, как инструкции превращаются в рабочие фрагменты тестируемого кода ― визуализация удачного эксперимента по «соседству» инструкций и доков.

Современный мир разработки ПО уже сложно представить без искусственного интеллекта. AI-агенты активно помогают инженерам в рутинных задачах, будь то написание кода, тестирование или документирование проектов. Однако у этой помощи есть своя обратная сторона: необходимо поддерживать отдельный набор инструкций специально для агентов, что может привести к рассогласованию с основной инженерной документацией. Эксперимент, недавно проведённый с целью решить эту проблему, показал интересный подход — совместное размещение (colocation) инструкций для AI-агентов и основной инженерной документации.

📌 В чём суть проблемы?

Традиционно документация для разработчиков и инструкции для AI-агентов хранятся отдельно друг от друга. В итоге:

• 🔄 Появляется дублирование информации, которое неизбежно становится несогласованным.
• 📚 Документация становится менее эффективной и сложной в поддержке.
• 🤖 AI-агенты чаще допускают ошибки, так как их инструкции устаревают.

📖 Как работает метод совместного размещения (colocation)?

В рамках эксперимента, проведённого на проекте Pigweed, инструкции для AI-агентов были встроены прямо в основную инженерную документацию в виде комментариев, скрытых от глаз человека, но доступных для AI. Например, на странице с рекомендациями по созданию тестируемых примеров кода была добавлена скрытая часть:

.. Instructions for AI agents (e.g. Gemini CLI):
.. #. Follow the workflow described in :ref:`contributing-docs-quickstart-a`.
.. Do not use Option B.
.. #. Inspect the files in ``//pw_string/examples``. This is a working example
.. of the kind of code that you need to create.
.. #. Create the code example, unit test, and build targets. The first
.. iteration of the unit test should fail.
.. #. Run ``bazelisk test //...`` to verify that your new unit test fails.
.. #. Fix the unit test.
.. #. Run ``bazelisk test //...`` again and verify that the new unit test now
.. passes.

Эти инструкции невидимы для пользователя на веб-странице, но прекрасно «видны» AI-агенту, который сразу получает чёткий и подробный план действий.

🧪 Результаты эксперимента

На практике это выглядело так:

1. 👩‍💻 AI-агенту Gemini CLI было поручено создать рабочий и тестируемый пример кода.
2. 🛠️ Агент точно следовал встроенным инструкциям, выполнил задачу, создав сначала неработающий тест.
3. ✅ Затем агент исправил тест и подтвердил, что он проходит успешно.

Особенно примечательно, что агент обнаружил и сообщил об ошибке, которая была допущена самими авторами инструкции, что подтверждает внимательность и точность исполнения инструкций AI.

📊 Что показал эксперимент?

• ✅ Совместное размещение инструкций позволяет AI-агентам работать точнее, следуя чётким и релевантным указаниям.
• ✅ Сокращается риск того, что инструкции для агентов и инженеров разойдутся друг с другом.
• ✅ Вся информация всегда под рукой и обновляется синхронно с основной документацией.

Однако стоит учитывать, что эксперимент был проведён не в полностью изолированных условиях: в репозитории Pigweed уже существовал отдельный набор инструкций для агентов. Возможно, наиболее эффективным подходом станет комбинация: общие инструкции — отдельно, а целевые — встроены непосредственно в документацию.

💡 Личное мнение автора

Как разработчику, мне кажется такой подход чрезвычайно перспективным. Основная проблема работы с AI-ассистентами сегодня — потеря актуальности инструкций и, как следствие, ошибки и неточности в их работе. Встраивание инструкций непосредственно в инженерную документацию позволяет:

• 🧑‍🚀 Упростить процесс поддержки документации.
• 🤖 Повысить точность работы AI-агентов.
• 🌐 Сделать AI естественной частью рабочего процесса инженера, а не отдельным, требующим постоянного внимания элементом.

🛠️ Как это реализовано технически?

• Инструкции были интегрированы в документацию с помощью комментариев формата reStructuredText.
• AI-агенты (например, Gemini CLI) получили доступ к этой документации и могли интерпретировать скрытые комментарии как инструкции к действию.
• В качестве системы сборки и проверки кода использовался Bazel, что позволяло агенту автоматически тестировать написанные примеры и гарантировать их работоспособность.

🌟 Итог

Совместное размещение инструкций — это не просто интересный эксперимент, а потенциально важный шаг в сторону интеграции AI в процесс разработки. Технологии, которые позволяют AI быть максимально точным и эффективным помощником разработчика, в ближайшие годы станут стандартом. И чем раньше компании начнут внедрять подобные практики, тем легче и эффективнее будет их путь к идеальному симбиозу человека и AI.

🔗 Ссылки и материалы:

• Полный отчёт об эксперименте и его результатах
• Пример инструкции на pigweed.dev

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