Я позволил CodeSpeak взять под контроль мой репозиторий.

Что произошло, когда я перевел проект объемом более 10 000 строк кода в рабочий процесс, изначально разработанный с использованием искусственного интеллекта?

Делиться

Языки программирования значительно эволюционировали с течением времени, становясь все более абстрактными и более понятными для человека. На заре вычислительной техники программисты работали непосредственно с машинным кодом, вручную вводя необработанные двоичные инструкции с помощью перфокарт, в которых отверстия кодировали данные и команды для первых мэйнфреймов. Этот процесс был утомительным и крайне подвержен ошибкам: одно неправильно расположенное отверстие могло сломать всю программу и заставить разработчиков начинать все сначала.

Для уменьшения этих препятствий появился язык ассемблера, заменивший необработанный двоичный код на удобочитаемые мнемонические обозначения, такие как ADD или MOV , которые затем преобразовывались обратно в машинные инструкции.

Следующий крупный скачок произошел в 1950-х годах, когда появились первые компилируемые языки высокого уровня, такие как FORTRAN и COBOL. Они ввели синтаксис, более близкий к математической нотации и естественному языку. Позже такие языки, как ALGOL, C и C++, привнесли структурное программирование, абстракцию памяти и объектно-ориентированные концепции, значительно снизив сложность программного обеспечения и улучшив его сопровождение.

Современные языки программирования, такие как Python и Java, продолжили эту тенденцию, уделяя приоритетное внимание читаемости кода и предлагая обширные экосистемы встроенных библиотек, что позволяет инженерам больше сосредоточиться на решении бизнес-задач, а не на деталях аппаратного обеспечения.

Однако в последнее время подход к написанию кода снова начал меняться с появлением и широким распространением искусственного интеллекта. Естественно, возникает вопрос: будут ли эволюционировать и языки программирования?

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

Настройка всего оборудования

Как обычно, прежде чем приступить к сборке, нам нужно всё настроить. К счастью, процесс довольно прост. Мы можем установить CodeSpeak с помощью менеджера пакетов uv :

 uv tool install codespeak-cli codespeak --version # CodeSpeak CLI 0.4.1

Далее нам нужно войти в систему. Выполнение следующей команды откроет окно браузера, где вы можете либо авторизоваться с помощью своей учетной записи Google, либо создать отдельный логин и пароль для CodeSpeak. После принятия Условий использования вы будете успешно авторизованы.

 codespeak login

Последний шаг — настройка вашего API-ключа, поскольку CodeSpeak придерживается политики «используйте свой собственный ключ». В настоящий момент он поддерживает только антропический API-ключ, что вполне логично, учитывая популярность антропических моделей в задачах программирования. Вы можете сгенерировать свой ключ на https://platform.claude.com/settings/keys и экспортировать его в качестве переменной окружения.

 export ANTHROPIC_API_KEY=

Вот и всё. Мы готовы начать строительство.

Создание проектов с помощью CodeSpeak

CodeSpeak поддерживает разработку с нуля, если вы составляете спецификацию и выполняете сборку на её основе. Однако я подумал, что было бы интереснее протестировать его на более зрелом проекте (или, по крайней мере, на уже работающем) и посмотреть, насколько хорошо он справляется с существующей кодовой базой.

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

Перенимать

Прежде чем использовать CodeSpeak для реализации новых функций, нам сначала нужно сгенерировать первоначальную версию спецификации. К счастью, CodeSpeak может помочь и в этом.

Я начал с того, что скопировал весь код из своего фитнес-приложения в новый репозиторий. Затем я удалил все существующие спецификации и файл структуры, чтобы имитировать более реалистичный сценарий, когда вы быстро написали что-то на Vibe Code, а теперь хотите перевести проект в более структурированный рабочий процесс с помощью CodeSpeak.

CodeSpeak позволяет переносить только отдельные части или модули проекта, но я решил пойти до конца и перенести всё приложение целиком. Репозиторий содержит около 13 тысяч строк кода, поэтому, хотя он и не огромен, это всё же достаточно крупный проект для подобного эксперимента.

Начать создание спецификаций можно с помощью следующей команды.

 codespeak takeover

Затем CodeSpeak тратит некоторое время на анализ ваших локальных файлов. В моем случае весь процесс занял около минуты. После этого открылась веб-страница с предлагаемой структурой кодовой базы. Она предложила разделить мое приложение на четыре модуля: фронтенд, бэкенд API, слой данных и бэкенд-тесты.

