⚛️ Атомарные Duo файлы


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

К сути. Сейчас обсуждаем концепцию "атомарных duo файлов". Это файлы, документирующие те или инце концепции в системе, причём построенные строго по определённым правилам:

- каждый duo-файл описывает только одну концепцию, отсюда в названии "атомарные"
- duo файлы "работают" в паре: арх-файл + гайд-файл
- первый хранится в папке architecture/ - арх-файл
- второй хранится в папке guides/ - гайд-файл
- парные файлы содержат аннотированные ссылки друг на друга
- арх-файл содержит высокоуровневое декларативное описание ЧТО и ПОЧЕМУ, архитектурную концепцию
- гайд файл описывает КАК ИМЕННО, операционные инструкции и детали

Такими файлами у меня в мемори банке описаны многие элементы фич, сущности в системе - от окружений для разработки (app stages) до визуального стиля ui-system

❓ Зачем атомарность? Почему только одна концепция?

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

Единственная концепция - удобный способ обеспечить принцип Single source of truth. Это важно для:
- группировки концепций в одном месте (полезно для внимания модели)
- упрощает обеспечение непротиворечивости контекста

Важная часть качественного контекста - его непротиворечивость. Если по вашим документам сведения "размазаны" по нескольким файлам, то с многословностью моделей вы легко получаете немного разные сведения об одном и том же! А после эволюции этого контекста могут появиться противоречия, что очень вредит качеству.

❓ Почему делим на 2 части?

Когда мы хотим дать агенту некоторые общие сведения о чем-либо, мы можем "положить" ему только арх-файл. Если агенту нужно будет работать с этой концепцией, мы добавляем гайд-файл.

Получается удобная управляемая схема.

❓В файле не одна концепция

Некоторые файлы неизбежно усложняются! например, система тестирования с описанием разных типов тестов. Процесс носит естественных характер с развитием вашей системы, нужно просто контролировать ситуацию, и когда она уже становится проблемной - делать рефакторинг.

❓А если никак не обойтись одной концепцией?

Я делаю составные концепции. Например, та же система тестирования может содержать групповой файл, который описывает систему тестирования в общем виде, и отдельные файлы про юнит тесты, e2e тесты и любые другие виды тестов, которые вы применяете.

❓ Сейчас модели получают большие контексты - зачем эта микро оптимизация?

Действительно, выходят модели с контекстами 400к токенов и 1м токенов. Но помимо контекста остаётся ещё механизм внимания модели, который тоже "не резиновый".

Чем меньше нерелевантных задаче деталей "отвлекают" модель, тем выше будет качество работы.

Этот аспект становится важнее с ростом системы.


#post
@deksden_notes

🧩 Управление агентным контекстом


От чего зависит качество работы агентов? Почему в некоторых ситуациях модели решают задачу здорово, а иногда - ошибаются и косячат?

