Практические примеры и сценарии
Конкретные задачи, которые решает Istok Code: объяснение кода, поиск багов, написание тестов, рефакторинг, работа с большой кодовой базой, долгие задачи с resume и CI-интеграция.
- CLI установлен и работает, но непонятно, с чего начать реальную задачу
- Хотите увидеть конкретные примеры перед тем как объяснять коллеге
- Нужен ориентир по тому, какие задачи вообще стоит отдавать агенту
- Понимание, какие задачи CLI решает хорошо и в каком порядке действовать
- Несколько готовых шаблонов запросов для начала
- Реальный сценарий для первого ежедневного использования
Объяснение незнакомого кода
Один из самых частых сценариев — попросить CLI объяснить модуль, функцию или файл, который вы видите впервые. Это работает лучше, когда вы задаёте конкретный вопрос, а не просто просите "объясни этот файл".
- istok-code "объясни, что делает функция processQueue в src/queue.ts и какие у неё побочные эффекты"
- istok-code "как работает middleware авторизации в app/middleware/auth.py и где он вызывается"
- istok-code --file src/billing/invoice.ts "опиши, как этот модуль считает итоговую сумму"
Поиск потенциальных проблем в коде
CLI хорошо справляется с поиском типичных проблем: N+1 запросы, гонки данных, необработанные ошибки, утечки ресурсов. Главное — указать конкретную область, а не просить проверить весь проект сразу.
- istok-code --file src/db/users.ts "найди возможные N+1 запросы к базе данных"
- istok-code --file src/api/upload.ts "проверь, всегда ли закрываются файловые дескрипторы при ошибках"
- istok-code "посмотри на обработчики ошибок в src/api/ и скажи, где исключения проглатываются без логирования"
Написание тестов
Попросите написать тесты для конкретной функции или модуля. Задача работает лучше, когда агент уже видит реализацию и тестовый фреймворк, который используется в проекте. Если тесты уже есть рядом — укажите их как образец.
- istok-code --file src/utils/date.ts "напиши unit-тесты для всех экспортируемых функций, используй vitest"
- istok-code --file src/auth/token.ts --file tests/auth/token.test.ts "добавь тесты для крайних случаев: истёкший токен, невалидная подпись"
- istok-code "напиши интеграционный тест для POST /api/orders, который проверяет создание заказа и списание лимитов"
Рефакторинг с проверкой через symbols
Перед рефакторингом полезно сначала найти все места, где используется функция или тип, а не угадывать по памяти. Для этого есть symbols с флагом --refs. После правок обязательно запустите verify, чтобы убедиться, что ничего не сломалось.
Найдите все места использования
istok-code symbols fetchUser --refs — покажет определения и все обращения к функции в проекте.
Попросите выполнить рефакторинг
istok-code "переименуй fetchUser в getUser во всём проекте и обнови все вызовы"
Проверьте результат
istok-code verify — убедитесь, что тесты и сборка прошли без ошибок.
При падении используйте /fix
Если verify упал, запустите /fix в интерактивной сессии. Агент получит контекст ошибки и исправит её точнее.
Долгие задачи с продолжением через resume
Если задача требует нескольких часов работы с перерывами, используйте resume вместо того чтобы каждый раз начинать с нуля. Сохраните ID сессии после первой части работы и продолжите позже с того же места.
Хорошая практика — в начале resumed-сессии дать короткое напоминание по задаче. Это помогает агенту сразу войти в контекст, а не начинать с разведки.
Запустите задачу и сохраните ID
После начала работы посмотрите ID сессии через /sessions или запомните из строки статуса.
Прервитесь в нужный момент
Закройте терминал или завершите сессию через /quit.
Продолжите позже
istok-code resume latest или istok-code --resume <id> — поднимет именно ту сессию.
Дайте контекст
Напомните агенту: "мы делали рефакторинг модуля auth, остановились на написании тестов".
Режим планирования перед большими изменениями
Для крупных задач полезно сначала попросить план, обсудить его, а только потом давать разрешение на выполнение. Режим /plan переключает агента в режим, где он строит план, но не выполняет действия до вашего подтверждения.
Это особенно важно при рефакторинге затрагивающем много файлов, при добавлении нового слоя в архитектуру или при задачах, где цена ошибки высокая.
- Введите /plan в начале интерактивной сессии, чтобы переключиться в режим планирования.
- Задайте задачу — агент опишет шаги, не трогая файлы.
- Когда план устраивает, введите /plan ещё раз, чтобы вернуться в рабочий режим, и подтвердите выполнение.
Использование в CI и скриптах
Для автоматизированных пайплайнов CLI поддерживает неинтерактивный режим через подкоманду run и флаг --pipe. Это позволяет встраивать агента в GitHub Actions, GitLab CI или любые shell-скрипты.
- echo "${{ secrets.ISTOK_TOKEN }}" | istok-code login --token-stdin — безопасный вход в CI без интерактивного браузера.
- istok-code run "проверь, нет ли TODO с пометкой CRITICAL в src/" — одноразовый запрос и выход.
- istok-code run --output-format json "запусти тесты и вернись JSON со статусом" — машиночитаемый вывод для парсинга в пайплайне.
- cat diff.txt | istok-code --pipe "опиши, что изменилось в этом диффе" — обработка stdin без интерактивной сессии.
Code review конкретного файла или диффа
Перед мержем можно попросить агента провести быстрый review конкретного файла или набора изменений. Это не заменяет человека, но хорошо находит очевидные проблемы: отсутствие обработки ошибок, небезопасные паттерны, нарушение соглашений.
- istok-code --file src/api/payments.ts "сделай код-ревью этого файла: безопасность, обработка ошибок, читаемость"
- git diff HEAD~1 | istok-code --pipe "проведи review этих изменений и укажи возможные проблемы"
- istok-code --file src/auth/session.ts "проверь, нет ли уязвимостей, связанных с управлением сессией"