10 мин

27

Привет, Хабр! Меня зовут Даниил, я программист и архитектор, разрабатываю программное обеспечение и спецификации для создания ПО в YADRO. Продолжаю цикл статей об организации рабочего места по методу Spec-Driven Development. В первой части мы настроили агента Claude Code. Во второй расскажу, как настроить harness — программную инфраструктуру, выступающую оберткой для LLM, и наконец поделюсь решением задач по методу SDD. 

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

Но сначала поправлю факт из первой статьи. Если вы решили попробовать DeepSeek модели V4 и наткнулись на Error 400, вам сюда. Также рекомендую попробовать DeepSeek V4 Flash. Очень достойная модель, особенно для SDD, и самая дешевая на сегодня.

Контекстная дисциплина как основа успешного применения LLM в работе

Напомню, что LLM — это просто большой преобразователь одного текста в другой. Для правильного преобразования мы должны выдать ему нужные тексты и не выдать ненужные. Звучит очевидно, но это и есть контекстная дисциплина, и Spec-Driven Development — довольно эффективный способ эту дисциплину обеспечивать. Все дополнительное ПО, которое мы устанавливаем поверх агента, служит одной цели: обеспечить поставку всего нужного в контекст и по возможности не допустить поставку ненужного.

Важно помнить, что любое средство, которым может воспользоваться модель, должно быть представлено в контексте. ПО с неточным описанием, слишком много инструментов и некачественные тулы размывают контекст. Надо строго следить за тем, что мы ставим в агента, что мы кладем в папку нашего проекта, и даже за тем, что мы открываем в окне нашего проекта. Исходя из этого мы и будем формировать наши «представления о прекрасном».

Что выбрать — Model Context Protocol или Skills

Почему-то этот вопрос первым всплывает при обсуждении оснастки AI-агента.

Никакой разницы нет. Технически вызов skills и MCP-сервера отличаются радикально, но это внутреннее дело агента, для модели все выглядит одинаково: 

• краткое описание, включенное в контекст;  

• развернутое описание, предоставляемое по запросу; 

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

А вот если вы сами будете писать оснастку для своего агента — разница есть, и существенная. Для MCP-сервера надо реализовывать протокол на базе JSON RPC, для skill достаточно скрипта на любом языке, возвращающего результат в свободной форме, а то и просто markdown-описания.

Делайте выводы.

Глобальная установка или установка для конкретного проекта

Как я писал выше, каждое ПО добавляет несколько строк к контексту. Это нужно, чтобы модель могла узнать об инструменте и вызвать его. Все, что установлено глобально, добавляет свои строки к каждому запросу. То, что установлено для конкретного проекта, — только для запросов в рамках этого проекта.

Под описаниями инструментов в следующем блоке я отметил, что рекомендую ставить глобально, а что — в рамках проекта. Но слегка вас обманываю, потому что методами установки, которые я там рекомендую, поставить плагин для проекта нельзя, только глобально. Метод установки для проекта описан в документации, и он не работает в VSCode, надо запустить Claude Code в консоли.

Как выбрать, что ставить

Универсальный совет: ставьте как можно меньше. Ставьте только то, в чем назначении вы уверены, удаляйте то, что не пригодилось. Маленький специализированный инструмент лучше большого комбайна. Отдельные инструменты лучше наборов.

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

Я ищу нужные инструменты в Google или в Perplexity. От специализированных агрегаторов вроде Agent Skills Marketplace я отказался — поисковики общего назначения ищут не хуже, но выглядят удобнее и привычнее.

В мой департамент ищем талантливого Go-разработчика. Мы создаем единую программную экосистему для всех продуктов компании, пишем Linux based-дистрибутив и разрабатываем системное ПО. Если вы в системном программировании больше трех лет и уверенно владеете Go, откликайтесь на вакансию.

Система плагинов Claude Code

Поставить skill очень просто: надо положить его в ./.claude/skills для установки в проекте или в ~/.claude/skills для установки глобально.

Аналогично для команды, только вместо skills надо писать commands.

Но мы все-таки используем штатную процедуру установки плагинов для Claude Code, через claude plugin, или /plugin:

• Если поставить надо больше одного файла, скрипты установки сделают это за нас.

• Можно включить autoupdate.

Что ставим обязательно

Самый простой способ узнать, что у вас уже есть — это спросить у самой модели: «Расскажи, какие tools, MCP и skills тебе доступны». Очень познавательное чтение, рекомендую. Так я узнал, что skill webfetch, который был весьма полезен на RooCode, не нужно нести в Claude Code — в нем есть такой стандартный.

Поиск в интернете

Интернет полон восторгов в отношении Anthropic: люди рассказывают друг другу, как прекрасно эти модели справляются с задачами. Если приглядеться, примерно 50% этих восторгов обеспечены тем, что модели Anthropic умеют пользоваться интернет-поиском.

