Проблема
Разработчики пишут больше текста, чем большинство людей понимает. Помимо самого кода, есть постоянный поток не-кодового письма, который происходит внутри VS Code: встроенные комментарии, docstrings функций, разделы README, черновики сообщений коммита, описания билетов, todo аннотации и заметки архитектурных решений.
Это письмо часто рассматривается как вторичное — что-то делать быстро или откладывать до позже. Результат — кодовые базы с редкой документацией, функции без объяснения того, почему они существуют, и архитектурные решения, которые существуют только в памяти кого-то.
Трение реально. После траты умственной энергии на сложный алгоритм, последнее, что большинство разработчиков хотят делать — писать абзац, объясняющий его. Печать ощущается как дополнительная работа сверху реальной работы. Но документация, написанная немедленно после реализации — пока контекст свежий — драматически более ценна, чем документация, написанная неделю позже, или вообще не написана.
Как Telvr работает с VS Code
Telvr интегрируется с VS Code и любым другим текстовым редактором через вставку позиции курсора на уровне системы. Не требуется расширение VS Code. Ни API ключа в вашем редакторе. Ни конфигурации внутри VS Code самого.
Рабочий процесс для документации разработки:
- Откройте VS Code и позиционируйте ваш курсор, где вы хотите, чтобы документация появилась — над функцией, в блоке комментария, в файле README или в новом документе markdown.
- Нажмите горячую клавишу Telvr.
- Говорите вашу документацию, объяснение или описание задачи.
- Отпустите горячую клавишу. Отформатированный результат появляется у вашего курсора менее чем за две секунды.
- Продолжайте кодирование.
Telvr работает во всех контекстах VS Code: сам редактор, встроенный терминал (для высказанных идей команды) и файлы markdown preview. Это также работает в JSON параметров VS Code и других файлов конфигурации, где вы можете захотеть добавить комментарии.
Лучший режим обогащения для VS Code: Dev Task
Режим Dev Task разработан специально для документации рабочего процесса разработки. Когда вы активируете его и говорите о куске кода или задаче, ИИ структурирует ваш результат в формат, готовый к разработке с четырьмя разделами:
Контекст: Справочная информация, объясняющая, что этот код делает, почему он существует или какую проблему он решает.
Требования: Что реализация должна удовлетворить — ограничения, зависимости, граничные случаи или бизнес-правила.
Заметки реализации: Технические детали, принятый подход, рассмотренные компромиссы или важные предупреждения.
Критерии приемки: Как проверить, что реализация правильна — какие тесты должны пройти, какое поведение ожидать или какие условия определяют успех.
Эта структура немедленно полезна для:
- Блоков документации уровня функции, объясняющих сложную логику
- Комментариев заголовка уровня файла для неочевидных модулей
- Описаний задач при планировании работы непосредственно в файлах кода
- Записей архитектурных решений (ADRs), написанных в markdown
Для более простых встроенных комментариев — быстрого объяснения regex, заметки об известном ограничении — режим Clean and Correct дает вам чистую, читаемую прозу без формальной структуры.
Пример "До и После"
Необработанный ввод речи (режим Dev Task):
"so this function handles the rate limiting for the API uh it needs to track requests per user per minute and it should use a sliding window not a fixed window because fixed windows can allow burst traffic right at the boundary um it depends on Redis for the counter storage and it should return a 429 with a retry-after header when the limit is exceeded we should also make sure that the limit keys expire automatically so we don't fill up Redis over time"
После режима Dev Task:
Контекст Обрабатывает ограничение скорости ИИ на пользователя с использованием алгоритма скользящего окна. Использует Redis для хранения распределенного счетчика для поддержки развертываний с несколькими экземплярами.
Требования
- Отслеживать запросы на пользователя в минуту с использованием скользящего окна (не фиксированного окна)
- Вернуть HTTP 429 с заголовком
Retry-Afterпри превышении лимита- Ключи Redis должны автоматически истекать для предотвращения неограниченного роста хранилища
Заметки реализации
- Скользящее окно выбрано вместо фиксированного окна для предотвращения всплеска трафика на границах окна
- Зависимость Redis требуется для распределенного состояния ограничения скорости
Критерии приемки
- Ограничение скорости правильно применяется при устойчивом и всплесковом трафике
- Ключи Redis истекают как ожидается (проверять с помощью команд TTL)
- Ответы 429 включают действительный заголовок
Retry-After- Нет накопления ключа Redis после периодов расширенного тестирования
Говоренная версия — это блуждающее объяснение. Результат Dev Task — это структурированная спецификация, которую вы можете пасте прямо над функцией как блок документации.
Экономия времени
Документация хронически недооценена, потому что медленно писать относительно ее воспринимаемой ценности в момент. Разработчики, которые переходят на документацию голосом, сообщают два изменения: они документируют больше, и они документируют лучше.
Написание комплексного блока документации функции занимает пять до восьми минут сосредоточенной печати. Говорение того же контента занимает шестьдесят до девяносто секунд, и режим Dev Task обрабатывает форматирование. Уменьшенное время инвестиций делает документацию осуществимой, а не обремениеслительной.
Для более длинных документов — READMEs, записи архитектурных решений, руководства введения — экономия времени масштабируется пропорционально. Один тысячесловный README, который займет сорок пять минут для написания, может быть продиктован за десять до двенадцати минут и затем отредактирован оттуда.
Есть также аргумент качества. Когда документация черновика немедленно после написания кода, пока детали реализации свежие, результирующая документация точнее и полезнее. Скорость Telvr делает практичным документировать во время кодирования, а не как отложенную задачу.
Через типичную неделю разработки с регулярной работой документации, Telvr может восстановить два-три часа — и создать лучше документированную кодовую базу как побочный эффект.
Начало работы
- Загрузите Telvr для macOS с telvr.ai.
- Завершите настройку и конфигурируйте ваш предпочтительный микрофон.
- Установите горячую клавишу, которая работает в рабочем потоке VS Code — что-то, что вы можете нажать без перемещения рук далеко от домашнего ряда.
- Откройте VS Code, позиционируйте ваш курсор над функцией или в блоке документации и протестируйте вашу первую диктовку.
- Установите Dev Task как ваш режим по умолчанию для работы документации разработки.
Хорошее первое упражнение: найдите три наиболее сложные функции в вашем текущем проекте — те, которые выиграют наиболее от четкой документации — и продиктуйте блок Dev Task для каждой. Все упражнение должно занять менее десяти минут и создать документацию, которая займет час для написания.
Telvr включает 14-дневный бесплатный период пробной версии с полным доступом ко всем режимам обогащения. После пробной версии цена составляет EUR 3 в месяц плюс от EUR 0,003 за минуту транскрипции.