Transcription
Добро пожаловать. Сегодня я собираюсь показать вам, как вы можете использовать один небольшой файл markdown, чтобы исправить самую большую проблему вашего AI-кодирующего агента. Меня зовут Ян. Я разработчик Agent Zero и Space Agent. И сегодня я покажу вам, как правильно использовать Docs. Это чрезвычайно просто. Никакой установки, никаких требований. И самое лучшее то, что это действительно решает проблему. Итак, в чем же проблема? Очевидно, это надежность AI-кодирующих агентов, и мы все знаем симптомы. Вы даете своему AI-агенту задачу. Он выполнит задачу, но в неправильном месте, нарушая ваши соглашения, дублируя функциональность вместо расширения функции, которая могла бы состоять всего из одной строки добавления. Он создаст совершенно новый вспомогательный модуль и так далее. Ваша кодовая база раздуется, и это сделает вещи еще хуже в будущем. И вы знаете, чем это заканчивается, верно? Бесконечные циклы отладки, исправление одного ломает другое, ваш агент сбит с толку всем кодом и так далее. Итак, теперь я покажу вам, что такое Docs на самом деле, почему это так просто и почему это работает так хорошо, почему мы его разработали и как вы можете использовать его в своем проекте. Итак, сначала нам нужно определить, в чем здесь реальная проблема. Проблема не в интеллекте, а в осведомленности о контексте. Потому что ваш агент уже достаточно умен, ваш LLM достаточно умен, чтобы выполнять любую работу по программированию лучше, чем вы. Но где он терпит неудачу, так это в поддержании больших кодовых баз, потому что он не видит за углом. Он не знает контекста всей вашей кодовой базы. И именно поэтому он допускает эти простые ошибки, потому что он просто не видит общей картины. И добавление большего количества токенов не является решением. Вопрос не в том, как дать ему больше контекста. Вопрос в том, как дать ему ровно столько контекста, сколько ему нужно. Не больше, не меньше, минимальный контекст, необходимый для внесения минимальных изменений, и все. Теперь, чтобы понять, почему я разработал Docs, нам нужно взглянуть на Space Agent, потому что именно там все началось. Space Agent, если вы не знаете, что это такое, это AI-агент, который работает полностью в браузере. Он может выполнять код. Он может генерировать свои собственные пользовательские интерфейсы на лету. Он может общаться с внешними сервисами. Вы говорите ему построить вам что-то, он построит это на лету прямо в браузере. И у него есть множество продвинутых функций, таких как управление пользователями, группы. Он расширяем во многих-многих отношениях. У него большая кодовая база, много слоев, много концепций, много классных функций, таких как путешествие во времени, и он был полностью разработан AI. Я не написал ни строчки кода в этом проекте. И мне потребовалось около 3 недель, чтобы полностью разработать, довести до ума и опубликовать это. И поэтому с самого начала я знал, что не смогу писать код здесь. Это невозможно в 2026 году. Вам нужна команда агентов, которые будут делать это за вас, но вам нужно, чтобы они делали это надежно и писали качественный код, поддерживали правильные принципы и лучшие практики и так далее. И поэтому первое, что я сделал в Space Agent, это создал файл agents.md, где тогда это еще не называлось Docs framework. Это был просто первый прототип самодокументирующегося фреймворка, построенного специально для проекта Space Agent. Но это было в основном то, чем является Docs framework сейчас. Он объяснял этому агенту читать документацию перед редактированием, обновлять документацию после редактирования, поддерживать документацию в иерархии, соответствующей кодовой базе, и как должна выглядеть документация. Итак, как мы говорим здесь, Docs — это самодокументирующийся фреймворк agents.mmd. Главное отличие здесь в том, что это не один файл agents.mmd. Это не документация, которая отделена от кодовой базы где-то. То, к чему мы привыкли, многие проекты имеют свою документацию в вики где-то или в отдельной папке. Здесь мы тесно связываем документацию с кодовой базой. И я могу показать вам это здесь. Это кодовая база Agent Zero, например. Это очень большой проект, очень большая кодовая база, очень глубокая, и все начинается с файла agents.mmd верхнего уровня. Здесь у нас есть наши оригинальные инструкции Agent Zero, и где-то здесь начинается Docs framework, что является одной из его прелестей. Вы можете просто взять markdown из репозитория GitHub, скопировать и вставить его в свой существующий agents.mmd. Это не испортит ваши существующие инструкции. Это просто добавит, скажем так, ответственность вашему агенту за документацию. Теперь агент знает, что ему нужно сканировать иерархию файлов agents.mmd, потому что каждый agents.mmd создается в каждой подпапке по всей кодовой базе, за исключением некоторых временных файлов и мусора и т. д. И каждый файл agents.mmd отвечает за одну область, одну папку, но содержит дочерний индекс документов. И мы сейчас находимся в agents.mmd верхнего уровня. И здесь у нас есть подпапки agents, API, configuration, docker и т. д. Каждая из них имеет свои файлы agents.md внутри, которые документируют эту конкретную область. И, например, в agents мы снова найдем дочерний индекс документов в конце, документирующий отдельные агенты внутри системы. И почему эта древовидная структура так важна, так это то, что таким образом агент всегда может выбрать самый быстрый и прямой путь к месту, где ему нужно внести изменения. Так что, если я скажу агенту, создай для меня API-эндпоинт, прямо в файле agents.mmd верхнего уровня, который агент может видеть все время, он сможет увидеть, что есть документация для API-эндпоинтов, вот краткое описание: http API handlers и точки входа для обработчиков websocket. Агент откроет этот файл, прочитает о назначении, владении, локальных контрактах, aka правилах, руководстве по работе, как тестировать и проверять, чтобы агент мог быстро перейти к соответствующему месту, внести минимальные изменения и, самое главное, после любого изменения обновить файлы документации, что сохранит документацию в синхронизации с фактической кодовой базой. И я знаю, что это может показаться простой концепцией. На самом деле так оно и есть. И может быть трудно поверить, что это действительно приносит какую-либо реальную пользу AI-агентам. Но разница между входом и выходом, я имею в виду размер добавления к вашей кодовой базе, отсутствие необходимости в установке, отсутствие ручной работы, и выход с точки зрения качества кода и эффективности агента настолько непропорционален, что мы были вынуждены выпустить это как отдельный продукт. Я говорю продукт, но, конечно, это open source, просто скопируйте и вставьте, и мы, вероятно, лучше всего увидим это на самом Space Agent, который был полностью закодирован AI. Мы можем взглянуть на agents.md верхнего уровня, и он укажет нам на команды фронтенд-приложения, упаковку, сервер, тесты. Мы можем взглянуть на документацию сервера, например. И это укажет нам дальше на API-эндпоинты, задания, библиотеку, страницы, роутер, рантайм. Вы поняли. Все тщательно документировано. Агент обновляет всю соответствующую документацию, не только ближайший файл agents.md к месту редактирования агентом, но и родительские, если это уместно. Так что, если мы изменим что-то о концепции, если я скажу агенту, что хочу, чтобы он использовал другие практики кодирования, другой стиль, форматирование, что угодно, он сможет обновить это в родительских файлах agents.mmd. И это будет отражено везде вниз по дереву, потому что, когда агент перемещается по иерархии документации сверху вниз, он будет держать в окне контекста всю информацию и инструкции из родительских файлов agents.mmd и все подробные инструкции из конца дерева. Так что, когда мы доберемся достаточно глубоко, например, до, я не знаю, может быть, заданий, здесь должны быть более конкретные инструкции, имена функций и т. д. к текущей проблеме в этой папке, но в родительских, например, в сервере, у нас будут инструкции более высокого уровня, куда что помещать, как работать, как организовывать код и т. д. ETA, и все это накапливается по мере того, как агент перемещается по дереву. Так что информация не теряется. Даже если что-то находится в другой ветке дерева, оно все равно может быть связано в индексе документов или в одном из разделов выше. Если у вас есть общая функциональность, такая как вспомогательные средства, они могут находиться в другой части дерева, и агент все равно сможет связать их вместе, используя эти файлы markdown. Так что эти файлы markdown похожи на предварительный просмотр всей кодовой базы. Это как карта для агента, и агент перемещается по карте только до момента, когда ему нужно прикоснуться к фактическому коду. И поэтому мы не загрязняем окно контекста какой-либо нерелевантной информацией. Он может видеть все файлы документации на пути к цели. Он не видит никаких соседних папок, если они не связаны вручную, потому что они релевантны. Ладно, хватит разговоров. Думаю, я могу показать вам, как вы можете реализовать это в своем собственном репозитории. Это очень просто. Все, что вам нужно сделать, это открыть agents.mmd из репозитория Docs. Просто скопируйте файл и перейдем в терминал. Хорошо, я в своем терминале. Я клонировал наш агент Zero connector, это репозиторий, который еще не документирован. Так что я сейчас просто запущу CodeX здесь и скажу CodeX добавить это в конец agents.md здесь или создать. Я не знаю, есть ли уже agents.md в этом репозитории. Мне все равно. Codex возьмет это, добавит в конец agents.md, а затем я смогу сказать ему: инициализировать индекс документов. Хорошо, я поставлю это на очередь. И теперь agents.md либо создан, либо отредактирован с добавленным в конце Docs framework. И теперь CodeX поймет, что означает Docs, потому что agents.md всегда включен в системный промпт или в окно контекста. И теперь, когда я сказал ему инициализировать индекс документов, он знает, что делать. Он начнет читать всю кодовую базу и создавать эти точки документации agents.mmd по всему репозиторию и связывать эти файлы вместе. Это, вероятно, займет несколько минут, потому что LLM нужно прочитать всю кодовую базу или большую ее часть и вручную написать эти файлы документации. Но скоро мы сможем увидеть первый результат. Хорошо. Индексация существующей кодовой базы заняла около 5 минут. Это не особо большая база. Это файлы agents.md, созданные в подпапках для инструментов разработчика, документации для исходного кода, для различных стилей экранов и т. д. Итак, посмотрим, как это прошло. Хорошо. Это agents.md верхнего уровня. Ранее там были какие-то инструкции и ссылки. Так что Docs начнется где-то здесь. Вот он. И здесь у нас есть дочерний индекс документов. Так что мы можем взглянуть, скажем, на source screens. И здесь у нас есть владение, родительский пакет, правила, управление интеграцией приложений, команды, протокол, экраны должны возвращать типизированные результаты, классы данных или None, и никаких дочерних элементов под экранами. Мы можем улучшить это. Я могу сказать, что хочу улучшить документацию экранов. Я хочу, чтобы все файлы Python в папке screens имели свою собственную документацию. тот же файл с добавленным в конце markdown. И они будут документировать отдельные экраны, и они будут перечислены как дочерние индексы документов в файле документации их родителя. И вот так, если у нас есть что-то в нашем проекте, что недостаточно разделено, как в Agent Zero, у нас, например, есть папка helpers, которая содержит, возможно, 100 скриптов к настоящему времени. Мы можем сделать это так. Нам не нужно разделять ее на подпапки. Мы можем просто сказать агенту, что хотим изменить структуру документации для этой конкретной папки. Мы хотим документировать каждый из этих файлов индивидуально, и он просто поместит правило в этот файл agents.mmd, которое будет применяться только для этой папки, и эта папка может иметь свои индивидуальные файлы, документированные отдельно. Мы можем сделать это для любой папки по всему репозиторию. Мы можем сказать агенту, что хотим сделать это для каждой папки в репозитории, и в этом случае агент поместит это в agents.md верхнего уровня. Это зависит от нас. Фреймворк действительно прост и настраиваем. Вы можете просто сказать агенту, что хотите сделать что-то по-другому, и он применит это к правильным файлам agents.md. И мы можем увидеть обновление здесь. Итак, agents.md в screens был обновлен где-то здесь. Он говорит, что каждый модуль Python в этой папке должен иметь парный документ markdown. И вот так каждый файл в этой папке теперь документирован. И, давайте внесем некоторые изменения. Что у нас здесь? У нас установлены плагины. Хорошо, я скажу агенту, что хочу изменить что-то в представлении плагинов. Я хочу изменить представление плагинов так, чтобы оно имело другой цвет фона, чем другие. Когда пользователь откроет этот экран, я хочу, чтобы фон изменился с черного или того, что мы используем сейчас, на красный. И, очевидно, я не собираюсь сохранять это изменение. Я просто хочу продемонстрировать, как будет действовать CodeX. Я обновлю стилизацию экрана установленных плагинов. Я перечитаю применимую цепочку документов. Это важная часть, которую агент прочитает цепочку документов, потому что она могла быть изменена. Так что он начнет сверху, прочитает всю документацию, найдет правильный файл документации для экрана плагинов. Я смотрю на существующие селекторы установленных плагинов. Теперь вероятное изменение находится в правиле CSS, ограниченном областью экрана. Я понятия не имею, о чем он говорит, но теперь у него есть вся документация. Мне не нужно об этом беспокоиться. Хорошо. Итак, мы изменили фон экрана установленных плагинов на красный. Внутренний плагин остается темным. Обновили документацию markdown и проверили синтаксис. И, конечно, это совместимо с любым AI-агентом, который поддерживает agents.mmd. В Agent Zero вы можете сделать это в проекте. Например, когда вы создаете новый проект, вы можете поместить его непосредственно в инструкции проекта, или вы можете создать его как файл agents.mmd внутри этого проекта. Агент увидит это, или вы можете просто сказать своему агенту клонировать репозиторий agent0/docs в ваше текущее рабочее пространство. Он сделает это за вас. Итак, это файл markdown, меняющий жизнь, который вы искали. Вы можете поблагодарить меня позже. Вы можете поставить нам звезду. У нас их пока всего 41. Это очень свежо. Вы можете подписаться на наш канал, если вам нравится то, что мы делаем. И до следующего раза.