В Claude Code есть стандартный инструмент websearch, но в нашем сетапе он выключен, потому что поддержка поиска в интернете предоставляется моделям Anthropic с серверов Anthropic и отсутствует у других провайдеров. Вернее, поддержка может быть, а может и не быть. Например, Z.AI предоставляет на своих тарифах поисковый MCP, и он весьма полезен, но лимиты на его использование отнюдь не щедрые. А OpenCode Go не предоставляет поисковик.

В общем, нам надо снабдить наш Claude Code возможностями поиска.

Казалось бы, в чем проблема, есть же Google. Но Google — не для роботов! Google живет с показа нам, кожаным, рекламы, и Claude Code, который рекламу просто проигнорирует, там никто не ждет,. То есть подключить-то можно, но доступ будет платным, и расценки там негуманные.

Так что надо поискать другие способы, например DuckDuckGo API. Вариантов, как водится, больше одного, поисковик вам в помощь.

Я для себя ничего, что устраивало бы меня на 100%, не нашел, поэтому напрограммировал свое. Посмотрите, вдруг и вам подойдет. 

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

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

claude plugin marketplace add Djarvur/cc-mplace &&
 claude plugin install cc-websearch

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

Документация к библиотекам

В каждой статье о настройке AI-powered рабочего места упоминается MCP Context7. И это архиправильно, товарищи!

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

Зайдите на сайт, создайте бесплатный аккаунт, сгенерируйте ключ и используйте его при конфигурации. Бесплатный Context7 только for individuals, как водится, и, возможно, это помешает с ним работать… Но без указания ключа вы, скорее всего, не получите от Context7 ничего, кроме 429 Rate limit.

Context7 MCP есть среди официальных плагинов Claude Code, оттуда его и надо ставить. 

Как ставить: этот плагин будет полезен в абсолютно любом программистском проекте, так что смело ставьте его глобально.

LSP

Среди стандартных плагинов Claude Code есть Language Server Protocol для всех популярных языков. Ставьте, они реально помогают!

Важное: ставить их я рекомендую per-project, потому что едва ли вам нужен Rust LSP в контексте Go-проекта. А понадобится — доставите. Как вариант, можно использовать Serena MCP. Если честно, я не смог понять, имеет ли смысл использовать Serena вместе или вместо стандартных LSP-плагинов. В конце концов сама Serena подключает все те же LSP.

Советую вам провести собственные эксперименты. Да, Serena есть в официальных плагинах Claude Code, но Serena README рекомендует ставить ее руками с GitHub. Вариант ручной установки лучше плагинного тем, что можно легко поставить Serena для проекта, не глобально.

Как ставить: per-project.

GitHub

В стандартных плагинах есть поддержка и GitHub, и GitLab.

Для BitBucket среди стандартных плагинов ничего не нашел. Пользуюсь самописным, на bash, который вычитывает из конфигурационного файла access token и запускает curl с правильным Authentication header. В SKILL.md — краткая выжимка из описания BitBucket HTTP API. Хватает, чтобы давать Claude Code задания типа «вот PR URL, извлеки комменты, оцени полезность и релевантность, предложи исправления».

В интернете есть разные более умные skills для BitBucket, но рекомендовать их вам я не могу — не пробовал. Советую вам провести собственные эксперименты.

Как ставить: глобально.

Atlassian

Atlassian предоставляет доступ к Jira и Confluence. Практически для всех таск-трекеров и инструментов совместной работы есть плагины, для популярных — официальные. Тут все однозначно, надо ставить, хотя бы чтобы давать задания вроде «вот Issue URL, проанализируй и придумай fix».

Как ставить: я ставлю per-project, чтобы OSS-проекты, над которыми я работаю, не опубликовали случайно что-нибудь из секретного раздела Confluence. Не гарантия, но приемлемое снижение вероятности.

Caveman

То, что должно быть частью любого стандартного промта, но почему-то не стало: skill снижает градус многословия модели без потери смысла, уменьшая расход выходных токенов на ~75%. Ставить или нет, решать вам, разговаривать модель начинает довольно забавно, но выходные токены — дорогие. Не исключено, что хозяева моделей так на нас зарабатывают.

Искать здесь.

Ставить в Claude Code вот так:

claude plugin marketplace add JuliusBrussee/caveman &&
 claude plugin install caveman@caveman

Если стоимость токенов вас не интересует, потому что у вас хорошая подписка — учтите, что на генерацию этих «лишних» токенов тратится время.

Как ставить: per-project. Либо включать, выключать и настраивать этот плагин в рамках текущей сессии.

Sequential thinking

Самый сомнительный пункт в моем списке: sequential thinking skill.

Заставляет модель потратить побольше токенов на пошаговые рассуждения. С хорошими моделями почти бесполезен, со слабыми — помогает модели выбраться из тупика практически всегда. Был прям спасением осенью 2025 года, когда я сидел на GLM-4.7, но на современных моделях я им практически не пользуюсь.

