С Istok вы работаете через разговор с агентом. Здесь показано, что говорить в типичных ситуациях и что Istok каждый раз записывает, — чтобы вы знали, что найдёт следующая сессия.
В примерах проект acme-api, агенты Claude Code и Codex. Предполагается, что агент уже подключён и получил инструкции из Быстрого старта.
Начать задачу
Опишите работу так, как обычно. Упоминать Istok не нужно.
GET /orders/{id} отдаёт 500, если заказа нет. Для неизвестных заказов должен быть 404, остальные ошибки пусть остаются 500.
Что записывает Istok: задачу, например #18 «Return 404 for missing orders», с описанием и критериями приёмки. Перед тем как писать код, агент берёт задачу в работу: открывается запуск под его идентификатором исполнителя, и Istok сохраняет, какой именно контекст агент получил.
На вопрос или правку в одну строку агент просто ответит. Задачи нужны для работы, к которой стоит вернуться позже.
Узнать, что происходит
Спросите о проекте, вместо того чтобы листать старые чаты.
Что сейчас открыто в Istok по этому проекту?
Открыто 3 задачи, 2 заблокированы. По #20 идёт активный запуск Codex; #19 ждёт #10.
Что было с задачей 18? Кто над ней работал и почему не удалась первая попытка?
Что записывает Istok: ничего. Агент только читает задачи, их историю и запуски. То же самое видно в веб-интерфейсе или в терминале через istok task list и istok task show 18.
Продолжить в новой сессии
Новый чат ничего не знает о старом. Укажите ему задачу.
Продолжи задачу 20.
Продолжи незаконченную работу над повторами платежей.
Что записывает Istok: агент читает заметки о прогрессе и прошлые запуски и продолжает работу. Если его предыдущая попытка ещё открыта, он восстанавливает этот запуск; если нет — снова берёт задачу, и начинается новый запуск со свежим контекстом.
Запомнить правило
Если вы поправили агента и хотите, чтобы поправка сохранилась, скажите об этом прямо.
Запомни для этого проекта: поля публичного API пишутся в snake_case.
Сделай правилом: каждое изменение API проверяется тестами API.
Что записывает Istok: запись контекста — решение, ограничение или инструкцию. Инструкции получает каждый следующий запуск, остальные записи доставляются, когда подходят к задаче. Подробнее — в разделе Правила и знания проекта.
Закончить с доказательствами
Инструкции и так требуют от агента проверить результат перед закрытием задачи. Но вы можете прямо сказать, что считать доказательством.
Прогони все тесты через Istok и закрой задачу, только если они пройдут.
go test ./... прошёл (проверка записана). Запуск завершён успешно, задача 18 выполнена.
Что записывает Istok: проверку с командой, результатом и выводом, привязанную к запуску. Задача закрывается со ссылкой на этот запуск и проверку, так что за «готово» стоят доказательства. Если проверка не прошла, неудача остаётся в истории, а задача — открытой.
Если проверять нечего, например при правке документации, агент должен явно объяснить, почему закрывает задачу без проверки. Эта причина тоже записывается.
Передать работу другому агенту
Попросите текущего агента оставить задачу в порядке, а потом запустите другого.
Запиши, что ты выяснил по задаче 18, и прекрати над ней работать. Дальше её возьмёт Claude Code.
Первый агент добавляет заметку о прогрессе или комментарий и завершает свой запуск — задача освобождается. Затем скажите другому агенту:
Возьми задачу 18 в Istok. Сначала прочитай, что выяснила прошлая попытка.
Что записывает Istok: второй запуск той же задачи под новым исполнителем (claude). Обе попытки со своими итогами и проверками остаются на странице задачи. Про идентификаторы и прерванные запуски — в разделе Несколько агентов в одном проекте.
Если агент забывает про Istok
Иногда агент начинает писать код, не создав задачу. Обычно не хватает одного из трёх:
- MCP-сервер не подключён. Проверьте командой
/mcpв Claude Code или в настройках MCP вашего агента. - Проект не зарегистрирован. Выполните
istok project listили попросите агента зарегистрировать проект. - Инструкций нет или они слишком слабые. Агент не знает, когда пользоваться инструментами.
Чтобы поправить его на ходу:
Используй для этого Istok: найди или создай задачу, возьми её в работу и запиши проверку перед тем, как закончить.
Если это повторяется, замените короткий блок из быстрого старта этой подробной версией в глобальных инструкциях (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md или User Rules в Cursor):
## Работа с Istok
Istok — основной источник долговременного состояния проекта для нетривиальной работы в репозиториях, зарегистрированных в Istok.
Используй MCP-инструменты Istok как основной интерфейс для состояния проекта, задач, контекста, запусков, проверок и поиска по репозиторию. Переходи на CLI Istok, только если MCP недоступен или не даёт нужной операции, и в этом случае предпочитай структурированный вывод.
### Перед нетривиальной работой
1. Определи текущий репозиторий или корень проекта.
2. Найди проект в Istok. Если подходит несколько проектов, используй самый конкретный. Никогда не переключайся молча на другой проект.
3. Если проект зарегистрирован, загрузи его включённые инструкции и используй ограниченный контекст, который Istok собирает для задачи. Не загружай разом весь сохранённый контекст и все знания.
4. Проверь существующие задачи, если работа уже может быть оформлена задачей.
Если репозиторий не зарегистрирован, сообщи об этом пользователю, не регистрируй его автоматически и продолжай без Istok, пока пользователь не попросит его зарегистрировать.
### Задачи
Создавай задачу для новых функций, исправлений ошибок, рефакторинга, миграций, исследований и других нетривиальных изменений. Не создавай задачи для вопросов, объяснений, мелких правок и быстрого чтения кода.
1. Используй подходящую задачу или сам создай узкую, не дожидаясь просьбы.
2. Возьми задачу в работу и веди текущую попытку в запуске.
3. Записывай заметный прогресс, блокеры, зависимости и решения по ходу работы.
4. Проверь результат и запиши команды, результаты и подтверждения.
5. Закрывай задачу только после того, как результат реализован и проверен. Одной реализации недостаточно.
### Контекст и знания
Следуй включённым инструкциям проекта, которые возвращает Istok. Используй контекст для коротких долговременных решений, ограничений и соглашений. Используй знания для более длинной актуальной информации — заметок об архитектуре, runbook'ов: находи их через каталог или поиск и читай только то, что относится к делу.
Извлекай знания в черновик с указанием источника, сверяй с текущим кодом, записывай ревью и утверждай только после ревью. Заменяй знания, которые устарели.
Никогда не записывай управляемое Istok содержимое в корень проекта. Не копируй состояние активных задач в TODO-файлы, планы или документы со статусом, если пользователь не просит.
### Поиск и завершение
Предпочитай поиск и граф Istok для поиска кода, но сверяй детали с текущими исходниками перед изменениями.
Никогда не утверждай, что проверка прошла, если она не была успешно выполнена. Если какую-то проверку выполнить не удалось, скажи об этом, а не выдавай работу за полностью проверенную. Держи Istok в актуальном состоянии, чтобы пользователю не приходилось делать это самому.Если в репозитории все участники должны работать по одному процессу, можно также закоммитить сокращённую версию этих правил в AGENTS.md или CLAUDE.md проекта.