Немножко про стандартизацию CLI агентов.

Сравнил слэш-команды у четверки наиболее популярных\актуальных: Claude\Codex\Gemini\Qwen.

Рабочий цикл:

/init - инициализация контекста - есть у всех
/plan - режим планирования, без выполнения - есть у всех
/goal - установка цели (evals или DoD) - 3 из 4, причем: фича появилась буквально месяц назад
//... тут идет разработка
/status, /context, /stats - просмотр информации о сессии - 4 из 4, но часто разделено на 2 команды - типа /status и /context. Как по мне - лучше слить в одну, я их путаю)
/compact (/compress) - ручное сжатие сессии - все, но терминология разделилась
/memory (/memories) - просмотр контекста проекта - 4 из 4, но Codex не смотрит на тренды)
/diff - просмотр незакоммиченных изменений - тут пока слабо, 2 из 4, но есть git и IDE
/resume - возобновление рабочей сессии - 4 из 4
/review - собственно ревью - 3 из 4, где-то есть 2 варианта - локально и на GitHub, где-то реализовано как скил с возможностью быстрого вызова
/clear (/new) - новая сессия - есть у всех

Итого - есть путаница с информацией о сессии, не везде есть /diff, дилемма /compact vs /compress. Т.е. 7 из 10 стандартизированы, по 3 наблюдаем.

Настройка оснастки (harness):

/model - выбор модели - у всех
/skills - просмотр и вызов скилов - у всех
/mcp - просмотр и включение MCP серверов - у всех
/agents - просмотр и добавление субагентов - 3 из 4, как ни странно Codex отстает, все работа с субагентами через конфиги
/hooks - просмотр и редактирование хуков - 3 из 4
/tools - список встроенных тулов - 2 из 3
/plugin(s) (/extensions) - работа с плагинами, включая установку из marketplace - 4 из 4, но терминология не выработалась. 3 разных варианта

Итого - практически стандарт, за исключением tools и терминологии plugin vs extension.

Безопасность:

/permissions - разрешения для тулов - 3 из 4

База:

/exit (/quit) - все
/theme - все
/vim - 3 из 4, для любителей Linux, но Claude его удалил, и это может стать трендом
/help - 3 из 4
/bug (/feedback) - все, Codex опять не в тренде)

Тут тоже все стандартизируется.

Удобство работы:

/copy - копировать последний ответ в буфер - все, и штука полезная, но малоизвестная. Claude даже n последних позволяет.
/btw (/side) - by the way или side вопрос - возможность что-то уточнить не открывая новое окно во время работы агента - 3 из 4
/recap - краткое резюме по сессии - 2 из 4
/statusline - настройка собственно statusline, как это принято в Linux - 3 из 4

Даже на таких мелочах и то стандартизация)

Передний край, развитие - фоновые задачи и ветвление:

/fork - создание параллельной сессии для исследования темы - 2 из 4
/rewind (/resume) - откат либо в рамках текущей сессии, либо убить форк - 3 из 4
/loop - запуск по расписанию в сессии, не путать с циклом - 2 из 4
/tasks (/bashed, /ps) - просмотр фоновых задач - 3 из 4

Общий итог - стандартизация явно вырисовывается.

#ai #ai_agents

Не могу пропустить новость про workflow в Claude Code.
Вот эту https://claude.com/blog/introducing-dynamic-workflows-in-claude-code

Для начала хотелось бы отметить некую иронию ситуации.
Принцип агентности в AI гласит, что система может считаться AI агентом, если сама принимает решение на основе полученных данных - от пользователя, RAG, тулов, собственно данных в модели.
А суть нововведения в том, что моделью при наличии в промте слова workflow создается стейт-машина, динамическая, под каждую задачу своя, в виде JS скрипта.
И в дальнейшем этот скрипт оркестрирует субагентов.

Т.е. забираем свободу у LLM, все контролирует скрипт)

Я конечно утрирую, свобода остается.
Во-первых модель пишет сам скрипт по промту пользователя.
Во-вторых - субагента никто не ограничивает в процессе работе, ограничивают его только во входных и выходных данных.
Но тенденция интересная. А велики шансы, что workflow станут стандартом.

Почему мы к ним пришли?
Я бы обратил внимание на два момента:
1) вот эта новость https://habr.com/ru/news/1041104/ Удивляет 500 млн $ и неизвестная компания. И упоминание Microsoft в следующем абзаце)
2) Фраза "Dozens to hundreds of agents per run".
Т.е. на больших задачах, если запускать десятки субагентов и никак их не контролировать - цена ошибки возрастает.
При этом и использование workflow потребует больше токенов, как собственно на реализацию state machine, так и на дополнительные контролирующие фазы.
Но видится, что на больших задачах это имеет смысл. Переплатить фиксированный X, чтобы не получить "большой ком грязи" стоимостью Y, который придется выкинуть.

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

Ну и ключевой вызов для использования workflow - навыки многопоточности.
При разработке обычных бизнес-приложений они часто не нужны: веб-сервера, producer\consumer часто делают все за нас.
А тут навык нужен не для кода, а для создания для правильного промта агенту, чтобы эффективно распараллелить части workflow.
Такие дела.