Причин, конечно, масса, но одна из них - контекст. Я уже затрагивал эту тему в заметке "Когда возможностей модели не хватает" (https://t.me/deksden_notes/11)

Традиционный контекст модели

⚖️ Как часто бывает, важен баланс.

Если вы не сообщили модели важную для её работы информацию, мы получим галлюцинации и некачественно сделанную работу. Например, модельне получила Api вашего модуля и знает только сигнатуру вызова. Тогда скорее всего при конструировании нового вызова она выдумает значения для неизвестных ей параметров, и вы meltnt фиксить это на этапе компиляции/тестов.

Но и если мы "перекормили" модель информацией, она в ней потеряется. Если вы скинули весь файл документации десятков методов api ради одной функции - тоже ничего хорошего, размываем внимание модели.

🧩 Вот и получается, что подготовка контекста в чем то напоминает сбор паззла, причём с довольно пристальным рассматриванием каждого кусочка - подходит ли он, или нет.

Получается, что с моделями ситуация немного проще: собрал контекст, подготовил промпт - получил ответ. Если ответ не устраивает, работаем с контекстом: переформулируем запрос, добавляем/убираем контекст. Инструменты типа prompt tower/repomix и товарищи делают этот процесс весьма управляемым даже с огромными контекстами.

Агентский контекст

Формирование агентского контекста имеет некоторые особенности, как упрощающие, так и усложняющие жизнь.

☽ С одной стороны, формирование контекста несколько проще: за счёт проактивной работы агента он в состоянии сам себе собирать конекст по своему разумению.

☾ С другой стороны, такая проактивность значительно снижает детерминированность агентных процессов. Если вы ведёте процесс в основном агенте, без использования схемы "оркестратор - агент", то легко получаем разное качество исполнения одного и того же эатпа в зависимости от предыдущей активности. Правило "мусор на входе - мусор на выходе никто не отменял".

😎 Поэтому использование специализированных агентов - это важный прорыв в обеспечении детерминированности: мы начинаем с пустого контекста, и можем сформировать его значительно более определённым!

Наверное вы уже понимаете, что концепция duo файлов (https://t.me/deksden_notes/49) как раз ложиться как инструмент "сборки" паззла агентского контекста.

▶️ Следующий момент: при формировании контекста агента мы можем воспользоваться анонсированными фичами нашего мемори банка - использовать аннотированные ссылки в промпте агента, причём ссылку можно делать условной (читать файл при необходимости). Тогда агент в состоянии сам решить - нужна ли ему эта информация или нет для решения задачи. Выходит значительная экономия контекста.

Индексные файлы агенты начинают использовать по-умолчанию.

🤞 Надеюсь, и у вас паззл постепенно начинает складываться - как из всех озвученных концепций начинать строить эффективно работающие системы

#post
@deksden_notes

📇 Главный индексный файл мемори банка

Чтобы агентначал использовать хранящиеся в мемори банке сведения, необходимо чтобы он о нем каким то образом узнал.

Так как каждая сессия агента - "как в первый раз", для знакомства агента с мемори банком там есть главный индексный файл. Статься про индексные файлы тут - (📇 Главный индексный файл мемори банка

Чтобы агентначал использовать хранящиеся в мемори банке сведения, необходимо чтобы он о нем каким то образом узнал.

Так как каждая сессия агента - "как в первый раз", для знакомства агента с мемори банком там есть главный индексный файл. Статься про индексные файлы тут - (https://t.me/deksden_notes/46)

Это как раз один из тех индексных файлов, который "кастомный", нестандартного формата. В файле содержится "карта" мемори банка в виде набора аннотированных ссылок на все ключевые файлы мемори банка, с описанием всех папок. Для каждой папки есть ссылка на её индексный файл.

Про аннотированные ссылки тут: https://t.me/deksden_notes/47

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

Первоначальная загрузка (Прайминг)

Как происходит загрузка мемори банка? Конечно, можно просто прописать в CLAUDE.md - "Загрузи .memory-bank/index.md"

Но я предпочитаю давать явную команду, поэтому у меня есть файл кастомной слеш команды "/mb", который поддерживает аргументы. Он грузит мемори банк

Примерное содержание:

Вот твоё <ГлавноеЗадание>
$ARGUMENTS
</ГлавноеЗадание>

- загрузи содержимое файла ".memory-bank/index.md" и выполни инструкции в нем

#post
@deksden_notes

⚛️ Генезис: Duo - файлы


Немного теории

Когда мы с вами обсуждаем некие подходы и приёмы, рассматраиаемый подход доносится в форме: "делайте Х, получите Y".

Но что отличает информацию от знаний? Глубина понимания, владения и осознавания - как именно эта информация встраивается в реальность.

И как достигать глубины понимания информации - работать с ней! Например, провести первичное позиционирование.

Когда видим "делайте Х", важно понимать - в каком контексте обсуждается утверждение. При каких условиях это работает.

Также будет здорово понимать историю вопроса - а что привело к понимают, что надо "делать Х"? А какие опции ещё есть, помимо "делать Х", что будет если делать немного/сильно иначе?

И если мы знаем ответы на подобные вопросы, то наше владение темой усиливается, и информация из категории простого набора токенов начинает перетекать в категорию знаний.

Фиксирует же процесс превращения информации в знания только опыт.


К нашему кейсу

Итак, я могу сообщить только ифномрацию. Давайте попробуем дополнительно проработать концепцию "duo" файлов, чтобы чуть чуть приблизит её к знаниям.

▶️ Итак - откуда возникла потребность в duo файлах? очевидно, что из необходимости хранить библиотеки знаний о проекте.

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

Вызод: дробление документации на максимально чёткие топики, что получило отражение в "атомарном" файле. Так проще заставить модель быть лаконичной.

▶️ Дополнительный плюс: контекст под задачу можно собрать только из нужной информации, выбрав интересующие концепции.

▶️ Зачем разбивка на 2 файла? Это минимальная вариация на тему "Оглавление + саммари" - "текст". То есть "общий обзор" - "детали".

такая разбивка позволяет дать либо обзорный файл там, где требуется просто упомянуть концепцию, либо добавить гайдфайл для деталей.

▶️ А почему только 2 файла если мы арх-файл это "оглавление"? Потому что мы описываем одну концепцию, и обычно не требуется большого массива данных в гайдфайлах.

▶️ Почему в двух разных папках? Дополнительная семантика - модель видит папку Architecture/ в пути к файлу, и у неё уже складывается определённое осознание типа контента в ней. Аналогично про guides.

Я проводил эксперимент когда все файлы в папке duo/ - тоже норм, редактировать удобнее когда файлы рядом. Немного больше файл index, но так у нас их будет два, значит не недостаток. Сам список файлов немного засорён парами файлов, не так очевиден список концепций - но всегда можно смотреть на более удачно отформатированный индексный файл, чем в файловую систему.

В общем, можно и так, на применимость подхода особо не влияет.

#post
@deksden_notes

🙇‍♂️ Идеальный оркестратор


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

Оркестратор - это штука, которая будет пускать workflow.

Надо помыслить о важных фичах, сгруппируем.

FR0. Модель:

* есть workflow, оно состоит из этапов (stage)
* есть task - это запущенный workflow
* есть step: это прохождение этапа workflow в task


FR1. Поддержка логики выполнения workflow:

1.1) обычный этап: когда делаем подряд действия,
1.2) условный этап: может перейти по одному из маршрутов, агент решит по какому, переходить можно к любому шагу воркфлоу (так можно сделать циклы)
1.3) "вызов" воркфлоу - переходим к старту указанного воркфлоу, а потом возвращаемся обратно
1.4) fan-out / fan-in: шаг может порождать "пучок" параллельных шагов из текущего контекста, каждый со своим контекстом; далее по процессу есть этап fan-in

