☝️Agentic WFs vs традиционные алгоритмы

Прекрасный кейс родился у Дениса @ataden

У него совершенно гениальная способность встречать баги! В СС ему встретилось уже 2, и оба подтвердились на github. Очередной был вскрыт накануне, но оказался не багом, а фичей.

Исследуя траффик как СС "в потрохах" общается со своей штаб-квартирой, Денис обратил внимание, что файл CLAUDE.md совсем не упоминался в контексте, хотя документация говорит что он читается регулярно, как минимум - в начале сессии. То есть в контексте он быть должен, но его нету.

Ларчик открылся просто: имя файла на его машине было CLAUDE.MD (расширение написано крупными буквами). А ожидался файл CLAUDE.md (маленькие буквы в расшиении). Так как в СС файл грузится обычным ts кодом, а не промптом агента, то код не находил требуемого файла (с расширением ".md") и тихонько продолжал работу без каких либо жалоб.

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

Когда в чате CC попросили прочитать AGENTS.md, агент попытался, не нашёл файл, прочитал каталог, увидел похожий и молча загрузил его. Агентный код грузит файл.

То есть степень гибкости агентного процесса - она агентная! Вот какой интересный опыт 🔥

#post
@deksden_notes

📝 #sidenote Заметки на полях


Я уже как то упоминал, что инвесторы курсора на самом деле инвесторы в антропиков.


пруф: https://t.me/ai_machinelearning_big_data/8210


#link
@deksden_notes

😬 Свежая идея: AI - чипы с трекингом (не только?) геолокации
#sidenotes

Omfg. И эти люди что то там говорили про HUAWEI !

"Все - одинаковые!"

https://www.bloomberg.com/news/articles/2025-08-05/us-explores-better-location-trackers-for-ai-chips-official-says

#link
@deksden_notes

😎 Совпадение?.. Не думаю!
#sidenotes


Только сейчас обратил внимание на то, что лимиты Жульеса при релизе смутно напоминают чего то ... Не могу вспомнить где я видел такую же кратность к базе - x5 / x20!..

" - Музыка навеяла!" (шикарный анекдот, конечно)



https://blog.google/technology/google-labs/jules-now-available/

#link
@deksden_notes

😇 Гугл - боги нейминга
#sidenote


Ура! Первые следы Gemini-3.0 обнаружены на просторах интернетов (видимо, в репо gemini cli).

Нейминг меня прям расслабил! Подушню, но это забавно же:

не gemini-3.0.-pro-beta, а gemini-beta

чуть ниже gemini-experimental, не -exp, и v2 вместо 2.0!

В общем, боги нейминга! 😁 Но тебе можно больше, если ты выпускаешь топовые модели, с топовыми бенчами, с самым большим контекстом.

Если ещё агентность докрутят, точность тулколов, и внимание в cli соберут, и контекст ... - то совсем 🔥

Ждём, ждём


#link
@deksden_notes

🐞 Неприятный баг в Claude Desktop


В последней версии Claude Desktop обнаружился неприятный баг. Я его использую с Desktop Commander MCP для планирования, следовательно, со старта мне нужен Opus и поумнее, то есть "Extended thinking" включена.

Стартую я новые чаты с проекта, для которого слегка прописано в Project Instructions чего и как, чтобы в промпт каждый раз не писать

Баг: даже если включаешь Extended Thinking со старта, чат стартует без него. В итоге, мало того, что свежий опус думает по 3-4 секунды, так ещё и думание это включать отказывается! А мне это существенно даже для первого сообщения - контекст в claude desktop совсем не похож размером на AI Studio + Gemini 2.5 Pro.

☝️Workaround: останавливаем генерацию ответа, включаем extended thinking, редактируем запрос - генерация запускается уже в режиме thinking. PROFIT!

П.с. Индикации окончания контекста так и нет - позор какой то, конечно.

#post
@deksden_notes

🗃️ Операционная память для агентских процессов на Папках задач
1/4