P.S. Жаль пока только для Max+ тарифов. Ждем на Pro и в следующей версии Qwen Code)

P.P.S. Фича полезная, но не всегда. Не всегда есть достаточно большие задачи с понятным ТЗ, чтобы имело смысл проектировать под них workflow.

#ai #ai_agents

Я вернулся)

Проблема бесконечных подтверждений действий AI агента получила свое имя - approval fatigue.
Есть даже цифры от Anthropic: после 20+ запросов в сессии точность подтверждений падает с 85% до 55%.
Что-то типа рекламной слепоты, когда жмешь кнопку "пропустить" не смотря и не запоминая.

И кроме AI апрува есть два альтернативных, или даже дополняющих подхода:
1) batching - объединение действий в пакеты с одним апрувом. Напоминает транзакцию)
2) апрув с объяснением: т.е. вместо длинной bash команды выдается краткое человекочитаемое описание, что она делает. Для этого нужен отдельный сервис\слой с быстрой моделькой.

Повторюсь - эти подходы можно и нужно совмещать с AI Auto Approve.
Если уж AI забирает радость от решения сложных проблем в коде, то пусть хоть не надоедает)

P.S. Про Java, Kotlin и DevOps я не забыл. Но надо понимать, время такое, все только и говорят, что об AI)

#ai

А кроме approval fatigue есть ещё cognitive offloading. Пост ниже как бы не про ИТ, но проблема общая.

С хорошим ИИ можно сделать сильно больше, чем без.
А с плохим - приходится "пинать ИИ", но это уже другая история)

Так вот, ИИ на этапе планирования предлагает кучу решений, к тому же он обычно многословен. По хорошему в каждое решение нужно вникнуть, поискать в нём слабые места. Но способность вникать и критиковать у человека не бесконечна. И тут возникает cognitive offloading. С какого-то момента критическое мышление отключается, и все решения, предложенные моделью, принимаются. А мы на этапе проектирования, это архитектура, на ней строится код.

Какие варианты?

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

2) разбивать процесс, который проектируем, на уровни абстракции и итерации. Как, собственно, и происходит в разработке. Мне этот вариант нравится, хотя он и замедляет процесс.

3) evals, о которых все сейчас говорят. По сути приёмочные тесты. Для архитектуры могут проверить форму итогового документа - есть ли разделы: Технологический стек, Требования к нагрузке, Отказоустойчивость... но не суть.

4) ограничение скоупа. С AI легко начать проектировать Notepad, а закончить Word-ом) Или даже Google Docs. И за день вполне можно получить детальную архитектуру, возможно даже лучшую, чем Google Docs. Не верхнеуровневую, которая проектируется на собесах за 1 час. А то, что можно отдавать в разработку тому же ИИ. Но где-то со второго часа все решения по факту будет принимать ИИ. Поэтому важно помнить об исходной задаче, а для всего остального завести секцию "Открытые вопросы" или "Планы". Главное, не углубляться в их детальную проработку.

#ai

Чем нам конкретно поможет AI?

В данном случае я говорю про помощь в разработке.
Уже писал про написание, а главное поддержание актуальности в документации https://t.me/javaKotlinDevOps/565

Теперь пришло время поговорить про другую важную штуку - TDD.
Что это - Test Driven Development - я думаю знают все.
Знают, но не используют.
Почему?

Особенно хочу подчеркнуть один момент.
С кем бы я не говорил на эту тему - общаясь по работе или на собесах - никто не сказал: "Да фигня этот ваш TDD".
Все знают, все пробовали, но никто не применяет на работе.
Почему?