FR2. Каждый шаг:

* это будет отдельный вызов claude -p
* контекст конструируется под шаг: выбираем чего берём от предыдущих шагов
* поддержка обмена файлами
* структурированные статусы завершения: агент делает структурированный документ про шаг (как иногда в functional calling есть схема на возвращаемое значение)
* структурированных вход: формируем параметры вызова по схеме (как в function calling есть схема на параметры)
* observability: смотреть с каким промптом стартовали, логи выполнения, с чем финишировали.
* смотреть папку задач этого шага
* наверное нужен плагин на вход и выход с ts кодом для произвольной обработки стартового контекста и итогов равершения

FR4. Хотелки по архитектуре

* асинхронное relatime
* простой scaling доступных workers
* теоретическая поддержка скелинга на другие виртуалки/удалённые машины - копируем контекст, пускаем шаг


Такая штука сильно поможет в сложных воркфлоу

Я что то упустил?

Upd: playback в явном виде: берем любой процесс, смотрим шаг, и с этого места запускаем процесс снова (бранчинг-как в аи студии)

#post
@deksden_notes

🧩 Модель С4

Начнём, пожалуй, потихоньку к архитектурным вопросам накидывать!

Сначала поговорим про модель С4: на мой взгляд эта модель довольно удачно позволяет декомпозировать архитектуру программного продукта и концептуально удачно подходит для работы с агентскими системами.

Суть подхода C4 - в декомпозиции архитектуры на 4 уровня:

# L1: System ©ontext : Контекст системы - уровень взаимодействия системы как чёрного ящика с внешним миром. На этот уровень попадает product.md из меморибанка, описывающий в том числе что за продукт и для кого.

# L2: ©ontainers : контейнеры - крупные строительные блоки, из которых состоит система - подсистемы. Например, frontend, api.

# L3 : ©omponents : компоненты - логические единицы внутри контейнера, например auth controller.

# L4 : ©ode : код - самый детальный уровень, сам код или детальный документ планирования реализации (диаграммы классов, ERD).

Как я использую данный подход в планировании :

- На L1 у меня product.md мемори банка + эпики. Я специализирую эпики (EP-) как единицы доставки пользовательской ценности, из совокупности эпиков и рождается product.

- на L2 : работаем с сущностью подсистемы (systems) - со своими контрактами; реализуются специальными техническими эпиками (TE-).

- на L3 : фичи и концепции, фича - конктерный компонент, реализуемый внутри подсистемы, а концепции мы в duo файлах фиксируем, с архитектурными паттернами и решениями.

- на L4 : план реализации, implementation plan для каждой фичи, получается в результате многоэтапной стадии планирования. Используется как подробная и детальная инструкция для агента.

Чего нету в подходах C4 : нет моделирования данных, нет описания динамического поведения (Sequence Diagrams например).

Также важно оставаться в рамках разделения на Problem Space и Solution Space:
- Problem Space - описывает ЧТО система должна делать, спеки системы
- Solution Space - описывает КАК это реализовано.

‼️ Как вы понимаете - мы сейчас говорили про Solution Space. На мой взгляд, модель C4 хорошо структурирует Solution Space - довольно просто, элегантно, концептуально, логично, но ограничения подхода надо понимать!

❓Какую роль играет C4? Это подход к архитектурному моделированию который используется?

Нет. Это "концептуальный взгляд" на систему документации в Solution space. Этот взгляд помогает понимать роль разных артефактов в системе, и какое значение они имеют. Само по себе проектирование системы прямо на C4 не завязано, это не методика как проектировать. Но смыслы, которые стоят за теми или иными артефактами системы, понимание таких концепций проясняет, как проясняет и соотношение, edpre друг с другом, взаимодействие этих понятий.



#post
@deksden_notes

🧩 Solution Space vs Problem Space


Пожалуй, вынесу это как отдельную заметку. Важно понимать, что ВСЯ документация / спеки системы концептуально делится на Problem Space и Solution Space.


▶️ Problem Space : это "мир" требований к системе, мир "заказчика", он описывает бизнес-логику, ЧТО мы строим. Никаких деталей реализации тут нет, только потребности, ограничения, цели

▶️ Solution Space : это уже мир инженера (видимо, агента?) - описываем КАК строим, язык технологий, структур, реализаций.

Важно понмиать, что это фундаментальное разделение. Много методологий построено на нем. Например, эта концепция - одна из краеугольных в Domain Driven Design. Если мы упоминули о C4 для концептуального структурирования Solution Space, то DDD будет концептуально структурировать Problem Space.

