okf-notebooks

Пресет dev-project: ведение проекта и разработка

Ведение проекта и разработки: глоссарий, ADR, спеки, тикеты, исследования, баги

Готовый пресет для блокнота, в котором команда и агенты ведут знания о программном проекте. Типы покрывают глоссарий и ADR, спеки и тикеты, исследования, прототипы, разбор багов и ретроспективы. Файл: presets/dev-project.yaml.

Подключение

В config.yaml укажите каталог с пресетами (в Docker он лежит рядом с конфигом, например /config/presets):

presets_dir: ./presets

Создайте блокнот:

uv run okf-notebooks notebook create my-project \
  --description "Разработка my-project: глоссарий, решения (ADR), спеки, тикеты, исследования и баги" \
  --scope "Устойчивые знания о проекте: термины, ADR, спеки, тикеты, исследования, баги. Не писать личные заметки" \
  --preset dev-project

Каталог пресетов читается при каждом обращении, перезапуск не нужен. Если YAML пресета сломан, он молча пропускается и --preset dev-project скажет «unknown preset»: проверьте файл yaml.safe_load-ом.

Типы

ТипКаталогЧто хранитОбязательные поляstale_after
Projectprojects/что за проект, как запускать и тестировать—180d
Termterms/запись глоссария: определение без деталей реализации, avoid — слова, которых надо избегать——
Decisiondecisions/ADR: контекст, решение, альтернативы, последствияdecided—
Specspecs/постановка: проблема, решение, user stories, вне скоупа—365d
Tickettickets/задача или баг с брифом, блокирующие тикетыcategory, triage90d
Researchresearch/находки по вопросу, каждый факт со ссылкой на первоисточникquestion180d
Prototypeprototypes/вопрос, что сделано, что выяснили, вердиктquestion90d
Bugbugs/симптом, воспроизведение, причина, фикс и регрессионный тестsymptom—
Retroretros/ретроспектива сессии: что мешало агенту и что менять——
Playbookplaybooks/повторяемая процедура: релиз, деплой, настройка—180d

Значения triage в Ticket — роли needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix; category — bug или enhancement.

Как это работает с агентами

  • Агент находит пресет сам: инструмент presets_list возвращает имя, описание («для чего подходит») и типы всех пресетов, включая этот.
  • Поля status и verified ставит человек (веб-интерфейс или CLI): всё, что пишет агент, остаётся draft, пока вы не проверите. Поэтому состояние тикета хранится в triage, а не в status.
  • Устаревание по stale_after помечает заметку в поиске как stale: исследования и прототипы быстро теряют актуальность, ADR и термины сами не устаревают.
  • Добавьте в AGENTS.md проекта строку вроде «решения, спеки и исследования записывай в блокнот my-project, тип выбирай по описанию типа в notebook_describe» (блок правил: okf-notebooks print-agent-guide).

Свой вариант

Скопируйте presets/dev-project.yaml, переименуйте и поправьте типы: правила, лимит в 12 типов и формат описаны в presets.md.

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