Ответ видится таким.
Есть задача. Есть ограниченное время. Которое можно потратить на проектирование, кодирование, тесты, отладку, документирование.
Есть такой закон с немного странным названием - закон Паркинсона.
Он гласит: «Работа заполняет всё время, отведённое на неё».
И он применим в ИТ) Увы(

Так вот - что в первую очередь будет выкинуто, чтобы успеть вовремя?
Очевидно документирование и тесты. А оптимизировать тесты (и документацию) проще, если они запланированы на самый конец. И прощай TDD(
Да, все понимают, что тесты - это хороший способ документировать код, это помощь при будущих рефакторингах, это сетка, предотвращающая сползание в легаси.
А TDD - способ гарантировано иметь тесты и тестируемое Java API.
Но ... нет времени.
А далее сервис медленно, но верно превращается в легаси.
Вспоминается грустный анекдот: "... А чё тут думать! Трясти надо!"

К чему я веду?
AI уже берет на себя большУю часть кодирования. AI быстро пишет код.
AI не лень писать тесты.
Точнее как - конечно же лень, любая LLM модель натренирована на получение быстрого результата, это экономика.
Но вопрос решается правильным промтом (контекстом или скилом если быть точным).
И режимом рассуждений (reasoning), предотвращающим забывание агентом правил игры.
Собственно, уже есть фреймворки, например, упомянутый мной https://t.me/javaKotlinDevOps/589 superpowers, в котором TDD встроен как обязательная часть процесса разработки:
brainstorm-планирование-TDD-ревью-commit.

Итог: документирование и TDD - две вещи, которые разработка с AI перемещает из области "надо, но мы не успеваем" в базовую практику.

#ai #tdd #agile #documentation

И вдогонку про superpowers.

Вроде полезная штука для снижения хаоса в разработке с AI.
Уменьшения галлюцинаций. Шаг влево, шаг вправо - стой, стрелять буду)

Но как обычно бывает есть нюанс(
На сильных моделях (ака Claude Sonnet+) все работает идеально.
Процесс идет по шагам brainstorming -> plans -> TDD в subagents -> review (двойное - каждого шага и общее) -> вливание в основную ветку.
И после каждого этапа commit, что тоже очень даже полезно.
Процент прохождения по workflow близок к 100%.

Но... на сильных моделях и так все неплохо работает, даже без workflow.

А вот на слабых (ака Qwen Code 3, Deepseek 4 Flash) процесс сходит с рельс.
Т.е. запускаем brainstorming - он может не перейти к планированию, а сразу написать TODO и пойти писать код.
Запустилось таки планирование - он может спросить: "переходить ли к TDD в субагенте или в основном потоке", но потом забить на ответ и ... снова пойти писать код.
И закоммитить пройденные шаги забудет.
Про то, чтобы по мере необходимости подключались другие скилы из superpowers (продвинутая отладка например) и речи не идет.

А ведь как раз на слабой модели порядок очень нужен.

Причина тут понятна, их по сути две:
1) superpowers писали и отлаживали на сильных моделях
2) слабые модели, особенно без ризонинга (но и с ризонингом тоже) теряют правила, заданные в контексте.
При сжатии контекста, да и просто по мере его заполнения.
Любая модель к моменту заполнения допустимого контекста начинает галлюцинировать, а слабые - сильнее.

Пример. В конце загруженного в контекст скила writing-plans написано:

...
After saving the plan, offer execution choice:

**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints

**Which approach?"**

**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Fresh subagent per task + two-stage review
...

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

Что же делать?

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

Альтернативные варианты:
- больше императивного наклонения в скилах (ОБЯЗАТЕЛЬНО вызови, НИКОГДА не переходи...)
- уменьшение размера обвязки в контексте до минимума
- загрузка скила using-superpowers (используй superpowers всегда) при старте сессии
не работают.

Скорее всего заработает запрет на переход к неправильному этапу через хуки (PreToolUse, сохранение состояния на диски), но видится, что это уже не AI агент, а state machine получится.

Загрузка информации о superpowers при старте сессии, кстати, автоматически настраивается при установке расширения\плагина.
Причем происходит двойная загрузка - и через хук, и через файл контекста (AGENTS.md) внутри расширения.
Т.е. проблема забывчивости присутствует с любыми моделями, даже сильными.
По хорошему же должно быть так - описания всех скилов есть в контексте, модель вызовет их в подходящий момент.
Скил-напоминалка в теории не нужен. А по факту нужен, и по моему опыту проблему решает.

#ai

Вместо этого поста я мог бы просто дать вот эту ссылку https://github.com/affaan-m/ECC/tree/main/skills
И порекомендовать медленно промотать содержимое страницы, обращая внимание на назначение скилов.

Но все же прокомментирую)

Первый набор скилов по ссылке выше:
- accessibility
- article-writing
- benchmark-methodology
- brand-discovery
- content-engine
- cost-tracking
- design-system
- healthcare-phi-compliance
- investor-materials
- scientific-thinking-literature-review
- seo

Что у них общего?
При чем тут разработка вообще?

А вот второй набор:
- android-clean-architecture
- angular-developer
- codebase-onboarding
- cpp-coding-standards
- django-tdd
- frontend-patterns
- golang-patterns
- java-coding-standards
- jpa-patterns
- kotlin-coroutines-flows
- kubernetes-patterns
- perl-patterns
- python-patterns
- quarkus-tdd
- rust-patterns
- springboot-patterns

Да, у skill есть прогрессивное раскрытие - вначале загружается frontmatter - заголовок, потом все остальное.
Но держать в контексте 250+ скилов - такое себе.
А еще там есть команды и субагенты)))
И хуки https://github.com/affaan-m/ECC/tree/main/hooks.

Тут проблема даже в другом - как выбрать необходимое среди 250 скилов?
Я вижу вариант - брать только то, что кто-то тестировал или по знакомым словам - java, kotlin, spring.
Вроде как в выборе должен помочь скил ecc-guide, но мне не помог(
Авторы в readme рекомендуют скопировать только нужное, да.
Но... зачем собирать такой "божественный репозиторий"?
Если ограничений на тематику нет - то сколько там будет скилов через год? 1000?

При этом судя по названию скилов, число звезд репозитория и по тому факту, что авторы выиграли в хакатоне Claude - полезные штуки там есть.
Та же /code-review команда мне понравилась.

Выглядят интересно хуки:
Strategic compact: Suggests manual /compact at logical intervals.
Git push reminder: Reminds to review changes before git push
Pre-commit quality check: linter (JS, Python, Go), validates commit message format, поиск секретов.
Quality Gate after file edit: автоформат, как в IDEA, тоже только для JS, Python, Go
Сonfig protection: запрет на редактирование конфига линтера.

И одна интересный, но спорный хук: Fact Forcing gate.
Не заметить его сложно, т.к. на каждое редактирование файла будет просьба к агенту предоставить факты:
- какие файлы проекта зависят от текущего (imports)
- какие публичные API меняются
- формат изменяемых файлом внешних данных
- исходный запрос пользователя
Идея в том, что собрав эту информацию агент должен сам себе задать вопрос - все ли правильно он делает?
Такая более продвинутая версия вопроса - "ты уверен?"
Срабатывает на первое редактирование файла в сессии, создание нового, а также на выполнение деструктивных команд.
Последнее так не решается, от деструктивных команд нужно защищаться на уровне репозитория git\прав доступа, но пусть будет.
Замедляет работу, очевидно, но возможно польза есть, наблюдаю.

Итого: интересная штука, но ребята, зачем вы плагин в помойку превратили??? Они не для этого.

P.S. Что-то не верится, что все это люди накодили)
P.P.S. Как они это поддерживать собираются?