❓ Как применять Solution Space и Problem Space в конкретной работе?

Никак. Это также концептуальное понятие, важное для правильного взгляда на вещи. Один из способов, как сказать про разделение ЧТО и КАК.

#post
@deksden_notes

🐙 Jules в очередной раз обновился


- Теперь публиковать код можно не дожидаясь окончания шага - а в любой момен
- Размер диска VM каждой задачи увеличили до 20Gb


Гугл активно развивает продукт! такие бы темпы для Gemini CLI. Видимо, гугл видит приоритеты иначе

https://jules.google/docs/changelog/

#news
@deksden_notes

🔥 ССstatusLine

Напомню, о сабже - кто ещё не в теме, обязательно посмотрите: небольшая, но сильно полезная штука про информацию в статусной строке (чуть ниже поля ввода)

Кмк, это must have для любого пользователя СС

Вот тут можно подробнее про неё прочитать:

https://t.me/kdoronin_blog/897

https://t.me/the_ai_architect/129

Или сразу с хаба брать:

https://github.com/sirmalloc/ccstatusline

Не забываем ставить звезды автору!

#link
@deksden_notes

🦄 Vibe Coding мифы и "охотничьи рассказы"

Начну делать пополняемый пост, который планирую дополнять по мере вспоминания кейсов.

Часто встречаюсь с тезисами, что модели / ИИ агенты делают что то плохо, не умеют, не могут, не тянут и прочие тейки. Напоминайте кейсы, будем разбирать и пополнять пост. "Охотничьи рассказы" - потому что все кейсы основаны на практике, хотя для наглядности изложения могут быть чуть-чуть переформулированы.

Некоторая часть этих тейков - не соответствует фактической действительности, и является лишь SKILL ISSUE.

🛑 1️⃣ ИИ агент слабо соображает: он забывает про ранее сгенерированный код, делает кучу дубликатов, рождает кучу функций примерно про одно и то же. Это все потому что ИИ пока не тянет, и работать может только под контролем программиста.
- разбор: https://t.me/deksden_notes/60

🛑 (k-2) ИИ пишет многословную документацию, и загромождает мемори банк кучей лишней информации, и он через некоторое время превращается в большую груду клочков сведений.

🛑 (... to be continued)

Ранее я уже писал про некий общий кейс, но это все таки немного другое было. https://t.me/deksden_notes/11

Тут я планирую каждый конкретный кейс разбирать.


#post
@deksden_notes

🔧 Разбор vibe-кейса 1️⃣


▶️ Симптомы:

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

ℹ️ Объяснение:

Такое часто бывает, когда ИИ агента используют как ИИ ассистента (привет, курсор!), но "входят во вкус" и поручают ему более серьёзные задачи, чем поправить текущий файл в буфере ИДЕ.

Что происходит? ИИ-ИДЕ даёт иллюзию, что ИИ агент отлично понимает кодовую базу - инструменты индексации кода "фоном" формируют нужный контекст. Проблемы начинаются, когда эти "умные инструменты" не сообразили как автоматически собрать контекст для вашей более сложной чем тривиальной задачи - что данная функция уже реализована в соседнем модуле но с другим именем и не совсем похожими параметрами (чтобы эмбеддинги не увидели сходства), что для модуля нужно использовать слой базы данных из соседней папки (потому что использование бд прямо не было указано в промпте, но предполагалось по дизайну системы) и тп. Так как работа этих инструментов непрозрачна, то сюрпризы могут случаться неожиданно.

Для ИИ агентов без индексации (типа СС - Claude Code, или Gemini Cli, Codex Cli) "непонимания" агентов можно различить чуть проще, но оно носит такую же природу - связи внутри вашей системы не стали для агента очевидными.


🔧 Решение:

Общий принцип простой: обеспечить агента качественным контекстом для его задачи. Агент должен получить в контекст или "знать" всю информацию для выполнения его конкретной задачи. Понимание в какой части системы он работает, какие модули затрагивает, какие контракты у этих модулей, какие паттерны взаимодействия между ними, какой стиль кода, где смотреть примеры реализации похожей функциональности, где искать документацию на внешние зависимости.

Как видно - сказать просто, а как обеспечить на практике?

В целом, подход тоже не сложный: давать документацию/спецификации/ссылки. Я храню это все в формате мемори банка (много постов канала про разные техники - индексные файлы, аннотированные ссылки, etc).

Разбивайте процесс доработок на этапы : планирование - потом кодинг - потом верификация.

На этапе планирования - поручайте сначала изучать документацию полностью, искать все что относится к интеграции фичи в код.

При кодинге делайте работу по плану, но соблюдайте стили кодирования, паттерны системы. Каждая генерация кода должна финалится чем то типа typecheck / lint - неким алгоритмическим анализом корректности кода с помощью инструментов для конкретного языка.

Верификация - это когда вы сопоставляете план и фактический код. Крайне полезно делать.

Идеально будет к коду сделать тесты - но это уже более широкий вопрос, как планировать тесты в системе, чтобы соблюсти разумный баланс.

