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

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


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

⚒️ В полку 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

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


▶️ Симптомы:

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

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

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

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

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


🔧 Решение:

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

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

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

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

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

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

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

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

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

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

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


#post
@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

🔥 ССstatusLine

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

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

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

https://t.me/kdoronin_blog/897

https://t.me/the_ai_architect/129

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

https://github.com/sirmalloc/ccstatusline

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

#link
@deksden_notes

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


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


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

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

#news
@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

🧩 Модель С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

🦦 Такое мы тестим!


VibeTunnel.

https://habr.com/ru/articles/937726/


#link

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


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

Оркестратор - это штука, которая будет пускать 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

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


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

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

#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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#post
@deksden_notes

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


#post
@deksden_notes

📓 Inline Скрипты


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

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

Все это в полной мере свойственно и агентным процесса.

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

Конечно, для таких целей у нас есть обычный код! И нет повода отказываться от агентных процессов! Мы просто просим модель запустить заранее подготовленный скрипт. Можно использовать python или js/ts с npx/tsx, смотря что у вас установлено, и с чем проще для вашего понимания работать.

☝️Разбив задачу на детерминированный код в скриптах, который вызывается из агентного процесса, мы получим лучшее от "обоих миров". Особенно если вы "оформите" вызов скрипта инструкциями о контроле во время выполнения и поручением, если что, исправлять ошибки.

🙇‍♂️ Высшим пилотажем могут считаться кейсы, когда агент пишет себе скрипт до выполнения, по мере необходимости! Тут нужны чёткие инструкции и мысли о безопасности, но мы получим максимальную гибкость.

❓Кейс?

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

Скрипты сделают что смогут (распакуют, разложат по типам, преобразуют известные форматы), а LLM соберёт это для достижения вашей конечной цели

#post
@deksden_notes

🔗 Аннотированные md ссылки


Ещё один приём, который несмотря на простоту является важным инструментом контекст инжиниринга.

Я назвал его "аннотированные ссылки".

Когда необходимо добавить ссылку на другой md файл, я ввёл для агентов правило оформлять её как "аннотированную md ссылку". Формат такой:

- в маркдауне один из вариантов оформления ссылки - это сочетание текста в квадратных скобках и сразу за ними ссылка в круглых скобках
- текст в квадратных скобках - это то что видит пользователь, оно может быть выделено как ссылка (синий цвет, подчёркивание)
- ссылка в круглых скобках - это url по которому система будет переходить по клику
- я требую в квадратных скобках указать абсолютное имя файла от корня проекта, например "[.memory-bank/product.md]"
- в круглых скобках система указывает относительный путь к целевому файлу (относительно папки текущего документа)
- ВАЖНО: следом идёт двоеточие и все то же описание файла из тэга description


❓ Нафига "козе баян"?

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

❓Почему два формата записи путей?

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

❓Зачем относительный путь?

Может сработать в markdown просмотрщиках, хотя нам важно дать инфу агентам.



#post
@deksden_notes

🗂️ Индексные файлы "index.md"


В меморибанке в папках, где лежит много файлов (architectue/, guides/), или в папках сложной строуктуры (где много вложенных папок с файлами) я организую специальные файлы index.md


☝️В файле index.md храним оглавление папки с ОПИСАНИЯМИ файлов. Описание берём из frontmatter тэга "description", то есть 1-2 предложения.

❓Зачем такое нужно?

Простой список файлов агент может получить LS командой. Но файл index.md даёт агенту понять, что именно лежит в каждом файле. Иначе ему придётся или читать каждый, или найти ключевые слова поиском - без гарантии что нужный файл попадётся.

Индексный же файл позволяет значительно повысить "прозрачность" данных для агента. Такие вот эмбеддинги на минималках.

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

❓ Как обновлять? Это же очень быстро устаревает.

Верно! Но у нас с вами есть [агентные процессы](https://t.me/deksden_notes/27), и [агенты](https://t.me/deksden_notes/16).

Процесс обновления:

- мы определяем агента "помощник по файловой системе", ставим ему модель haiku для скорости, объясняем синтаксис frontmatter чтобы он даже не думал
- оркестратор запускает пучек агентов "по файловой системе" на крупные "ветки" меморибанка, параллельно; я определяю сам с каких веток стартуем, но тут можно выдумать кучу оптимизаций по автоматическому распределению работы;
- агенты работают параллельно, каждый обрабатывает свою ветку файлового дерева
- в хоже работы агент обновляет поле "description" каждого файла. После того, как агент обработал все файлы, он обновляет индексный файл.
- некоторые папки обрабатываются по своей логике: например, папки agents и commands меморибанка, в которых есть md файлы, но они симлинками указывают на папку .claude для определения команд и субагентов проекта - их мы не обрабатываем
- папку эпиков обрабатываем на всю глубину, делая в индекс несколько уровней файлов
- прочие кастомные правила, которые вы выдумаете
- правила прописываем агенту в инструкцию

▶️ В итоге: индексные файлы незаменимы для подсказок агенту при сборе контекста


❓А может сразу все дерево?

В принципе, попробовать можно. Смущают несколько моментов:

- файл с полным деревом , у которого будет описание md Файлов будет довольно большим
- много разнородной инфы в одном файле путает модель
- концептуально, для модели может быть не совсем понятно дерево ТОЛЬКО по markdown файлам.


❓Зачем обновлять агентами?

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

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

Обновление тэга же без агента сделать тяжело - для суммаризации нужна модель.


#post
@deksden_notes

📂 Фронтмэттр


Продолжим серию постов про "алфавит" AI SWE инструментов - без этого алфавита сложно будет разговаривать о более сложных конструкциях. Ведь они состоят из этих базовых элементов.

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

К сути!

▶️ Начнём с frontmatter - это расширение стандарта Markdown синтаксиса для указания в начале файла небольшого блока данных, в формате YAML. Формат легко гуглится, отделяем чёрточками, между ними пишем свойства в YAML нотации.

Зачем нам frontmatter? Удобная вещь для хранения важных реквизитов файла, которые иначе нужно было бы собирать по файлу, проводя его полную обработку:

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

▶️ пример "ссылок" :

feature: '[FT-002-3]'
epic: '[EP-002]'

Это ссылка на эпик/фичу с которой связан документ

❓ Какие тэги можно использовать?

Стандарта нет, используем то, что нам нужно знать про файл. В некоторых CMS системах на этих тэгах построены атрибуты файла, которые использует CMS.

Важно отметить, что claude использует frontmatter для файлов описания агентов - там мы пишем name, description, model, color.

❓ А всё таки?

помимо description и epic/feature я использую тэги:

- update: в чем суть последнего обновления файла
- date: дата последнего обновления файла
- status: это DRAFT или ACTIVE документ
- history: перечень последних 5-7 обновлений файла с датами и описанием (не в git же ща ними лезть!)

Ну и всякие другие поля - по обстановке!

#post
@deksden_notes

😎 Клод теперь все помнит

Клод в веб теперь может искать и брать контекст с предыдущих чатов

https://support.anthropic.com/en/articles/10185728-understanding-claude-s-personalization-features

Наверное, надо было чаще говорить спасибо за проделанную работу и хвалить!..

#news
@deksden_notes