#ai #harness

Похвалю Claude.

1) у них есть страница состояния сервиса https://status.claude.com/
2) см. скрин - они пишут историю изменения статуса по проблеме
3) можно подписаться на обновления

Такая штука вполне могла бы стать стандартом для веб-сервисов

P.S. И да, Claude упал)

В AI разработке только и разговоров что об evals)

Что это за зверь такой?

По сути это приемочные тесты, наличие которых - базовое отличие разработки с AI от вайб-кодинга.
Что это на практике?

Если речь про архитектуру и аналитику:
1) проверки формата полученного артефакта - структура файлов, структура разделов внутри,
2) наличие обязательных элементов
3) единообразие терминов
4) ограничение по размеру
5) банально правильная нумерация разделов и ссылок

Если речь про разработку - сразу стоит подсветить важный нюанс.
Агент сам пишет тесты и даже следует TDD (см. предыдущие серии)
И поэтому рассматривать наличие тестов как eval - неправильно, мы их содержимым особо не управляем.
Но при этом тесты - лучшие eval.
Поэтому в самой постановке задачи должны быть проверяемые требования, которые превратятся в генерируемые агентом тесты.
unit или интеграционные - не критично, зависит от уровня, на котором можно проверить работу фичи.
И вот наличие таких приемочных тестов и их прохождение - это уже evals.

Также evals - это успешные проверки линтеров (Checkstyle к примеру) и внешних статических анализаторов кода (SonarQube, Checkmarx, ...).
Сюда же процент покрытия тестами нового кода из SonarQube.
С линтерами есть важный момент - агент в теории может поменять их настройки. Это запрещается через хуки, есть такой хук в ECC плагине https://t.me/javaKotlinDevOps/610
Можно втащить к себе в проект как часть плагина или просто позаимствовать адаптировав под свои файлы настроек.

Еще в качестве evals могут выступать:
- запрет на использование тех или иных библиотек\классов (по всему проекту или в отдельных модулях)
- запрет циклических ссылок (spring beans, ArchUnit)
- запрет на "ломающие" изменения в API или БД
- наличие JavaDoc в определенных местах
- требования к SQL скриптам, например, наличие CREATE INDEX CONCURRENTLY
- время выполнения вызова
...
В общем все, что выполняется достаточно быстро и без сложных интеграций, имеет смысл сделать evals и проверять пораньше.
Ну и один из самых важных evals - соответствие реализации постановке.
В целом все это уже должно было проверяться в CI pipeline с одним исключением, о котором ниже.

Как оформить evals? Как и все остальное - в виде скила.
И тут еще один важный нюанс.
Любую проверку можно выполнить 3 способами:
- запуск кода (тест или shell скрипт)
- просьба сделать проверку агенту
- запуск нового CLI агента в headless режиме

Всегда, когда это технически возможно, стоит использовать первый вариант.
Почему?
AI все-таки по природе своей ленив - любит быстро достигать результата.
Т.е. на явную просьбу что-то проверить в скиле он может сказать: "все ок"- ничего не проверяя. Или даже написать - проверь сам.
Да, он может "подшаманить" скрипт проверки, чтобы пройти дальше.
С последним нужно бороться хуками с запретом на редактирование.
А с первым как раз помогает "хардкод" проверки.
А еще вызов LLM всегда дороже по времени.

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

И вот как раз возможность проверки кода LLM моделью и есть важный бонус, которого ранее не было в CI pipeline.
Но, повторюсь, использовать с осторожностью)

У кого был опыт написания evals для агента - делитесь, что еще можно проверить?

#ai #harness #ai_agents

Почему в Python "неправильная" документация.

Если посмотреть библиотечный Python код, то там можно увидеть вот такое:

class IntervalArray(IntervalMixin, ExtensionArray):
"""
Pandas array for interval data that are closed on the same side.


Или такое:

@classmethod
def _validate(cls, left, right, dtype: IntervalDtype) -> None:
"""
Verify that the IntervalArray is valid.

Что-то к так с документацией, да?)
Зачем питонисты решили сделать все наоборот - комменты после кода???
До кода же логичнее - вначале читаешь доки, потом если надо смотришь код?