По итогам доработки НЕ ЗАБЫВАЙТЕ обновлять информацию в мемори банке.

При таком подходе можно генерировать много кода для достаточно сложных систем без всяких проблем. Но, как вы видите - все это требует подробных инструкций и некоего ПРОЦЕССА. Процесс можно для начала оформлять слеш командами, чтобы не писать длинные промпты каждый раз. В идеале - нужен агентный воркфлоу.

Поэтому AI SWE - это спеки, планирование, процессы. Вайб? Ну - от результата: когда по вашим хотелкам в итоге генерируется сложная крутая система - это ПЛЮС ВАЙБ))


#post
@deksden_notes

⚒️ В полку Ai SWE Tools пополнение - Qoder


Наши азиатские товарищи от Алибабы выпустили довольно интересный инструмент - очередной форм VSCode со своим видением агентской ИИ разработки.

На машине пора чтобы какой то runtime VS code держать для оптимизации - целый зоопарк уже в этом семействе развелся! Kiro, Trae, Qoder, Cursor, Windsurf, сам VS Code ...

Ну, нынче - про Qoder - важных фич отмечу несколько, про них в блоге написали:

- Quest mode: разработка через Specs First - сначала план, потом реализация;
- Code Search: эмбеддинги + граф
- Long Term Memory + evolution : их тейк на память для агентов
- еще RepoWiki есть, навороченное

Все фичи выглядят правильно и логично.

▶️ Quest mode: то, что для ИИ агентов нужны спеки теперь в индустрии, видимо, стало очевидным фактом. Kiro вышло с поддержкой спеков, теперь тут предлагают сначала план делать. Не поспоришь! На чем базируется план, пока не очевидно, надо поизучать - будем разбираться.

▶️ Code Search: qoder индексирует код кастомными эмбеддингами на своих серверах. Обещают быстро и приватно, ага. В дополнение к эмбеддингам локально строится граф из кода и доки.

Когда пользователь задаёт вопрос, система сначала эмбеддингами ищет релеватные сущности, а потом из графа обогащает связанной инфой. Видимо, какие ветки графа тянутся - будет зависеть от задачи.

Реализация на словах выглядит вполне логичной и рабочей.

▶️ Long Term Memory + Self Evolution: самая интересная, кмк, часть их подхода. Про неё напишу отдельно попозже - требуется внятный разбор, потому что много механизмов работы с памятью проекта реально реализовано! Респект.

Кто хочет почитать в оригинале - можно у них в блогах тут: https://qoder.com/blog/long-term-memory

▶️ RepoWiki: система строит по вашему репозиторию целый вики, со схемками / диаграммами в mermaid и довольно подробный. Источники тоже приводит.

Очень массивная штука, не совсем ясно где и как используется системой - но почитать её самому вполне любопытно. Обещают обновлять при работе с проектом, но там есть нюансы которые могут сбой вызвать. Я так понимаю, надёжнее как нибудь ночью обновлять это

Собирается долго, в доках указано - 2 часа для проекта в 4k loc.

☝️ В общем, решение довольно интересное, со своими фишками - их изучим обязательно.

https://qoder.com/

#post
@deksden_notes

🆕 Новый релиз СС


Version 1.0.88:
• Fixed issue causing "OAuth authentication is currently not supported"
• Status line input now includes exceeds_200k_tokens
• Fixed incorrect usage tracking in /cost.
• Introduced ANTHROPIC_DEFAULT_SONNET_MODEL and ANTHROPIC_DEFAULT_OPUS_MODEL for controlling model aliases opusplan, opus, and sonnet.
• Bedrock: Updated default Sonnet model to Sonnet 4


▶️ Почему пишу? примечательные пункты вижу - exceeds_200k_tokens, controlling model aliases opusplan, opus, and sonnet.

🤞 Прям навевает на мысль, что 1m контекста в том или ином виде появится, надеюсь что и в подписке! Было бы интересно потестить

https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md


#link
@deksden_notes

🧠 LLM Neighbors - Vol.11
🗣Pitch and workshop
по традиции в Сб 23 августа 18:00 (UTC+3) (отметься чтобы записаться на звонок )

✍️Agenda:
- 18:00-18:30 ~ 30 min - small talk, think big =)
- ~18:30 - 21:00 Guro Bokum - Liman AI Agentics
(30 min coffee break☕️ && || сократовские беседы)
- ~ 21:30-до ночи до упора) - Глеб Кудрявцев - Shotgun

Кудрявцев Глеб
CEO Карьерный Цех, microboard.io, ex CPO Skyeng.
Разработчик. Эксперт в AI-assisted разработке. Автор популярного приложения для программирования с ИИ — Shotgun (1500 звезд на гитхабе).
Область интереса — программирование агентов, промпт-инженерия и подготовка контекстов (в т.ч. RAG, Knowledge graph и т.д.), b2b/b2c продукты на основе AI.
После успеха Шотгана, решил расширить его возможности и сейчас делаю "взрослый" suite для агентского кодинга:
— Автоматизированное составление онтологии проекта с помощью скана репозитория и релевантных документов
— Собственная система агентов для кодинга
Сейчас это напоминает OpenAI Codex. Нахожусь в фазе активной разработки, делаю приложение с помощью него самого 🙂 Хочу поделиться опытом построения системы для кодинга, ключевыми проблемами и своим подходам к решению

