Устранение ежедневных препятствий для разработчиков: контекст ИИ, различия версий, порты и документация

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

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

Предоставление ИИ-ассистенту полезного контекста

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

Преобразование публичного репозитория в запрос с помощью GitReverse

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

Самый быстрый способ использования — замена URL. Начните с обычного адреса репозитория, подобного этому:

https://github.com/owner/repository

Замените хост github.com на gitreverse.com, сохраняя имя владельца и путь к репозиторию:

https://gitreverse.com/owner/repository

Сервис считывает информацию из репозитория и на её основе генерирует промпт. Это влияет на качество диалога, который можно вести. Если задать модели вопрос «Чем занимается этот проект?» без контекста, она может дать расплывчатый или выдуманный ответ. Начав с генерированного обзора, можно задавать более точные дополнительные вопросы:

• Как приложение организовано по модулям или пакетам?
• На каких языках, фреймворках и библиотеках оно основано?
• Как взаимодействуют между собой основные компоненты?
• Какие файлы являются наилучшими точками входа для изучения кода?
• Что потребуется, чтобы создать что-то с аналогичной архитектурой?

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

Пакетирование локальных файлов для помощника

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

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

src/auth/login.ts
src/auth/session.ts
src/api/auth.ts
src/components/LoginForm.tsx

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

Привычка, которую стоит выработать, — это задавать один вопрос перед каждым изменением с использованием ИИ: какие именно файлы контролируют это поведение? Ответ на него часто помогает понять проблему ещё до того, как модель что-либо скажет, и избавляет от большинства бессмысленных действий с копированием и вставкой. Чтобы узнать более подробно, в чём помощники ИИ при работе с фронтендом и где у них ограничения, прочитайте Разработка в React с ИИ: реальные преимущества, реальные ограничения.

Просмотр различий между ветками с помощью GitHub Compare

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

https://github.com/OWNER/REPO/compare/main...feature

На странице отображаются коммиты и различия между файлами в обоих версиях. Режим с тремя точками позволяет сравнивать текущую ветку с моментом её отделения от базовой ветки, что обычно и нужно при вопросе «Что добавляет эта функциональная ветка?». Он полезен для:

• оценки объёма изменений перед формальным рассмотрением
• проверки содержимого функциональной ветки
• анализа ветки с исправлениями ошибок, упомянутой кем-то в чате
• сравнения произвольных коммитов или тегов, а не только веток
• просмотра работы коллеги без необходимости изменения собственной рабочей ветки

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

Обмен локальным приложением с использованием перенаправления портов в VS Code

В новых версиях VS Code можно перенаправить порт с вашего устройства и получить URL, по которому к нему можно подключиться. Если ваш сервер разработки прослушивает соединения здесь:

localhost:3000

вы можете открыть панель Ports, перенаправить порт 3000 и получить генерированный адрес, работающий с других устройств. Распространенные случаи использования включают:

• открытие сайта на настоящем телефоне или планшете
• показ коллеге текущего состояния интерфейса
• предоставление кому-то возможности ознакомиться с функцией перед ее объединением
• прием webhook или ответа OAuth от внешнего сервиса
• запуск демо-версии без необходимости создания отдельной развернутой среды

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

Рассматривайте перенаправленный порт как публичный конечный пункт

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

Проверка адаптивных макетов с помощью Mobile View

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

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

Desktop
iPhone-sized viewport
Android-sized viewport
Tablet
Custom breakpoint

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

• текст, выходящий за границы контейнера
• кнопки, растягивающиеся до некорректных размеров
• навигационные элементы, переносимые на новые строки

Изображения, заставляющие контент выходить за границы области отображения

Карточки, слишком узкие для чтения

Размеры отступов, которые меняются в зависимости от размера экрана

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

Хранение документации в одном месте с DevDocs