Не от балды, нет.
Интерпретатор при загрузке модуля читает первое выражение в теле класса/функции/метода и, если это строковый литерал, помещает его в атрибут ___doc___ соответствующего объекта. Работает принцип convention over configuration.

Также документация выводится с помощью метода help(obj) - если надо прямо в коде. Или через рефлексию - inspect. Или с помощью CLI утилиты pydoc.
Описывается формат документации стандартом PEP 257. Т.е. все продумано.

Причём поля класса документируются точно также для единообразия. Хотя на них стройная система, описанная выше рушится.
И появляется интересный нюанс - если по привычке писать документацию к полям в JavaDoc стиле, то она сопоставится с другим полем)

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

P. S. Как я обратил на это внимание? Один агент написал документацию в формате JavaDoc, другой на ревью заметил, что это не по стандарту Python)

#lang #python #java #conv_over_conf

Расширим AI агента?)
Я про extension, они же plugins.

По сути это способ упаковки обвязки - скилов, команд, субагентов, промтов, хуков и MCP серверов.

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

Есть ещё нюансы по возможному содержимому. Рассмотрим на примере большой тройки агентов - Claude Code, Codex, Gemini CLI.
Скилы, MCP, хуки разрешают все.
У Codex нет субагентов.
Возможность упаковать файл контекста (AGENTS.md) есть только у Gemini CLI и его наследников.
А вот у Claude куча уникальных возможностей:
1) можно упаковать скрипты, которые будут добавлены в PATH для команд плагина,
2) добавить monitors https://code.claude.com/docs/ru/plugins-reference#monitors - интересная штука для наблюдения за внешним процессом, например, через логи, и выдачи сигналов в агента
3) указать тему. Да, у AI агентов тоже есть темы.
4) добавить LSP сервера (Language Server Protocol). По сути это протокол для работы с standalone AST парсером. Агент шлёт кусок кода и задачу, LSP сервер парсит код и возвращает ответ.

Может возникнуть вопрос - а как внутрь расширения запихнуть MCP сервер, это же не промт, а Node.js или Python пакет? Есть такие штуки, как npx (uvx) - скачивают и запускают пакет без инсталляции.

Но вернётся к главному - зачем использовать плагины?
1) единица деплоя для распространения связанного набора компонентов.
2) единый набор компонентов для нескольких проектов, например, всех проектов на Java
3) пакетное включение/выключение компонентов агента одним ключом командной строки
4) кладём все плагины в git - получаем версионирование своего harness. Если захотеть - всегда можно понять с какой обвязкой написана та или иная строчка кода

Итог: использую сторонние (superpowers), создаю свои и всем рекомендую

#ai #ai_agents

Пару слов про хуки в AI агентах.

Набор событий у каждого агента свой.
При этом тут тоже идет унификация и базовый набор хуков, кажется, определился:
* PreToolUse
* PostToolUse
* SessionStart
* UserPromptSubmit - начало обработки пользовательского запроса агентом
* Stop - его завершение.
Я про большую тройку (Claude, Codex, Gemini и примкнувшего к ним Qwen Code).
Тут надо отметить, что PreToolUse/PostToolUse вызываются на любой tool, включая вызов bash, редактирование файла и даже TodoWrite.

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

Для чего можно использовать?
Мои варианты:
1) свой механизм разрешений (PreToolUse)
2) блокировка сессии после проверки среды (SessionStart, только у Codex\Claude)
3) подгрузка контекста в сессию, в т.ч. после ее сжатия (SessionStart)
4) телеметрия, аудит (PostToolUse, Stop)
5) валидация промта пользователя (UserPromptSubmit)
6) валидация ответа модели с возможностью его перегенерации (Stop)
7) замена тула при неправильном ответе (PostToolUse)
8) проверка формата данных, например, при записи в файл (PreToolUse)
9) запуск любых линтеров при окончании работы агента (Stop, SubagentStop)
10) запрет на изменение определенных файлов (PreToolUse)
11) просьба агенту обосновать, зачем он выполняет то или иное действие (PreToolUse)
12) запрет на переход к следующему шагу если не выполнены необходимые действия на текущем, реализация state machine (Stop, SubagentStop)
13) вывод информации о текущей сессии, подсказки о сжатии или начале новой (Stop)
14) кэширование результата работы тулов, включая MCP (PreToolUse)
15) обогащение промта пользователя (UserPromptSubmit)
16) независимое хранилище истории диалогов (PostToolUse, Stop)
и наверняка многое другое, что мне не пришло в голову)

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

#ai #ai_agents

Только сейчас понял, что в канале ни разу не встречается аббревиатура SDD.
Казалось бы не встречается, ну и ... ладно, но SDD сейчас "на хайпе", придется рассказать.
Да и TDD был, DDD был, BDD был.
Тем более штука интересная. Я бы даже сказал полезная.

Вначале расшифровка: SDD - Spec Driven Development.
Т.е. в основе разработки лежит спецификация.
Казалось бы - любая команда, которая пишет аналитику уже работает по SDD?
Нет.
Ключевое отличие - спецификация хранится вместе с кодом, версионируется и поддерживается в актуальном состоянии.
По сути развитие подхода Everything as Code (EaC).
Были Infrastructure As Code, была Architecture As Code, теперь добрались до аналитики.
Отдельные вопросы:
- мы храним спеки по отдельным фичам, как их объединять если новая фича - доработка старой? AI агент или человек?
- как получить все аналитику из отдельных фичей? Отдельный скил?