Guro Bokum
Всем привет! меня зовут Гуро, я разработчик, работал в разработке и инфраструктуре в разных областях и языках (15+ лет)
сейчас хайпят агенты, и я последний год ими заниваюсь
за время работы над ними у меня накопились решения, которые я решил завернуть во фрейморк - Liman AI
это YAML декларативный фреймворк с костомным CE DSL, что-то близкое к кубернетес манифестам, где ты описываешь граф в виде нод, а они потом обходятся в зависимости от условий executor’ом
Вчера написал блог пост - как можно из коробки обернуть ваше апи в агента с помощью лимана (парсится делкрация OpenAPI и создаются нужные тулы)
https://www.liman-ai.dev/blog/2025-08-17_simple_openapi
Я хочу рассказать в субботу про фреймворк на реальном примере, и вот думаю про MCP сервер под claude code. Что думаете? Какой бы сервер мы могли сделать, чтобы поиграться на звонке? Делитесь идеями!

Ах да, Если будешь, пожалуйста: Отметься⚠️ в голосовалке!

Приходите, у нас как заведено - приветствуется проактивность и готовность делиться с другими практическим опытом
#meeting@llm_neighbors

Call link 1 min before event

📝 Список задач Claude Code - схема "ТРИ ВОЛШЕБНЫХ ПУНКТА"
1/2

Поделюсь приёмами, которые использую при сеансах "вайбкодинга".

Когда "все по науке", тогда после процесса проектирования агент часами работает над планами реализации и тестовыми стратегиями. Тогда вся его работа происходит по длинным воркфлоу, много этапов и все такое.

Но сегодня мы не про AI-SWE, а про "вульгарный" вайбкодинг)) Это - о кейсе, когда мы условно в "свободном" режиме допиливаем чего то с СС.

Для таких кейсов я действую следующим образом: обычно в режиме plan mode (переключается Shift+Tab) обсуждаю с агентом план действий.

У моего плана действий для вайбкодинг сессии есть ТРИ обязательных пункта: два в начале, один в конце.

1️⃣ Сначала я прошу сделать ЧЕК-ЛИСТ по выполнению текущего плана в корне проекта со всеми ключевыми деталями для кода и документации.

2️⃣ Следом я прошу через субагента внести изменения в документацию, обновить мемори банк: проанализировать текущие duo файлы по индексу, найти какие файлы нужно обновить/актуализировать, какиу удалить, какие дополнить. То есть для того плана, который я собираюсь реализовать, первым пунктом делается документация - docs first.

▶️ Далее идёт сам план, который мы разработали с агентом.

3️⃣ Последним пунктом плана я прошу взять чек-лист из файла, и запустить субагента на сверку фактических файлов кода и документации с чек-листом, проверить как все реализовано, и исправить недостатки.

Наверное, делать typecheck / linit / build - об этом не говорим, это общая гигиена при создании кода.

Тестовая стратегия - использовать минималистичный набор тестов только для core functionality.

❓ Зачем такие сложности?

Агент при длительном выполнении в основном потоке (тот самый вайбкодинг) может слегка забывать план, отклоняться в стороны, не сделать чего то, или "лениться". Чек-лист первым пунктом, когда план "свеж в памяти" агента - он помогает зафиксировать важные детали плана, чтобы потом быть "стержнем" при выполнении задуманного.

❓ Почему обновление мемори банка вторым пунктом? А не последним? логично было бы сначала сделать код, а потом все документировать!

Нет, не логично. И примерной по той же причине, что и чек-лист на первом пункте - агент пока ещё хорошо помнит план и его детали. В конце выполнения в контексте агента будет много всего, и документировать в таком "смурном" состоянии - затея не очень хорошая.

Если чек-лист важен чтобы агент ВЫПОЛНИЛ план с полными деталями, то документация на втором пункте важна чтобы агент ЗАДОКУМЕННТОВАЛ чего мы тут навайбкодили "на память" для последующего использования - что не менее важно. Вам ещё с этим кодом жить!

❓ Если в процессе постоянно говорить "сверяйся с чек-листом" - это поможет?

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


❓ А зачем тогда финальный чекап по чек-листу?

Как ни странно, агент регулярно упускает какие-то детали. Если его "стегали" по ходу дела возвращаться к чек-листу, то такого будет меньше - но полностью исключить не выходит.

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

❓ У агента же есть свой список задач! Зачем ему чек-лист?

Верно, но я "синхронизирую" список задач: когда нужно выполнить план, я прошу взять план и выполнить, и сохранить план себе в TodoWrite (это инструмент записи в список задач агента) - тогда агент часто берет прям структуру моего плана и буквально переносит его в свойс список задач.

Вот тут твиттерские нарыли, что агент постоянно возвращается к своему плану работы, буквально постоянно. Это говорит о пользе "синхронизации" нашего плана с планом агента:

