Правила и знания проекта

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

И правила, и знания хранятся в базе Istok, а не в репозитории. Ваши README, AGENTS.md и документация остаются как есть.

Правила: сохранённый контекст

Правило — это короткая запись контекста: соглашение, решение, ограничение или постоянная инструкция. Проще всего добавить его, сказав агенту.

Запомни для этого проекта: поля публичного API пишутся в snake_case.

Добавь инструкцию: изменения API нужно проверять тестами API.

Агент сохраняет запись с видом: note, decision, constraint или instruction. Из терминала то же самое выглядит так:

istok context add "API naming convention" --kind decision \
  --body "Public API fields use snake_case."

Чтобы посмотреть, что сохранено в проекте, выполните istok context list или попросите агента перечислить правила проекта.

Когда правило попадает к агенту

У каждой записи есть режим доставки — он решает, когда агент её получит:

Всегда (always) — запись получает каждый запуск. Инструкции по умолчанию доставляются так. Делайте их короткими: они занимают место в каждом запуске.
Когда подходит (ranked) — Istok сравнивает запись с названием, описанием, критериями и заметками задачи и добавляет самые подходящие. Это режим по умолчанию для заметок, решений и ограничений.
Только по запросу (manual) — запись никогда не добавляется автоматически. Подходит для длинных заметок, которые нужны только в отдельных задачах.

Сохрани заметки о миграции старого биллинга, но выдавай их только по моей просьбе.

У инструкций также есть приоритет от critical до low, он задаёт их порядок. У записи может быть дата пересмотра, срок действия или ссылка на более новую запись, которая её заменяет, — так старые правила не задерживаются.

Контекст, который получает агент, ограничен по размеру: 16 КиБ сохранённого контекста и 32 КиБ кода, всего 48 КиБ. Если записи с режимом always перестают помещаться, взять задачу не получится: Istok сообщит, какие записи мешают, а не выкинет их молча. Подробности и флаги — в справке по istok context.

Чтобы выключить инструкцию, не удаляя её, попросите агента её отключить или выполните istok context disable.

Знания: подробная документация

Знания — для материалов, которые слишком длинны, чтобы отправлять их с каждой задачей: как устроен процесс возвратов, почему заказы используют UUIDv7, как ротировать ключи. У каждой заметки есть вид: architecture, domain, decision, runbook или note.

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

Обычно знания создают в конце исследования:

Оформи то, что ты узнал о процессе возвратов, как черновик знаний и укажи эту задачу как источник.

Ревью перед тем, как на знания можно опираться

Новая заметка — это черновик (draft). Актуальной (current) она становится и появляется в сводках только после того, как кто-то её проверит и утвердит:

Прочитайте черновик: istok knowledge show ID или попросите агента его показать.
Сверьте его с кодом и запишите ревью с пометкой, что вы проверили.
Утвердите заметку как актуальную.

istok knowledge review ID --expected-revision 1 \
  --note "Checked against internal/refunds on main"
istok knowledge promote ID --expected-revision 2

Ревью можно поручить агенту, которому вы доверяете, но пометка о ревью записывается в любом случае. Актуальные заметки нельзя редактировать. Когда факты меняются, новый проверенный черновик заменяет старую заметку, а та остаётся доступной для чтения как история.

Знания можно просматривать в веб-интерфейсе на странице проекта Knowledge или командами istok knowledge list и istok knowledge search. Чтобы получить заметку в виде файла, используйте istok knowledge export — она запишет её по указанному вами пути.

Проверить, что увидел агент

Если агент проигнорировал правило, выясните, получил ли он его вообще.

До запуска: istok context preview 18 показывает, что получит агент, если возьмёт задачу 18: режим доставки и оценку каждой записи, а также сколько бюджета занято. Запуск при этом не создаётся.
После запуска: откройте запуск в веб-интерфейсе и выберите вкладку What the agent saw. Там точные записи, код и сводка знаний, сохранённые для этого запуска.
Общее состояние: istok context doctor сообщает о записях с истёкшим сроком, заменённых и ожидающих пересмотра, о слишком больших записях и об инструкциях, которые не влезают в бюджет.

Как контекст собирается изнутри, описано в разделе Контекст и знания.