Тут может возникнуть вопрос - канал то про разработку? Сейчас все будет)

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

Третий важный момент - именно спека, лежащая в проекте идет на вход AI агенту как основной артефакт.
Наравне с описанием проекта в контексте (AGENTS.md) и проектными скилами.

Еще полезный побочный эффект: при SDD больше вероятность, что ADR - architecture decision records - будут сохранены рядом с кодом в процессе совместной проработки фичи.
Вообще говоря, ADR как практика появилась еще в 2021 году, автор Майкл Нюгард (Michael Nygard), но ее широкого распространения я не вижу.
История принятия ключевых архитектурных решений часто живет в головах сеньоров, которые их приняли.
И теряется с их уходом. Или просто со временем. Что не есть гуд.

Что еще важно - тема SDD идет в паре с AI разработкой, поэтому неудивительно, что уже есть готовые SDD фреймворки.
Их много, но самые известные - OpenSpec и SpecKit.
И они предлагают разные workflow для работы над фичей. Но об этом в следующей серии.
Сейчас хотел бы отметить, что если спека пишется AI агентом совместно с аналитиком, это требует меньше участия разработчика.
Т.к. агент видит код проекта, знает язык и фреймворки, и что-то может подсказать сам.
Но конечно же не все.

P.S. Еще 22 буквы свободно)))

#ai #dev_workflow

В продолжение предыдущего поста.
Давайте сравним два AI SDD фреймворка - OpenSpec и SpecKit.

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

OpenSpec - вот базовый вариант:
- /opsx:propose (написание аналитики в составе: proposal, спецификация, дизайн, план)
- /opsx:apply (реализация)
- /opsx:archive (проверка выполнения плана, слияние спек при необходимости, архивация ненужного, перемещение спеки в статус "выполнено")

Просто, всего три шага, после первых двух нужно ревью со стороне человека.

Вот максимально полный вариант:
- /opsx:explore (предварительное исследование, аналог brainstorming в superpowers)
- /opsx:new (создание только proposal.md - документ с секциями "Зачем?", "Что?", "Что меняем?", "Критерий успеха?")
- /opsx:continue 3 раза - создание остальных документов: spec.md (сценарии и требования), design.md (архитектура), tasks.md (план реализации, минимум технических деталей).
- /opsx:apply
- /opsx:verify (ревью реализации)
- /opsx:archive

Тут добавляется брейнштоминг, контроль аналитики по каждому документу отдельно и шаг ревью реализации по трем критериям: полнота, корректность и консистентность с архитектурными (design.md) и code style требованиями.
Т.е. это некий аналог code-review скила, расширенный проверкой соответствия реализации и архитектуры по фиче.

Теперь SpecKit, базовый flow:
/speckit.constitution (некий аналог /init у AI агентов, выполняется один раз)
/speckit.specify (аналитика без архитектуры и плана - spec.md)
/speckit.plan (создается технический план, по сути - архитектура, разбитый на части: contracts\*, data-model.md, plan.md, quickstart.md, research.md)
/speckit.tasks (полный аналог tasks.md)
/speckit.implement (реализация)

Расширенный flow:
/speckit.constitution
/speckit.specify
/speckit.clarify (уточнение задачи, исследования)
/speckit.plan
/speckit.tasks
/speckit.analyze (ревью консистентности аналитики)
/speckit.checklist "что проверяем" (создание чек-листа для проверки реализации в каком-то разрезе: unit tests, security)
/speckit.implement
/speckit.converge (ревью реализации)

Что хочется отметить:
- названия шагов (скилов) не совпадают от слова совсем
- у SpecKit появляется /speckit.constitution, более интерактивный init проекта, позволяющий задать базовые принципы разработки, а кроме того инициализирующий шаблоны, по которым создается аналитика, адаптируя их под текущий проект.
- у SpecKit даже в базовом варианта аналитика создается пошагово с четким разделением на бизнес и техническую части, плюс план.
- набор создаваемых артефактов отличается: совпадают spec.md и tasks.md. У SpecKit файлов больше, т.к. технические документы разделены: API, схема данных, research и собственно архитектура, почему-то названная планом.
- у OpenSpec брейншторминг идет до создания спецификации, у SpecKit - после.
- у SpecKit есть шаг ревью аналитики и шаг создания evals - приемочных чек-листов
- ревью реализации есть у обоих, но OpenSpec пишет замечания и в зависимости от их критичности предлагает сразу исправить, а SpecKit на основе расхождений заводит новые таски
- у OpenSpec есть понятие архивации, которое помечает спеку как выполненную и перемещает ее в архив.