Буду потихоньку накидывать терминологии и концепций. Это статья логически связана с "Агентными процессами". Поговорим об Agentic memory и варианту реализации этого механизма на такой штуке как "Папка задач".

Операционной памятью агентов является контекст и только контекст, всегда. Нюанс в том, что его всегда не хватает.

По дизайну, механизм обмена информацией у оркестратора с агентами очень простой: "вызов" агента происходит как рядовой вызов/мультивызов инструмента (tool calls), только работа инструмента получается довольно долгой. При вызове оркестратор формирует как параметр вызова инструмента промпт, где указывает задание субагенту.

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

Мы видим, что течение информации довольно скромное: сообщение "оркестратор" -> "агент" в начале работы, сообщение "агент" -> "оркестратор" в конце. Не самая интенсивная коммуникация! Буквально в режиме "Здравствуй и прощай".

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

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

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

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

#post
@deksden_notes

🗃️ Операционная память для агентских процессов на Папках задач
2/4

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


🗄️ Механизм "Папка задачи"

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

📝 Системные промпты агентов могут предусматривать чтение из папки задачи деталей своего задания, которые никак бы не вместились в сообщение оркестратора.
Результаты работы агента со всеми деталями могут быть записаны в файл. Не всегда возможно уместить эти детали в ответ оркестратору.

Чтобы стало понятнее, давайте рассмотрим конкретный пример агентного процесса.

✨**Пример кейса:**

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

Как для данного кейса может выглядеть выполнение агентного процесса:

‣ задача оркестратора: переименовать функцию Х из модуля ХУ.ts

