Transcription
В этом видео я покажу вам, как создавать самодокументирующийся ИИ-код, потому что самая большая проблема в "вайб-кодинге" заключается в том, что многие детали создаваемых вами функций в итоге не используются. Особенно если вы из тех людей, кто одобряет все изменения, вы упустите те критические моменты, когда Claude Code, Cursor или Gemini решают вырезать 50% того, что вы построили. И, конечно, вы этого не заметите. Так что вы ничего не подозреваете и думаете: "Эй, просто это не очень хорошо получилось". Но реальность такова, что под капотом все те функции, которые вы фактически создали, просто собирают пыль. Это как если бы система по умолчанию переключилась на режим Honda Civic, когда вы уже построили двигатель Ferrari.
Итак, сегодня мы покончим с этим раз и навсегда, создав самодокументирующиеся функции. И я покажу вам три уровня этой системы, каждый из которых немного сложнее предыдущего. Так что пристегнитесь, и давайте приступим.
Итак, я работаю над созданием этого очень классного инструмента для YouTube-стратегий. И он может анализировать целые каналы, извлекать семантические закономерности и предсказывать типы контента, который будет набирать популярность. И вот, то, что мы здесь видим, — это один конкретный вид из этого инструмента. И эта одна функция заняла у меня несколько часов. Она встраивает тысячи транскриптов видео, а затем семантически понимает способы речи, закономерности речи, которые имеют тенденцию становиться вирусными, основываясь на производительности этих видео.
Теперь, когда я столкнулся с этой ошибкой, когда семантическое разбиение не работало, я зашел в свой Claude Code и сделал то, что сделал бы большинство людей. Я взял ошибку и вставил ее сюда. Теперь мы видим, что Claude Code решил вместо того, чтобы исправить вызов функции, который просто неправильно использовал параметры, удалить всю функцию семантического разбиения. И я заметил это только потому, что внимательно следил за точными выходными данными и тем, что он собирался делать дальше. Но если мы посмотрим на наш файл, у нас есть полностью функционирующий файл с сотнями строк кода, почти 500 строк кода, которые специально созданы для обработки этого семантического разбиения. И я уже протестировал это и знал, что это работает.
Так что вместо получения глубоких аналитических данных о контенте мы получаем только эти базовые разбиения по времени. Это как простое сопоставление ключевых слов вместо чего-то, что действительно извлекает смысл из происходящего. Опять же, это как двигатель Ferrari, который не используется, а мы решаем просто кататься на велосипеде. Если вы не обращаете внимания на подобные вещи, вы потеряете много удаленных функций или функциональности, которые могут остаться в вашей кодовой базе, но ваши функции на самом деле не будут их вызывать.
И знаете что? Почти сезон Хэллоуина, если подумать. Так что напишите в комментариях свою историю ужасов об удалении функций. Сколько функций вы потеряли, даже не зная об этом в то время, потому что вы не обращали внимания на выходные данные и у вас не было этого исходного источника документации?
Итак, чтобы показать вам это, мы быстро создадим эту функцию, а затем, когда она будет готова, мы задокументируем эту функцию. Так что мы позволим этому делу идти своим чередом. Оно выйдет и создаст функцию, которая позволит нам запрашивать нашу базу данных и искать определенные вещи. Так что, когда это будет сделано, мы перейдем к следующему шагу.
Ладно, ребята. Функция только что была создана, заняла несколько минут, и теперь мы скажем: задокументируй эту функцию, которую мы только что завершили, как она работает, с чем она связана и так далее. Затем напиши описательный коммит git. И мы вернемся через секунду, чтобы проверить, что получилось.
И вот мы видим, что результат этого — довольно хорошая документация функции, потому что, опять же, мы не дали ей особого руководства относительно того, что именно мы хотим видеть. Мы просто сказали: "Эй, создай мне документацию по этой функции, которая описывает, как она работает". И мы получаем обзор архитектуры, различные компоненты этой архитектуры, которые были созданы, такие как сервисные уровни и API-уровни, и что было создано, как это взаимодействует с нашей базой данных. Обновления схемы базы данных, различные конечные точки API, которые мы создали, какие типы тел они принимают в качестве части ответа, какой тип ответа они отправляют обратно через API, например, на фронтенд, какая есть продвинутая функциональность, как все это работает, и так далее. В целом, довольно надежная документация о том, как работает эта конкретная функция.
И вы сразу заметите, что любая функция, которую вы создадите, основанная на этой корневой функции, которую вы только что задокументировали, будет выполняться гораздо чаще и правильно с первого раза. Больше не придется возвращаться и вперед три-четыре раза, отменять коммиты и восстанавливать контрольные точки, потому что что-то сломалось или что-то не было понято. У нее будет гораздо больше контекста о том, что именно ей нужно делать при использовании этой функции. Это происходит потому, что мы устраняем неоднозначность в отношении различных функций, их работы и связи друг с другом. Так что, когда фронтенд теперь делает запрос, например, или хочет обратиться к этой конечной точке, у него будет довольно точная документация о том, что ему нужно отправить и что он должен ожидать получить в ответ.
Это поможет вам значительно сократить количество сеансов отладки, которые вам придется проводить, и больше не придется случайно сжигать свою кодовую базу в 2 часа ночи, потому что вы слишком усердно работали, не понимая реальных функций и того, как они работают. Не говоря уже о том, что помимо увеличения скорости разработки новых функций, вы также получите гораздо более высокое качество каждой создаваемой вами функции.
Эта базовая система, честно говоря, сэкономила нам часы. Но что, если бы мы смогли кодифицировать это немного больше и сделать процесс немного более упорядоченным и предсказуемым? Вот некоторая документация из трех недавних проектов, над которыми я работал. Первый — это расширение для Chrome, которое я создаю, связанное с другим проектом, который мы рассматривали. И его единственная реальная форма документации — это комментарии, верно? И это полезно, если вы человек, который просто смотрит на это, но это не объясняет, как система в целом координируется с каждой частью.
Теперь, если мы посмотрим на этот другой проект кошелька Prompt Wallet, над которым я работал, у нас есть базовая README-файл в корне проекта, который объясняет, как его запустить и как начать, но нет никакой документации о том, как этот инструмент на самом деле работает. В моем проекте Forkcast, когда Claude Code видит проект такого размера, где у меня есть бэкенд-репозиторий и фронтенд-репозиторий, по сути, в одной папке проекта, есть сотни файлов в разных папках, разных каталогах, нескольких сервисных уровнях. У него действительно нет контекста о том, как многие из этих вещей на самом деле связаны на практике. Единственный контекст, который у него есть, — это я, вызывающий определенные функции, и понимание того, что определенные части связаны на основе того, как фактически используются текущие функции приложения.
В результате он часто переписывает существующие компоненты, что приведет вас в ад отладки. Ужасное место. Или он начнет ломать то, что уже работало. И поэтому часто у нас получается очень непоследовательная, беспорядочная документация по всем нашим функциям, которая не обязательно обновляется после внесения изменений в эти функции. И это делает весь процесс построения очень суматошным. Но, к счастью, мы можем преодолеть это с помощью базовой команды-слэша, которая может автоматизировать части этого процесса.
В Claude Code команда-слэш работает следующим образом: вы создаете каталог внутри вашего каталога claw под названием commands. А затем внутри commands вы можете предоставить файл markdown, который вы можете вызвать практически в любое время. Итак, что вам нужно сделать, это сначала выйти из вашего экземпляра Claude Code, а затем снова открыть его, и все, что вы добавили в папку команд, теперь будет там. Так что, если бы я ввел doc feature, мы увидим, что теперь у него есть эта команда, которую мы создали.
Хорошо, мы позволим этому делу поработать, а затем посмотрим, что это за промпт. И теперь мы видим, что у нас уже есть гораздо более структурированный тип документации, где мы предоставляем прямые ссылки или ссылки на важные файлы, которые эта функция затрагивает или использует, что она призвана решить в первую очередь, как она решает эту проблему, где она вписывается в общую архитектуру и поток данных в приложении, чтобы он понимал различные части и в какой момент эти части вступают в игру. Основные компоненты, которые мы создали, как эти вещи на самом деле работают, методы, которые у нас есть для них, и когда или когда методы следует использовать конкретно, все различные конечные точки и так далее. Это продолжается и продолжается и продолжается. Так что это гораздо более конкретно и актуально для того, что нам конкретно нужно, опять же, если бы мы пытались работать с LLM и давать ему необходимый контекст, и ничего больше.
Вы даже можете поднять это на новый уровень и создать команду, которая, например, обновляет документацию после того, как вы обновили функцию, которую вы уже создали, и вы хотите убедиться, что существующая документация соответствующим образом обновлена, и оставить заметки о том, что было изменено и почему. Так что подобные вещи могут изменить весь ваш рабочий процесс разработки, когда вы переходите от трех, четырех, пяти сломанных функций или интеграций каждую неделю к нулю или одной.
Но теперь очевидный следующий вопрос: могу ли я запускать это автоматически каждый раз, чтобы мне не приходилось вводить команды-слэши, чтобы оно запускалось? И ответ — да, с помощью под-агентов. Итак, мы зайдем сюда и попытаемся понять, насколько мы продвинулись в этом. Мы заставим систему завершить создание этой функции, и если она будет работать должным образом, она автоматически задокументирует то, что мы создали. И я собираюсь попросить ее сделать это. Итак, мы скажем ей, основываясь на спецификациях для этой конкретной функции. Я хочу, чтобы вы увидели, насколько она продвинулась, завершена ли она или нет, закончите то, что еще не сделано, а затем задокументируйте все, что она должна сделать. Я не говорил ей документировать это, но опять же, если наш агент работает должным образом, он должен запуститься.
Эта система должна работать с любой IDE, которая поддерживает под-агентов. Так что, если вы используете инструмент кодирования, который позволяет вам запускать под-агентов, вы сможете использовать какую-то версию этого. Я, очевидно, делаю это с Claude Code. Теперь промпты для команды-слэша и это определение агента доступны бесплатно под видео, так что вы можете ознакомиться с ними и рассмотреть их более подробно. Я расскажу о высокоуровневых вещах на секунду, пока это работает.
Итак, прежде всего, эта система должна проактивно запускаться в любое время, когда мы создаем новую функцию, вносим существенные изменения в код существующей функции или когда мы создаем текстовые спецификации для чего-то, что не входило в первоначальную область проекта. Так что, если мы начинаем отходить от архитектуры и пользовательских историй и всего того, с чего мы начали проект. И поэтому мы предоставляем несколько вещей: ссылки и ссылки на другие файлы, которые важны для правильного функционирования этой функции, где она вписывается в общую архитектуру приложения, каковы все основные компоненты, которые мы создали в рамках этой функции, и что она получает? Что она должна выдать? Где она находится? Как она связана со всем остальным, что мы строим? Каковы различные зависимости, которые у нее есть? Как ее нужно настроить? Было ли что-то, что нам нужно было изменить в нашей базе данных? Да? Так что мы продолжаем и продолжаем, просто давая много действительно подробных указаний относительно того, что это за функция и как она должна функционировать.
И теперь, когда это сделано, мы снова видим действительно надежную документацию функции. Все измененные файлы в рамках этого изменения, что отлично, верно? Потому что, если что-то сломается, я знаю, что могу просто вернуться и сослаться на эти файлы и спросить, где это могло сломаться, например, именно в этих файлах. Затем мы спускаемся и можем посмотреть, например, на фактическую архитектуру приложения и где это конкретно вписывается. Так, в контексте этого YouTube-инструмента, он интегрируется с текущей службой транскрипции YouTube, системой обработки очередей, которую я использую, конфигурацией переменных среды пришлось изменить, верно, чтобы использовать эту прокси-службу. Теперь у нас есть понимание того, как именно данные проходят через эту систему от начала до конца. Мы углубляемся в основные компоненты того, что она фактически создала, и как эти вещи работают. Например, менеджер для фактической конфигурации прокси, что он принимает, что выходит, где находится это изменение и каковы ключевые функции, реализованные в рамках этого изменения. Опять же, очень подробная документация о том, что именно мы создали и как именно это работает, что очень полезно для нас, чтобы вернуться и сослаться, но опять же, также для системы, чтобы сослаться, когда мы хотим отладить эту функцию позже или добавить что-то поверх нее. И мы можем сказать: "Эй, прежде чем ты начнешь создавать следующий этап, мне нужно, чтобы ты ознакомился с техническими спецификациями систем ротации IP-адресов".
Если вы объедините это с автоматизированными сообщениями Git, вы на пути к тому, чтобы стать настоящим Vibe Chad. Такие системы позволят вам строить гораздо быстрее, но и с гораздо лучшим качеством. Независимо от того, является ли ваша мечта — экспериментировать и создавать для себя, или вы хотите создать что-то, что однажды может превратиться в бизнес, такие процессы будут иметь решающее значение для вашего успеха. Так что, если вы хотите предпринять активные шаги к тому, чтобы стать продвинутым вайб-кодером, самодокументирующиеся циклы, подобные этим, — это самый простой инструмент, который вы можете добавить в свой арсенал.
Вот и все. Три подхода к самодокументирующемуся коду, которые вы можете использовать независимо от уровня вашего опыта. Это поможет вам быстрее создавать код, конечно, но, что более важно, это поможет вам создавать с большей уверенностью и качеством в том, что вы делаете, потому что, помимо предоставления дополнительного контекста, возможно, языковой модели, это будет отлично для вас, чтобы иметь возможность фактически просмотреть функцию, когда вам это нужно, и фактически понять, как она работает. Так что дело не только в эффективности токенов и в том, была ли созданная нами документация наиболее эффективной по токенам. Речь идет о том, как мы используем это для разработки систем, которые могут кодировать для нас автономно, где мы можем стать режиссером этого процесса, а не быть в его деталях.
Так что, если вам нравятся подобные видео, обязательно подпишитесь на канал, чтобы получать больше подробных, обоснованных, приземленных уроков, подобных этому. Итак, это все. Увидимся в следующем.