Но как раз на архивации видно ключевое отличие этих фреймворков. В OpenSpec спецификация - это дельта-спецификация.
Что это значит? Что вначале анализируется набор существующих спек в проекте, и для новой сразу же определяется что это - новая фича, изменение или удаление существующей. И на этапе архивации происходит синхронизация - правится или удаляется существующая спецификация, или добавляется новая.
Еще одно отличие - в OpenSpec важной считается только spec.md (сценарии и требования), остальные файлы архивируются - остаются в проекте, но помещаются в папку archive.
У SpecKit такого шага нет, соответственно, слияние аналитики происходит вручную и все создаваемые файлы остаются в папке со спецификацией.

Итог - workflow достаточно сильно отличается, при этом оба соответствуют всем принципам, описанным в предыдущем посте.
У каждого есть плюсы и минусы. OpenSpec проще из коробки и частично берет на себя вопрос упорядочивания фич в проекте. SpecKit заточен на контроль и детализацию.
Я лично использую OpenSpec в связке с superpowers, но об этом в следующей серии.

#ai #ai_harness #dev_workflow

И последнее по SDD. Последнее, но важное.

SDD - это упор на актуальную спецификацию. Т.е. на аналитику.
Из 5-10 шагов по SDD workflow к чистой разработке относится один - /opsx:apply и /speckit.implement соответственно.

Достаточно ли этого?
Для простых фичей, но при этом имеющих свою аналитику - да.
А для более сложных есть superpowers) С TDD, параллельной разработкой в разных worktree, с расширенным код-ревью и отладкой

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

Два нюанса:
1) brainstorming из superpowers в такой схеме становится ненужным и заменяется аналогами из SDD фреймворков
2) writing-plans (из superpowers) нужно оставить, так как это разная детализация.
В SDD таски написаны на уровне аналитика, а writing-plans пишет классы, импорты, тесты, команды запуска скриптов.
По сути из плана, созданного через superpowers, написать код может любой джун. И ему даже скучно будет)
Или самая дешевая модель.

Тогда может возникнуть другой вопрос - а нужен ли план, созданный SDD фреймворком?
В целом не обязателен. Но если он создается одной командой с другими артефактами - можно и оставить. Или подтюнить соответствующий скил.

Еще одно важное замечание. Я встречал случаи, когда superpowers тоже относят к SDD.
Нет, ну формально конечно спека по итогу brainstorming создается, как и план по итогу writing-plans.
Но это спека и план с деталями реализации, т.к. superpowers прям заточен под разработку.
Поэтому на мой взгляд по факту это не SDD фреймворк. Ну или как минимум - не SDD для команд, где есть явная роль аналитика.

И последний момент - нужно ли использовать два фреймворки - OpenSpec + superpowers - в связке?
А точнее когда нужно их использовать?
Ответ в общем очевиден - для достаточно больших фичей, когда в репозитории по итогу разработки фичи должна остаться спецификация. Либо это требование организации, либо решение команды.

#ai #ai_harness #dev_workflow

Небольшая иллюстрация чем отличаются superpowers и OpenSpec на примере артефакта tasks.

OpenSpec, план работ по одной task-е

## 1. Chain и policy

- [ ] 1.1 `data/label_policy.yaml`: добавить `service_id_chain` (дефолт `[service, service.name, app, app.kubernetes.io/name, job]`); загрузчик policy сохраняет порядок, поставляет дефолт при отсутствии поля
- [ ] 1.2 Функция извлечения `extract_service_id(labels, chain) -> (service_id, service_source)` — чистая, ≤N dict-lookup'ов; юнит-тесты: порядок приоритета (`service` бьёт `app`), fallback на `app`/`job`, пустой chain → `('', 'none')`, provenance-значения

superpowers, кусочек плана по той же task-е

### Task 1: Service ID Extraction Chain + Policy

**Files:**
- Create: `src/meta/service_id.py`
- Modify: `data/label_policy.yaml`
...

**Interfaces:**
- Produces: `extract_service_id(labels: dict[str, str], chain: list[str]) -> tuple[str, str]` — returns `(service_id, service_source)`
...

#### Step 1: Add `service_id_chain` to `label_policy.yaml`

- [ ] **Step 1.1: Edit `data/label_policy.yaml`** — append after `max_virtual_series`:

```yaml
# service_id_chain — ordered keys for deriving a metric's service identity
# (T2-22). The first key present in observed labels wins. Chain order:
# intentional instrumentation labels → infra labels → scrape labels.
# Changing the chain requires re-profiling affected metrics + regenerating
# templates (chain is part of the metric-identity contract).
service_id_chain:
- service
- service.name
- app
- app.kubernetes.io/name
- job
```

#### Step 2: Write failing tests for `extract_service_id`

- [ ] **Step 2.1: Create `tests/meta/test_service_id.py` with failing tests:**