https://x.com/vitransformer/status/1958135188749509016

Ну и напоминалки агенту никогда не помешают, поэтому напоминаем про чек-лист почаще!

(... продолжение: https://t.me/deksden_notes/65)

📝 Список задач Claude Code - схема "ТРИ ВОЛШЕБНЫХ ПУНКТА"
2/2

(начало тут - https://t.me/deksden_notes/64)

❓ А как же планирование с гемини?

Оно все ещё работает лучше, чем планировать с агентом - потому что с большим контекстом гемини все работает "сразу" и модель все видит, а агентом планировать - это надо проследить, чтобы контекст нужный "втянулся": при некотором опыте это несложно, но хлопот всяко больше.

Поэтому я люблю планировать с Гемини в АИ-Студии пока размер проекта позволяет, и вам советую! Схема действий аналогичная: просим гемини добавить эти же ТРИ ВОЛШЕБНЫХ пункта.

Дальше очищаем контекст, праймим задачу от Гемини через меморибанк "/mb {сюда_вставляем_задачу}". Тогда агент подхватит контекст мемори банка по индексным файлам, и приступит к задаче уже немного соображающий в теме.

❓ А как же агенты?

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

Поэтому такой флоу - это более примитивный вайбкодерских "подход", который да, грешен - встречается на практике.


❓ А почёму не использовать AI-SWE? Чтобы все правильно: сначала спеки, потом план реализации, потом кодинг и верификация.

Это, конечно, более правильный подход, на который я перевожу все свои проекты, но переход ещё не завершён. "Компиляция" проекта из спеков - более грамотная и продвинутая технология, которую я всячески развиваю. Но потребность в сеансах работы с агентом в неполностью готовых под AI-SWE проектах все ещё есть - поэтому и такие сеансы я стараюсь делать "по методике".

␄
#post
@deksden_notes

🧩 Memory bank для существующих проектов :: Реверс-проектирование и реверс-документирование в brownfield
1/2

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

Но что делать, если хочется использовать меморибанк с существующим проектом, для которого нет меморибанка? Это - территория brownfield, и она значительно сложнее greenfiled.

Ситуация внедрения меморибанка в существующий проект требует творческого подхода. О чем необходимо подумать при старте такого начинания:

- размер проекта: чем крупнее проект, тем сложнее задача создания меморибанка, который является "памятью" проекта: очевидно что для крупных проектов там должно быть очень много информации; документирование отдельных крупных систем порой может потребовать сопоставимых с разработкой с нуля количество усилий;

- наличие существующей документации: если она есть, структурировать её для ИИ агентов будет технической задачей; хуже когда документации нет, или она не точная, причём, согласно исследованиям, неточная документация вреднее её отсутсвия;

- документирование кода: jsdoc/docstrings в проекте уже составляют неплохую базу для ИИ агента;

- степень понимания проекта участниками: иногда есть реально работающие системы, которые НИКТО из сотрудников/подрядчиков не понимает полностью, потому что они долго эволюционно развивались, пережили ротации разработчиков, эволюцию бизнеса, меняющиеся требования, интеграцию с внешними системами - и все это в реальной жизни, без особой документации (которой иногда и не делали), со схемой работы в головах сотрудников (которые потом увольнялись без полной качественной передачи знаний). Такое и приводит к ситуации: система работает, но ПОЧЕМУ ИМЕННО ТАК - не известно достоверно никому; 

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

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

▶️ Базовый принцип: мы "строим" в меморибанке усровень абстракции "выше" кода, потому что именно этих уровней не хватает агентам для эффективной работы

▶️ Что за уровни? Тут на помощь приходят классические архитектурные паттерны (да, теперь мы говорим о ренессансе традиционного SWE, прости, agile!) - например, простым и практически удобным для применения будет паттерн C4, подробнее - https://t.me/deksden_notes/55

▶️ Верхний уровень L1 документировать просто - описываем что у нас за система, кто и зачем ей пользуется; концептуальная информация скорее, пректически - задаёт домент рассуждениям агентов;

▶️ L2 уровень очень важен: тут мы описываем крупные блоки вашей системы - назовём их подсистемами: databse, ui, api server, processing engine, - все что имеем; важно правильно выбрать "нарезку", чтобы это имело практический смысл. Например, если у вас огромный Api сервер, имеет смысл выделять в нем свои структурные блоки вроде аутентификации/авторизации, CRUD по модулям. "Крупность" нарезки блоков определяется так: фиче приложения желательно взаимодействовать с одним блоком - то есть, если "пользователь вносит заказ", то он взаимодействует с одним блоком базы данных. Так мы сможем в контекст агента положить всего один документ про подсистему БД "Заказы".

▶️ L3 Уровень - это фичи приложения, это "элементарные" блоки функциональности вашей системы. Делятся аналогично, по автономии: например, вы можете реализовать фичу "пользователь создаёт заказ в системе" отдельно от "пользователь редактирует заказ в системе". Самый многочисленный уровень для документирования. Про его сбор чуть далее.

▶️ L4: у вас уже есть, мы как раз строили мостик между L1 -> L4.

(... продолжение тут: https://t.me/deksden_notes/67)

#post
@deksden_notes

🧩 Memory bank для существующих проектов :: Реверс-проектирование и реверс-документирование в brownfield
2/2

(.. начало тут: https://t.me/deksden_notes/66)

Немного практики:

🔵 Нет смысла документировать очевидные из кода вещи: агент может прочитать и воспринять что написано в коде. Делать дублирование логики функций в документации особенной ценности не имеет и будет забивать контекст - агент будет читать и документацию, и код.

🔵 полезно вносить в мемори банк то, для сбора чего агенту нужно совершить несколько действий. Например: схему взаимодействия между модулями (кто кого и откуда вызывает), контракты подсистем, публичное api модулей, примеры и паттерны их использования

🔵 Отличную почву для дополнения меморибанков дают ошибки агента - когда он сделал что-то "не то". Это верный знак необходимости рефакторинга документации: отсутствие правильного контекста, или его качеством. Проверим что у агента документация была: индексные файлы, duo файлы. Проверяем - опирался ли агент на корректную документацию? противоречий или ошибок в документации не было? важные вещи документированы?

🔵 Используем агентов:
- собраем полную карту апи-роутов сервера;
- исследовать и документировать схему из БД и связанных файлов кода, "вытаскиваем" максимум мета-информации;
- описать существующий UI: перечень экранов, их структурных элементов; data test id атрибуты для тестирования; идентифицировать основные actions в интерфейсе;
- call graph: агент может составить схему взаимодействия модулей - какие функции/методы вызывают другие модули/функции; конечно, специализированные системы (типа qoder) сделают это лучше, но и простыми способами зафиксировать "соседние ветки" дерева зависимостей несложно и весьма полезно.

🔵 Самое сложное - это вытащить нормальную структуру фич из кода. Тут может помочь фиксация типовых сценариев использования системы - как пользователи с ней работают. Элементы системы, которые участвуют в сценарии и могут стать отправными точками для фич. Пример: "Пользователь входит в систему: на экране логина он вводит имя пользователя и пароль. Система валидирует пароль и загружает главный экран с доступными пользвоателю разделами." (фича аутентификации, фича авторизации).

🔵 Используйте методологии CRUD анализа: еси в системе зафиксирована работа с некоей сущностью "заказ" - типа, "пользователь создал заказ", то для сущности "заказ" должны быть описаны все CRUD методы: как создавать, просматривать, менять и удалять такие сущности (бывает, что удаление часто выпадает при документирвовании).

🔵 Используйте методики Use Case Analysis: сценарии часто описывают только "happy path". Но что будет если пользователь ввёл неправильный пароль? 10 раз подряд? если при регистрации пользователь с таким паролем уже существует? Если api станет недоступно посередине регистрации? Такие сценарии называются "exception flows" и "alternative paths".

🔵 Анализ Перехода Состояний (State Transition Analysis) : если в системе есть сущности с состоянием, надо разобраться со схемой переходов состояний. Составляем агентами список состояний и карту возможных переходов между ними, и смотрим - документировали ли мы все, что касается доступных переходов. Как именно заказ из состояния on-hold переводится обратно в processing. Документировали ли мы как заказ из "paid" становится "shipped"? Такая карта здорово помогает найти пробелы в документировании.

🔵 В целом - практики "классического" "enterprise" моделирования процессов, проектирования, бизнес-инжиниринга будут работать на пользу процессу и тут - ведь мы решаем похожие задачи: если раньше эти практики использовались чтобы люди понимали как работает система в бизнесе, то теперь у нас даже более практичное применения - мы должны растолковать все то же самое ИИ агентам!

Надеюсь, дал какие то намётки подхода! И помните - задача творческая, жёстких методик пока не сформировано, все познается на практике.

🙇‍♂️ Пробуем, анализируем, делимся, улучшаем!


␄
#post
@deksden_notes

🖼️ Claude Code: Paste Images

Неужели починили старый баг?


Version 1.0.93:
• Windows: Add alt + v shortcut for pasting images from clipboard



ℹ️ Ну и кто не в курсе, в CC, да прям в терминал, "всегда" (когда это работало) можно было вставлять картинки (скриншоты например). Только на маке это работало через Control+V (а не привчынй Command+V), а на windows нынче сделали alt+V (тоже нестандартный). Ну - хоть так!

Кстати, drag and drop картинок работал давно и понадёжнее.


#news
@deksden_notes

ℹ️ Claude Code: подумать глубже


☝️ Тоже могут не все знать: в CC есть возможность для Соннета / Опуса включать режим thinking - для этого пишем "think hard" / "ultrathink".

▶️ У меня почему то не в каждом промпте это срабатывает, поэтому я останавливаю CC через нажатие Esc, и пишу отдельно в интерактивном режиме: think hard. После этого можно будет увидеть немного другим оформлением "мысли" модели. Соответственно, - например, поиск бага получает инъекцию сообразительности!

"Хозяйке на заметку" (ц)

#post
@deksden_notes