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


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

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

🔃 Claude Code: очередное обновление 1.0.94

На самом деле уже 1.0.95, но про .95 ничего не рассказали, а вот что у нас в 1.0.94:

• Vertex: add support for global endpoints for supported models
• /memory command now allows direct editing of all imported memory files
• SDK: Add custom tools as callbacks
• Added /todos command to list current todo items


Помимо того что можно быстро и удобно открыть CLAUDE.md уровня проекта/системы (/memory командой), появилась возможность посмотреть текущий список задач через /todos, что удобно - теперь не надо скроллить чат в поисках где там СС последний раз его трогала.

А вот что такое "Add custom tools as callbacks" - это надо разбираться, интересно. Пока из документации особо не понятно, будем искать)


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

#news
@deksden_notes

🔃 Claude Code: очередное обновление 1.0.97


Version 1.0.97:
• Settings: /doctor now validates permission rule syntax and suggests corrections


⚠️ Да, уже .0.98, но в 97 включили поддержку линтинга правил в настройках - и если у вас перестал работать ccstatusline, время проверить что за ошибки в settings. Если выявлены ошибки - то возможны всякие "спецэффекты" в виде отключения части прописанных в настройках штук, имейте ввиду!

#post
@deksden_notes

↔️ XML-like теги


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

Это XML-like теги. Рекомендации от "лучших собаководов" прилагаются!

https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags

❓ Почему я пришу XML-like, а не XML? Потому что это не "классический" XML со схемой, атрибутами тэгов, нет - без этих усложнений. Усложнения в виде схемы путают модель без очевидной необходимости. Атрибуты - по желанию, если семантика подходит.

▶️ Мы просто используем тэги в угловых скобках для разметки структуры промптов. Какие задачи наиболее эффективно решаются:

- явная разметка начала и конца некоего семантического блока
- явное и однозначное указание вложенности блоков друг в друга

Этого достаточно, чтобы пользоваться этим почти в каждом промпте.

❓Какие теги применять? Конечно, семантические, что даёт дополнительный плюс. Пример:

<инструкции>
...

<некий_блок>
...
<вложенный_блок>
...
</вложенный_блок>
...
<и_еще_один>
...
</и_еще_один>>
</некий_блок>
...
</инструкции>

Думаю, идея понятна. В сложных случаях: <элемент_списка порядковый_номер="1" важность="обычная">


❓ Зачем такие сложности? Чтобы явно показать структуру, когда она не тривиальная. С тривиальной и маркдаун вполне подходит, а вот вложденные многоуровневые списки модель иногда "парсит" с ошибками: проверка может быть очень простая - попросите модель составить структуру вашего промпта с многоуровневыми нумерованными элементами структуры, можно иногда удивится!

❓ А как же маркдаун? Такие теги с ним вполне совместимы. Я пишу обычные md файлы и добавляю xml-like теги в "сложные места", где модель можнт неоднозначно определить логическое начало и конец блоков.

❓Можешь пояснить "за фрактальный промптинг"? Конечно, и, как ни странно - сабж и xml теги вполне себе имеют место быть: для авторегрессионных казуальных моделей (а это почти все современные трансформеры, с треуголными масками внимания на всех этапах обработки, включая prefill) - они "условно" читают текст слева направо, поэтому наличие уникального закрывающего тега для них "удобно".

ℹ️ Удобно в кастомной слеш команде делать так:

some_command.md:

Вот команда пользователя:
<команда_пользователя>
$ARGUMENTS
</команда_пользователя>

И дополнительно делай так: ...

❓ Что именно улучшают тэги? Только восприятие моделью
структуры промпта - содержательно тэги сами по себе не будут какой то магической «пилюлей».


#post
@deksden_notes

🥳 🎁 🎉 Маленький юбилей Claude Code: круглая версия v1.0.100

Жаль, что без release notes, багфикс релиз или какие то скрытые пока функции.

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

Пожелаем дальнейших успехов!


#news
@deksden_notes