Модули — это хорошо зарекомендовавшая себя концепция программирования, и легко понять, почему они полезны: они создают более компактные, самодостаточные домены, улучшают читаемость и упрощают повторное использование компонентов в разных проектах. Поэтому замечательно, что CodeSpeak предлагает нам создать 4 разных спецификации, вместо того чтобы пытаться уместить всё в один длинный документ.

В браузере вы можете просмотреть каждый модуль и попросить CodeSpeak разделить, объединить или переосмыслить его. В моем случае предложенная структура показалась разумной, поэтому я решил оставить все как есть и перенести все модули, позволив CodeSpeak управлять всем репозиторием.

После выбора всех модулей и начала процесса захвата, CodeSpeak обрабатывал их по одному: считывал файлы, генерировал спецификации, уточнял их и запускал тесты.

В итоге была создана директория specs содержащая четыре файла спецификаций (по одному для каждого модуля). Давайте посмотрим на один из них, frontend.cs.md .

Документ начинается с оператора импорта: import specs/backend_api.cs.md . Импорт используется для отслеживания зависимостей между модулями и поддержания контекста для агента. Например, когда агент работает со спецификацией фронтенда, он знает, что сначала нужно загрузить спецификацию API бэкенда. Поскольку сама спецификация API бэкенда импортирует спецификацию уровня данных, агент автоматически подтягивает и её. В результате он получает весь необходимый контекст, прежде чем вносить изменения во фронтенд. Это довольно удобно и обеспечивает чистую декомпозицию кодовой базы, аналогично тому, как обрабатываются зависимости и абстракции в традиционной разработке программного обеспечения.

Остальная часть документа имеет структурированный формат и описывает все основные части фронтенда: от технологического стека до аутентификации, функциональности на уровне страниц и существующего тестового покрытия.

 Frontend SPA ├── Stack & Setup ├── Authentication ├── Layout & Navigation ├── API Client ├── Pages │ ├── History (/history) │ │ ├── Weekly summary card │ │ ├── 12-week training trends chart │ │ └── Session list │ ├── Log Workout (/log) │ │ ├── Cardio form │ │ └── Strength form │ ├── Session Detail (/sessions/:id) │ │ ├── Strength session detail │ │ └── Cardio session detail │ ├── Templates (/templates) │ ├── Settings (/settings) │ │ ├── Activity Types │ │ ├── Exercise Types │ │ └── Exercises │ └── Login (/login) ├── Shared Components │ ├── ExerciseEntryBlock │ ├── TimeInput │ └── ProtectedRoute ├── Utility Modules │ ├── dateUtils │ └── unitUtils └── Tests ├── LoginPage.test.tsx └── TimeInput.test.tsx

На первый взгляд, сгенерированные спецификации выглядели довольно исчерпывающими и, казалось, хорошо отражали большинство деталей реализации (даже такие мелочи, как мое предпочтение шрифту Montserrat).

Конечно, первое впечатление может быть обманчивым, поэтому я решил протестировать их как следует. К счастью, у меня сохранились все оригинальные спецификации, использованные при разработке приложения. Это позволило сравнить спецификации, сгенерированные CodeSpeak, с оригинальными, используя LLM.

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

Основные пробелы касались миссии проекта (почему мы это создаём) и дорожной карты (планов на будущее), что вполне ожидаемо, поскольку ни то, ни другое нельзя легко определить только по коду.

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

В целом, CodeSpeak отлично справился с задачей создания спецификаций, объясняющих существующий код. Но создание спецификаций никогда не было конечной целью, поэтому давайте применим их на практике и действительно что-нибудь построим.

Реализация функции

Я уже использую приложение для отслеживания своих тренировок, но мне также хотелось бы получать обратную связь от тренера с искусственным интеллектом, чтобы понимать, правильно ли я тренируюсь. В конечном итоге я хотел бы иметь полностью интегрированного в приложение ИИ-помощника, но давайте начнем с малого и добавим возможность генерировать краткое описание тренировки в текстовом формате, которое можно скопировать и передать ИИ.

Поскольку мы работаем по методологии разработки, основанной на спецификациях, внедрение этой функции начинается с обновления спецификации. Изменения в основном касаются пользовательского интерфейса, поэтому я отредактировал файл frontend.cs.md и добавил описание новой функциональности.

После этого я смог реализовать эту функцию с помощью следующей команды, которая не только внедряет изменения, но и гарантирует прохождение всех тестов. Насколько я понимаю, для внедрения изменений CodeSpeak «под капотом» анализирует разницу в спецификации и пытается сгенерировать код, соответствующий ей.

 codespeak build frontend.cs.md 

Совет: Если вам нужна лишь быстрая реализация без полного цикла валидации, вы можете использовать codespeak impl .