```python
"""Unit tests for service_id extraction chain (T2-22)."""
from meta.service_id import extract_service_id

DEFAULT_CHAIN = ["service", "service.name", "app", "app.kubernetes.io/name", "job"]

def test_intentional_key_wins_over_infra():
labels = {"service": "payments", "app": "payments-prod-1"}
sid, src = extract_service_id(labels, DEFAULT_CHAIN)
assert sid == "payments"
assert src == "label:service"
...

ну и далее по TDD.
В плане даже команды запуска тестов и git add\git commit будут.

Детализация мягко говоря сильно отличается)

#ai

compact vs clear

Я снова про AI-шку и две типовые команды у большинства агентов /compact vs /clear.
Первая сжимает контекст, вторая начинает новую сессию.
По сути это два способа борьбы с энтропией - раздутием размера контекста и последующим ухудшением качества ответов агента.
А ухудшается оно по статистике где-то в районе 50% контекста.
Ну и борьбы со стоимостью тоже, если вы сами платите за модель)
Т.к. весь контекст при каждом запросе уходит на сервер, хоть и считается по особому тарифу (cashed).

Если запустить /compact в Claude Code - удивляет (неприятно) скорость его работы. У меня это обычно более минуты, ближе к 2.
Почему так - сжатие стало умным, т.е. вся история сессии скармливается LLM, и она выбирает важное. Можно указать это важное, явно передав текстом /compact "сохрани план работ и архитектурные требования".
Для сжатия похоже используется та же модель, что и сейчас в сессии - по крайней никакой другой информации я не вижу.
Это точно есть в Claude Code, и думаю скоро будет у всех)
К слову, есть готовые хуки, определяющие оптимальную точку для /compact с простой, я бы даже сказал "наивной" реализацией: создается PreToolUse hook для операций Edit|Write, счетчик, как только число вызовов превышает порог (50 по умолчанию) - пишем в контекст рекомендацию вызвать /compact.

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

К чему я веду - /compact видится костылем, помогающим, если вы неправильно декомпозировали задачу (story). Или пошли на поводу у модели, когда она предложила добавить в план работ еще А, Б, С... Решив, что раз это дешево - почему бы не сделать сразу)
А ведь преждевременную оптимизацию и YAGNI никто не отменял.

Итог: навык декомпозиции задач с AI остается таким же важным, как и был без нее. Бейте задачи на части, план работ и текущее состояние храните в файле (а SDD фреймворки так и делают), чаще вызывайте /clear.

#ai #ai_agents

Рубрика: "Полезное из Python"

Как вы думаете, что делает команда: uv run pytest --durations=20 ?

Ответ не очевиден (для меня): выводит 20 наиболее медленных тестов.
Вот так бы было более очевидно: uv run pytest --durations-min=1.0

Второй вопрос: что меня в этом больше всего расстраивает?)

Ответ: то, что ни в Maven, ни в Gradle тестовых плагинах ничего такого нет. Хотя можно легко завайбкодить с помощью AI.
Если быть точным: в Gradle легко, в Maven придется плагин или внешний скрипт писать.

P.S. Еще такой же паттерн использует PostgreSQL - FROM pg_stat_statements
ORDER BY total_exec_time DESC, а еще есть slow query log с фильтрацией по предельной длительности

#python #junit #unit_tests

Я не рассказал про ключевой вопрос по SDD - где находится source of truth?

До сих пор источником правды был код. По понятной причине - именно код работает на ПРОМе, не аналитика. Аналитика лежит в wiki и медленно, но верно расходится с кодом.
Сейчас мы этот разрыв пытаемся убирать, и кладем аналитику поближе к коду.

Но разрыв остается, т.к. LLM при разработке фичи условно правит 3 места:
1) спеки
2) код
3) документацию к коду
Тот факт, что правка идет в одной сессии (на одном контексте) увеличивает вероятность, что все три источника будут одинаковы.
Но не доводит ее до 100%.
А главное - зачем нам три источника?

Сложный вопрос.
Где спека точно нужна?
Спека на входе агента - да, т.е. в течение рабочей сессии.

Нужна ли она далее - вопрос?

Накину аргументы за спецификацию как источник правды:
1) спецификация упрощает совместную работу над фичей для ВП, аналитиков, разработчиков и тестировщиков. Тут наверное не поспоришь, пока в команде есть все эти роли.
Разве что тестировщики сейчас автоматизируются и идут "в код".
2) актуальная спецификация может дать возможность выкинуть код и переписать сервис с нуля. В целом да, но вообще говоря спеку можно вытянуть из кода и JavaDoc.
3) агенту (и человеку) проще дорабатывать проект. Под вопросом - при хорошо структурированном коде и наличии документации там, где она нужна. А еще индексаторы кода есть.

Про минусы я уже сказал - массовое нарушение DRY.
Почему массовое?
Потому что по факту источников больше, чем три. Новый реализуемый алгоритм появляется в:
1) коде
2) тестах
3) JavaDoc
4) spec.md
5) design.md (здесь и далее в терминологии OpenSpec)
6) proposal.md (верхнеуровнево)
7) tasks.md (на своем шаге реализации)
8) в файле с tasks от superpowers.md (при использовании superpowers)
9) AGENTS.md (такое возможно, если алгоритм влияет на требования к остальному коду. или в виде описания алгоритма как комментарий к параметрам вызова сервиса)
10) какой-нибудь скил валидации, проверяющий, что алгоритм вызывается там, где должен вызываться

И если мы поменяли название алгоритма - где его менять? Везде? Или исторические документы не трогаем? А если их кто-то прочитает?
Ясно, что это решается отдельным скилом синхронизации, но что делать с DRY?

Я пока окончательного ответа для себя не нашел, но точно понятно, что дублирование надо уменьшать.

code or not code, вот в чем вопрос?

#ai #ai_agents