Количество вкладок с документацией быстро растет: JavaScript, TypeScript, React, Node.js, CSS, HTTP, ваша база данных и тот фреймворк, который вы пробовали полгода назад. Когда вам нужен ответ быстро, поиск подходящей вкладки может занять больше времени, чем само прочтение ответа.

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

Этот инструмент оправдывает себя в следующих случаях:

• когда вы в пути или работаете через ненадежное подключение
• когда вы переключаетесь между несколькими технологиями в тот же день
• когда вам нужно быстро найти информацию о сигнатуре API
• когда вы хотите хранить справочные материалы в одном едином месте

Быстрый поиск справочной информации недооценивается. Когда вы уже знаете, что создаёте, вам редко нужны длинные учебники. Вам требуется точный ответ на конкретный вопрос, например «Какие аргументы принимает этот метод?», и именно для этого идеально подходит объединённая, поисковая библиотека.

Исследование вложенных данных с JSON Crack

Любой, кто работает с API, рано или поздно сталкивается с ответом, настолько глубоко вложенным, что его чтение в виде текста превращается в задачу подсчёта скобок. Даже небольшой пример показывает суть проблемы:

{
  "user": {
    "profile": {
      "account": {
        "settings": {
          "notifications": {
            "email": true
          }
        }
      }
    }
  }
}

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

JSON Crack преобразует структурированные данные в интерактивную схему, благодаря чему вложенность становится видимой в виде связанных узлов, которыми можно навигировать. На момент написания этого текста инструмент поддерживает форматы JSON, YAML, XML и CSV, а также имеет расширение для VS Code. Он полезен для:

• отладки данных, передаваемых через API
• ознакомления с незнакомым форматом данных
• исследования крупных конфигурационных файлов
• объяснения структуры данных коллегам
• определения местоположения конкретного атрибута

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

Описание схем баз данных в виде текста с помощью dbdiagram.io

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

dbdiagram.io позволяет описывать таблицы и связи с помощью простого текстового языка, после чего генерирует соответствующую диаграмму. В документации этот язык называется DBML (Database Markup Language). Поскольку схема представлена в виде обычного текста, её можно хранить в системе контроля версий и рассматривать как любые другие изменения.

Вот упрощённый обзор таблицы пользователей:

users
- id
- name
- email

а также таблица заказов, которая ссылается на неё, с описанием связи между ними:

orders
- id
- user_id
- totalusers.id < orders.user_id

Следует обратить внимание на два момента. Во-первых, этот фрагмент представляет собой набросок, а не корректный DBML: настоящий DBML описывает каждую таблицу с помощью блока Table name { ... } и указывает типы столбцов. Во-вторых, в последней строке второго фрагмента две строки объединены в одну; total является последним столбцом таблицы orders, а users.id < orders.user_id — отдельной строкой, описывающей связь. В DBML символ < обозначает связь типа «один к многим», поэтому это означает «один пользователь имеет множество заказов». Перед созданием реальной схемы ознакомьтесь с точным синтаксисом в документации dbdiagram.io.

Почему диаграмма окупает себя

Четкая диаграмма связей сущностей помогает вам:

• понять систему, которую вы не проектировали
• спланировать новую схему перед написанием миграций
• объяснить связи коллегам

Выявляйте таблицы и ссылки, которые добавляют сложность без реальной пользы

Документируйте проект

Быстрее интегрируйте новых разработчиков

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

Структурирование обучения с roadmap.sh

Знакомая схема для разработчиков: сначала изучают JavaScript, затем React, потом TypeScript, затем Docker, немного Kubernetes, базу данных, а уже в объявлении о работе упоминается что-то, чего они раньше не слышали. Список вещей, которые нужно выучить, кажется бесконечным.

roadmap.sh публикует созданные сообществом учебные пути по фронтенду, бэкенду, полному стеку, DevOps, базам данных, ИИ, проектированию систем, облачным технологиям и отдельным языкам программирования. Цель не в том, чтобы перечислить всё, что необходимо знать. Цель — предоставить карту, чтобы вы могли понять, куда вписывается тот или иной тематический блок, вместо того чтобы перепрыгивать между не связанными уроками.