После выполнения команды CodeSpeak начал читать спецификации и анализировать, что нужно изменить. Первоначально он начал добавлять заголовочные файлы CodeSpeak во многие файлы, что немного сбивало с толку, поскольку это не было очевидно связано с моим запросом. Надеюсь, это происходит только при первом запуске.

 # Generated by CodeSpeak from spec file: specs/backend_api.cs.md # Modifying this file manually is DISCOURAGED. # CodeSpeak will try to preserve manual changes, but it's not guaranteed.

После завершения обработки заголовков система правильно определила основную задачу: добавление кнопки «Копировать сводку тренировки» в каждую строку сессии на HistoryPage . Изменение было внесено, все тесты пройдены, и сборка отмечена как успешная.

Пора протестировать. Самый простой способ проверить изменения в пользовательском интерфейсе — просто запустить приложение и проверить его. Поэтому я запустил проект локально с помощью Docker Compose. Новая кнопка копирования появилась рядом с каждой сессией в истории и корректно работала для силовых тренировок. Однако, когда я попытался скопировать кардио-тренировку, это не удалось. Хуже того, ошибка произошла незаметно, без каких-либо сообщений об ошибках в консоли браузера или логах Docker.

Итак, теперь у нас обнаружилась ошибка. Важно отметить, что проблема заключалась не в спецификации, а в самой реализации. Для её исправления можно использовать запрос на изменение кода. Для небольших изменений CodeSpeak поддерживает удобную однострочную команду.

 codespeak change frontend.cs.md -m "Support format of cardio training for copy button"

В моем случае запрос был несколько сложнее, поэтому я решил создать отдельный файл для запроса на изменение.

 codespeak change --new # Created template change request in # /Users/marie/Documents/github/trainlytics_codespeak/change-request.cs.md

Внутри файла я добавил следующий запрос, охватывающий как исправление ошибки, так и улучшение поддержки отладки.

 - Support copying summaries for cardio trainings, since it currently fails (likely due to a different data format) - Add logging for copy failures, as issues currently do not appear in either browser console logs or Docker logs

После этого я попросил CodeSpeak внести изменения.

 codespeak change frontend.cs.md 

Прежде чем вносить какие-либо изменения, CodeSpeak сначала проверяет, соответствуют ли запрошенные изменения кода существующим спецификациям. Если запрос противоречит спецификации, система предлагает либо пересмотреть запрос, либо сначала обновить спецификацию и пересобрать проект. Я нашел это особенно полезным, поскольку это помогает уменьшить расхождения между спецификациями и реализацией.

В итоге CodeSpeak исправил проблему и добавил тесты для предотвращения подобных регрессий в будущем.

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

Краткое содержание

В целом, я считаю, что этот эксперимент был довольно успешным. CodeSpeak удалось взять под контроль репозиторий с более чем 10 000 строк кода, не потеряв при этом ни одной важной детали реализации, что действительно впечатляет. После этого мы обновили спецификацию и создали новый функционал непосредственно на её основе.

Первая попытка реализации была не идеальной, но после отправки запроса на изменение кода CodeSpeak не только исправил ошибку, но и добавил тесты, предотвращающие повторное возникновение подобных проблем в будущих сборках. Мне особенно понравились эти автоматические механизмы защиты, поскольку они помогают сделать продукт более перспективным.

Опыт разработки с помощью CodeSpeak сильно отличался от ранее исследованного мною подхода к разработке на основе спецификаций. Позвольте мне выделить несколько ключевых отличий.

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

Это также ясно показывает, что CodeSpeak в первую очередь предназначен для инженеров. Для эффективного использования вам по-прежнему необходимо понимать модульную структуру системы и вносить соответствующие целенаправленные изменения в спецификации. Напротив, разработка, основанная на спецификациях, может быть внедрена даже при гораздо меньшем инженерном опыте, поскольку рабочий процесс часто ближе к общению с агентом и сохранению промежуточных решений в репозитории для сохранения намерений и контекста.

Однако должен признать, что CodeSpeak оказался совсем не таким, каким я его себе представлял изначально. Я использовал более десятка языков программирования, и CodeSpeak не очень-то похож ни на один из них. На самом деле, главное нововведение, похоже, заключается не столько в самом языке, сколько в инструментах и рабочем процессе, построенных вокруг него, что является интересным изменением.

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

Поэтому я надеюсь, что по мере развития CodeSpeak (и стоит помнить, что сейчас это все еще альфа-версия) в нем появится более целенаправленный подход к написанию высококачественных спецификаций, а также лучшие инструменты для их проверки и улучшения.

Мария Мансурова Посмотреть все от Марии Мансуровой

Источник: towardsdatascience.com