Сомнителен этот пункт, потому что сценарии SDD-инструментария уже содержат все необходимое, чтобы этот skill оказался бесполезен. Советую вам провести собственные эксперименты.

Инсталляция:

claude plugin marketplace add nsheaps/ai-mktpl &&
 claude plugin install sequential-thinking@ai-mktpl

Расширенная поддержка языка программирования

Лично я пишу на Go, и рассказать, соответственно, могу вам только про этот язык. Для Go ставлю:

• modern-go-guidelines;

•  cc-skills-golang;

• go-best-practices (репозиторий сделан для Gemini, так что именно этот набор приходится ставить руками);

• gopilot.

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

Для создания собственных плагинов ставлю:

• agents-best-practices,

• plugin-dev,

• skill-creator,

• mcp-server-dev.

Как ставить: первый пак плагинов ставлю глобально, потому что большинство моих проектов написаны на Go. Второй — per-project. 

C отдельными инструментами разобрались. Дальше посмотрим, какой SDD kit подойдет под ваш сценарий работы.

Собираем инструментарий для Spec-Driven Development

Ну и наконец то, ради чего все затевалось: SDD-инструментарий. Сразу оговорюсь, что этот инструментарий — не единственный способ делать SDD и даже, возможно, не лучший.

Я знаю людей, которые создают свой собственный SDD kit параллельно с созданием проекта под него, и у них получается. В конце концов, любой SDD kit — это набор сценариев и шаблонов, иногда — скриптов им в поддержку. Но у меня, к сожалению, нет столько времени, поэтому я беру готовые наборы и пилю проекты на них. Для разных проектов беру разные инструменты.

Все инструменты, о которых пойдет речь ниже, я ставлю строго per-project, потому что:

• Для разных проектов — разные инструменты.

• Некоторые проекты я перевожу с одного инструмента на другой.

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

Разберем разные SDD kit, чтобы вы могли прикинуть, какой вам ближе. Напишите в комментариях, о каком инструменте написать в следующей статье. 

OpenSpec

Установить →

Девиз: the most loved spec framework.

В OpenSpec — самые человекочитаемые документы. Другие особенности: 

• Встроенные средства развития спецификации: если в процессе развития проекта решения пересматриваются, общая спецификация корректируется автоматически.

• Рудиментарные средства сбора информации: все, что вы хотите, чтобы было учтено, надо указать явно.

• Рудиментарные средства для исследовательской фазы: надо явно сообщать, какие именно исследования надо провести.

• Рудиментарные средства декомпозиции: о разбиении задачи на подходящие этапы вам надо думать самостоятельно.

Если надо сделать небольшую задачу и обсудить спецификацию до реализации с живыми коллегами, OpenSpec — ваш выбор.

Get shit done

Установить →

Девиз: the complexity is in the system, not in your workflow.

Особенности:

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

• Лучший из опробованных сценарий декомпозиции. Практически никогда мне не хочется внести исправления в разбиение на этапы.

• Самый внятный сценарий проверки получившейся спецификации на внутреннюю непротиворечивость и полноту.

• Процесс интервью может быть утомительным. Это робот, он задает тупые вопросы.

• Сложности с чтением документов. Используется специфический формат и система перекрестных ссылок. Файлов много и назначение их не всегда ясно.

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

Если у нас большая и технически сложная задача, которую надо доформулировать и доформализовать в процессе реализации, GSD — ваш выбор.

BMAD-метод

Установить →

Девиз: build more architect dreams.

Особенности:

• Лучше всех знает, как работать с непонятными идеями. Задает вопросы, анализирует ответы, возвращается к обсужденному ранее, если новые ответы противоречат старым.

• Самая развитая архитектурная составляющая. Задает вопросы про то, «что надо сделать», не только про «как».

• Самые развитые исследовательские сценарии. Проводит дополнительное исследование темы по собственной инициативе.

• Довольно долгий путь от первичного описания задачи до ее реализации.

• Не вполне внятный сценарий модификации спецификации в процессе развития проекта.

Если вы пока не знаете, как реализовать идею, и хотите сформулировать ее в архитектурных документах, BMAD — ваш выбор.

Spec-Kit

Установить →

Девиз: build high-quality software faster.

С этого инструмента началось мое знакомство с SDD: я за несколько вечеров написал линтер, который без Spec-Kit писал бы пару месяцев, а без AI не написал бы никогда.

Сейчас я этим инструментом практически не пользуюсь. У него нет ни ярко выраженных недостатков, ни очевидных достоинств — средний во всем. Когда-нибудь я попробую сделать на нем еще проект, чтобы оценить заново. Например, для написания статьи :)

Заключение

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

Напишите в комментариях, хотели бы вы узнать о недостатках Spec-Driven Development, или сразу перейдем к разбору инструментов. И задавайте вопросы в комментариях.