Новичок может представлять себе разработку бэкенда как двухэтапный процесс:

Learn a framework → Build API

Карта показывает, что на самом деле этот путь гораздо длиннее и состоит из нескольких уровней:

Programming
    ↓
Git
    ↓
HTTP
    ↓
Databases
    ↓
APIs
    ↓
Authentication
    ↓
Testing
    ↓
Caching
    ↓
Security
    ↓
Deployment
    ↓
System Design

Именно такой более широкий взгляд отсутствует у многих начинающих. Он объясняет, почему существующий API — это ещё не конец работы, и почему такие темы, как аутентификация, тестирование, кэширование и безопасность, заслуживают тщательного изучения. Администраторы сайта постоянно обновляют планы развития и сопутствующие материалы, что делает их разумной отправной точкой для структурированного обучения. Рассматривайте их как руководство, а не как список проверки: вам не обязательно освоить каждый пункт, прежде чем начать эффективно работать. Чтобы узнать информацию, специфичную для фронтенд-разработки, ознакомьтесь с нашим реалистичным планом развития для фронтенд-разработчиков.

Категория, которую следует внимательно изучать: ИИ-агенты браузера

Браузеры, созданные для ИИ-агентов, представляют собой новую категорию. Классическая автоматизация браузера обычно запускает новую сессию, что создаёт неудобства, когда задача зависит от существующих входов, настроек или открытых вкладок. Инструменты вроде Eagle Light призваны предоставить агенту собственное изолированное рабочее пространство браузера, где он может взаимодействовать с сайтами, при этом ваше обычное просмотрение остаётся отдельным.

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

Общая схема всех этих инструментов

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

• ручное копирование файлов из репозитория превращается в этап передачи данных от репозитория к команде или от файлов к команде
• постоянная настройка размера браузера превращается в возможность просмотра на нескольких виджетах
• поиск в десяти вкладках с документацией превращается в возможность поиска в единой библиотеке
• чтение глубоко вложенных структур JSON в виде текста превращается в визуальную схему
• устное объяснение взаимосвязей между таблицами превращается в диаграмму, описанную текстом
• случайное обучение превращается в следование построенному плану

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

Выбор точки старта

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

• для кодирования с помощью ИИ используйте работу с репозиторием или файлами для формирования команд, сохраняя при этом небольшой и релевантный контекст

Для работы с фронтендом имейте под рукой инструмент для превью с адаптивным дизайном, но всё равно тестируйте на реальных устройствах.

Для работы с API имейте под рукой визуализатор JSON.

Для работы с бэкендом и данными храните вашу схему в виде диаграммы под контролем версий.

Для ежедневного использования используйте один источник документации с возможностью поиска и регулярно обновляйте его.

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

Лучший инструмент — это редко тот, у которого самый длинный список функций. Это тот инструмент, который решает проблемы, с которыми вы постоянно сталкиваетесь.

Основные выводы

• Лучшие результаты от ИИ начинаются с лучшего контекста: предоставляйте ассистентам лишь несколько файлов, определяющих их поведение, и проверяйте сгенерированные краткие описания репозиториев по коду.
• Встроенные функции, такие как режим сравнения в GitHub и перенаправление портов в VS Code, часто превосходят установку новых инструментов.
• Каждый элемент удобства, позволяющий получить доступ к чему-либо — будь то перенаправленный порт или агент с возможностью работы в браузере, — требует осознанного решения с точки зрения безопасности.
• Симуляции и краткие обзоры, от предварительного просмотра в окне просмотра до генерируемых запросов, ускоряют первоначальную обработку, но не заменяют проверку реального варианта.
• Когда задача кажется повторяющейся, сделайте паузу и спросите себя, существует ли уже лучший инструмент; ответ часто бывает «да».