‣ оркестратор вызывает субагента "создать папку задачи" и получает новую папку задачи `.tasks/TASK-032/, идентификатор задачи TASK-032.

‣ оркестратор запускает первый этап процесса - найти затронутые файлы вызывая агента "исследователь" с задачей: идентификатор задачи TASK-032, идентификатор этапа S-01, результат нужно будет поместить в файлы вида "TASK-032-S-01-final-report-{file_type-XX}.md", задача - найти где в кодовой базе используется функция Х из модуля XY.ts.

Исследователь должен отсортировать файлы в два списка, по типу файла (file_type) - если это файл кода, то в список "-code", если это документация, то в список "-docs".

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

Группу файлов будем писать в отдельный файл с суффиксом "-code-XX" или "-docs-XX" (вы же помните что мы разбили код/документация).

Вернуть нужно итоговый список созданных файлов (сколько то файлов -code-XX и -docs-XX), допонительно сказать сколько таких файлов всего получилось.

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

‣ управление возвращается оркестратору - он просто видит результары работы "исследователей" со списками файлов, содержимое файлов его особо не интересует

‣ далее оркестратор начинает обрабатывать список файлов, делать вызовы агента "писатель кода" по 5 штук параллельно, для всех полученных файлов кода

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

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

‣ система завершит работу. Даже если у нас был неслабый проект и 200 упоминаний по коду/документации, мы получим полностью обновлённую кодовую базу, с переименованными комментариями и правильно сформированной документацией; при этом контекст оркестратора будет "забит" только списком файлов, что вряд ли "скушает" его даже на 1%.


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

#post
@deksden_notes

🗃️ Операционная память для агентских процессов на Папках задач
3/4


... (продолжение, предыдущая часть тут: https://t.me/deksden_notes/37)

**А если - нет?**

Промоделируем сессию AMA

❓ В чем смысл таких сложностей и "танцев с бубном"? Допустим, мы просто расписали промптом задачу в СС и он начал выполнение. В чем такой подход хуже?

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

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

2️⃣ Во вторых, если у вас большой проект, контекст основного агента (только тут его не назовёшь уже оркестратором, он ничего не оркестрирует, а работает сам) забьётся вызовом инструментов и обработкой файлов очень быстро.

Далее произойдёт автокомпакт (у кого он включён), и дальше - как повезёт! если агент "не забудет" задание, то продолжит работу. Может, слегка не в том ключе и не особо следуя инструкциям.

▶️ В итоге: будет сложнее, дольше, менее качественно. Скажут - "Я ж говорил, ИИ не тянет!", хотя - 💯 SKILL ISSUE.

❓ А в чем смысл создания папки задачи с уникальным идентификатором?

Все очень просто: идентификатор даёт некоторую изолированность задачи. Если вы в одном сеансе СС работаете с базой данных, то другие сеансы могут рефакторить код. Задачи друг другу мешать не будут, случайного пересечения имён файлов тоже не случится.

Аналогично - и идентификатор этапа, позволяет разделять файлы.

❓ А чего такой велосипед? Файлы - это как то примитивно

Потому что - нет. Файлы - не примитивно, а традиционно и в каком то смысле enterprise grade. Достаточно вспомнить что есть unix way, где вся система - это взаимодействие через файлы, включая pipes. Напомню, что linux - это тот же unix, только попроще. И даже бородатые сисадмины не скажут что unix это примитивно.

❓ Может быть все таки более хайповый MCP

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

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

❓ Зачем такие сложности с группировкой файлов? Можно просто обработать один за одним

Нет, нельзя. По тестовому кейсу у нас документация и код. Как минимум разделить придётся по типу файлов. А если уж делить, так слегка оптимизировать параллельностью. До 5-7 агентов СС спокойно запускает параллельно, что будет сильно быстрее последовательного вызова.

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

🗃️ Операционная память для агентских процессов на Папках задач
4/4

(...продолжение, предыдущая часть тут: https://t.me/deksden_notes/38)


❓ А что за магическая цифра "разбивать по 5 файлов"?

На самом деле, именно 5 тут приведено просто для примера, но суть в том, что не надо делать такую задачу без ограничений количества файлов. Работа с файлами неслабо так нагружает контекст - все эти чтения фрагментов чтобы создать изменения, все они остаются в контексте. Если субагент получит неконтролируемого размера кучу файлов для обработки, уже у него кончится контекст - со всеми непредсказуемыми последствиями данного обстоятельства. А мы же хотим качественно и надёжно все сделать, да?

❓ Ок, но зачем так экономить контекст оркестратора? откуда такая сокральная ценность его контекста?

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

А что касается именно оркестратора - то его "чистый" контекст - это возможность выполнения сложных и продолжительных агентских процессов. 2-3 шага нашего примера процесса были не самыми простыми по логике выполнения, но "потратили" не более 1% контекста, значит смело можно делать процесс где таких шагов будет ещё 50.

☝️ Выводы

Сочетание приёмов и принципов:

- экономия контекста
- использование агентных процессов (врокфлоу на субагентах)
- конфигурирование агентов
- использование папки задач как механизма обмена

... позволяет "выжимать" потенциал Claude Code и реализовывать сложные, полезные и умные процессы!

Stay tuned, серия статей "to be continued"


␄
#post
@deksden_notes

⚡️🔥 Sonnet4 1m context (!!!)
#sidenote

Big if big!

Почти x2 к цене API на контекстах выше традиционных 200к, но, блин! Интересно

Ждём бенчей

https://www.anthropic.com/news/1m-context

---
UPD: В Claude Code .74 уже предлагает при заполнении контекста переключиться на модель sonnet[1m], но на подписках пока не работает:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"The long context beta is not yet available for this subscription."}}

---
UPD-2: Я так понимаю летний апдейт соннета - это как раз sonnet4[1m]

Уже .77 и все без release notes. Чего то прикручивают!

#link
@deksden_notes

🙇‍♂️ "Умные" вызовы "умных" агентов (smart calling)


Продолжим серию постов с "азбукой" агентных процессов - нам нужно выучить некоторые новые "буквы". Сегодня поговорим о "smart calling" - практическом приёме "умного" вызова "умного" агента. Этот приём пригодится для выстраивания сложных агентных процессов, и сможет некоторым образом повышать надёжность и usability работы.

▶️ Напомним базу

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

Несмотря на явную аналогию с вызовом функции в классических алгоритмах, мы имеем нюансы: схема "вызова" никак не типизирована и ничем особенным не ограничена - просто текстовое сообщение. Впрочем, ровно как и ответ агента! Это имеет свои последствия.

ℹ️ Аргументы "вызова" - проверка, верификация

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

🛑 "Выбрасывание ошибки"

Что делаем если что то не в порядке и это критично, мы не можем исправить? Например, сказано что необходимо анализировать отчёт, а отчёта по указанному пути мы не нашли.

Мы "выбрасываем ошибку" - инструктируем агента что в таком случае мы прекращаем работу и пишем ясное сообщение о причинах.

🔃 Возврат результатов

Мы уже обсудили с вами на темах "agentic memory" и "папка задачи" важность беречь контекст оркестратора. Объёмные результаты мы помещаем в папку задачи. Короткие результаты возвращаем текстом, проинструктировав агента что при завершении работы он их должен сообщить.

🤓 Где же тут "умное" (smart)?

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

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

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

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

Также можно применить приём "умные результаты": когда мы не только вернули запрошенные данные, но и дали пояснения к ним относительно их использования, а также контекста. Например, возвращаем статус эпика и говорим что с ним можно делать дальше (это специализированный агент возьмёт из описания ваших процессов работы с эпиком). Или агент создания папки задач вернёт подсказку, что папка задач создана с "точкой" в начале имени, это делает её "невидимой" среди обычных файлов, поэтому нужно применять специальные опции для bash команд для её обнаружения. Интересные результаты можно получить от инструкции в промпте агента "а также добавь в итоги работы то, что считаешь важным и необходимым".

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

␄
#post
@deksden_notes

🤓 Простой пример для простого примера - доносим смыслы


Дополняющий пост к публикации "Операционная память для агентских процессов на Папках задач" (https://t.me/deksden_notes/37)

Во второй части я привёл "простую задачу". Однако когда Тимур @yatimur , пытаясь его понять, стал рисовать в гемини диаграммы потока выполнения и прочую датафлоу, - стало ясно что пример не особо прост для восприятия. И родилась отличная аналогия для полноценного донесения смыслов!

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

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

🥄 Шеф, посмотрев на отчёт помощника, зовёт двух поваров и даёт им задание готовить блюдо по рецепту, а продукты их муже приготовлены на выделенных столах (промпт со ссылками на файлы в папке задач). Повара идут, и готовят блюда, возвращаются с отчётом когда закончат работу.

☝️ Понятно, что шеф организовал выполнение всей работы! Но вы зацените концепцию "столов для продуктов" - именно она позволила шефу "не марать руки" (контекст оркестратора не нагружен). Шеф получал только краткие отчёты о работе, а вся работа (весь контекст) для исполнителей собралась на столах: сначала как набор проуктов, а потом и готовые блюда.

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

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

Таков вот пример 🧑‍🍳


#post
@deksden_notes

📦 Memory bank через Obsidian

Я часто гляжу на меморибанки проектов через Obsidian. Почему? Несколько важных фич:

- нормальный рендер markdown, выглядит все эстетично
- удобный inline редактор, разметку видим когда редактируем, а так - WYSIWYG
- полноценно рендерим mermaid диаграммы, это важно (вот gemini в AI Studio не умеет! Пойду пожалуюсь Логану)
- есть Kanban плагин для просмотра досок (с багами, например)
- есть достаточно удобная поддержка frontmatter тэгов, которые использую активно

Когда смотришь то же самое в PyCharm - совсем другой вид, менее "товарный"!

Вот примерно такой просмотрщик md мне нужен в post-IDE инструментах (типа TRAE SOLO). Надо будет найти кто так умеет делать на реакте (особенно удобное редактирование)- если кто знает, пишите.


#post
@deksden_notes

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

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

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

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

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

🗂️ Индексные файлы "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

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


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

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

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

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


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

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

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

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

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

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



#post
@deksden_notes

📓 Inline Скрипты


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

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

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

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

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

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

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

❓Кейс?

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

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

#post
@deksden_notes

⚛️ Атомарные 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