Spec-Driven Development и системность процессов

Как выстроить систему SDD: от требований к дизайну

Вопросы участников:

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

Механика. Идея SDD — перевернуть привычный порядок: не код, а спецификация становится источником правды, а код — производный артефакт, который можно перегенерировать. Спека отделяет что и зачем от как: требования и критерии приёмки не должны называть стек и детали реализации — иначе модель воспримет ваши подсказки как жёсткие ограничения и перестанет искать лучшее решение.

Систему из этого делает не один промпт, а воспроизводимая последовательность фаз, где каждая даёт артефакт-вход для следующей. Канонический конвейер GitHub Spec-Kit выглядит так:

Constitution — один раз на проект: неизменные принципы и стандарты, против которых валидируется каждая последующая фаза. По сути это системный промпт репозитория.
Specify — требования, сценарии, критерии приёмки. Только что и зачем, без стека.
Clarify — агент сам ищет пробелы и задаёт точечные вопросы: edge-кейсы, поведение при ошибках, конкурентный доступ. Здесь SDD окупается, даже если сгенерированный код выбросить.
Plan — вот теперь как: архитектура, стек, библиотеки. План ограничен конституцией; Spec-Kit генерирует секцию Constitution Check и помечает выборы, нарушающие принципы.
Tasks — план дробится на атомарные задачи с зависимостями и пометками параллельного запуска.
Analyze — сквозная проверка согласованности спеки, плана и задач. Шаг, который чаще всего пропускают и на котором ловится тихое расхождение.
Implement и Converge — генерация по задачам и финальная сверка кодовой базы с артефактами.

Для вопроса о сборке дизайна по требованиям ключевое — жёстко разделить фазы specify и plan и не пускать дизайн вперёд требований. Дизайн (фаза plan) обязан быть выводим из спеки и ограничен конституцией, а не придуман параллельно. Академический разбор SDD Spec-Driven Development: From Code to Contract вводит три уровня строгости и золотое правило: берите минимальную строгость, которая убирает неоднозначность для вашего контекста.

spec-first — написали спеку, сгенерировали код, дальше поддерживаете код. Годится для старта фичи.
spec-anchored — спека живёт постоянно, изменения идут через неё и распространяются в код. Это выбор для долгоживущих продакшн-систем и регуляторики.
spec-as-source — спека и есть исходник, код эфемерен и перегенерируется. Требует зрелой и доверенной генерации.

Чтобы навести систему там, где каждый делает по-своему, закрепите три вещи в репозитории: файл CONSTITUTION.md с 5–10 принципами, каталог specs/ с отдельным файлом на значимую фичу и тест-набор, которому вы доверяете настолько, чтобы пускать через него регенерацию.

Что пойдёт не так. Главная ошибка — применять полный цикл к однострочной правке: на баг с null-проверкой не нужны конституция и восемь фаз. Microsoft прямо пишет, что не каждое изменение требует всего цикла, и советует right-sizing. Вторая ошибка — смешивать что и как в спеке: реализационные подсказки в требованиях ухудшают результат. Третья — пропускать clarify и analyze: именно там ловятся расхождения, пока их ещё дёшево чинить.

Ссылки

Как системно улучшать качество и эффективность агента

Вопросы участников:

Контекст: Spec-Driven Development Для работы над качеством и скоростью постоянно на проекте улучаю скилы и рулы, задаю каноны. Создаю MCP (например, для быстрых походов в ELK и тд). Но, периодически, агент наступает на грабли. Из-за этого страдает скорость решения: например, неоптимальное количество прогонов тестов, игнорирование кодинг стандарта при разработке, вызовы каких-то команд с ошибочными флагами и тд. При этом, если после спотыкания в агента ткнуть нужным скилом - он все четко сделает. Т.е на практике пришел к тому, что работает постоянное непрерывное улучшение и подкручивание процесса, скиллов, рулов и тд. Т.е по сути есть некоторые метрики и показатели, которые снимаю, пишу, слежу. Вопрос: а как вы системно улучшаете качество и эффективность работы агента на проектах?

Механика. Ваш опыт — что агент слушается, когда его ткнуть нужным скиллом, — это не случайность, а прямое следствие того, как загружается контекст. Anthropic разбирает семь механизмов управления поведением, и у каждого три разных свойства: когда инструкция попадает в контекст, переживает ли она компакцию — сжатие длинной сессии, — и какой у неё авторитет.

CLAUDE.md грузится в начале сессии и висит всю сессию. Это факты на каждый день: команды сборки, раскладка репозитория, конвенции. Дорого по токенам — каждая строка тратит бюджет, релевантна она или нет.
Rules (.claude/rules/) — конкретные ограничения. Их можно сделать path-scoped: правило грузится только когда трогается подходящий файл.
Skills — процедуры, которые грузятся по требованию. Anthropic называет это progressive disclosure: сначала имя и описание, тело — при вызове (разбор в Agent Skills). Именно поэтому тычок скиллом чинит поведение: вы догружаете нужную процедуру в контекст.
Hooks — детерминированные обработчики на события жизненного цикла. Срабатывают в обход модели и компакции.

MCP-серверы (ваши походы в ELK) — из другого класса: они расширяют, что агент умеет делать, но надёжность дают не они, а гейты вокруг вызовов инструментов.

Ключевой сдвиг для ваших граблей: CLAUDE.md и rules — это контекст, а не гарантия исполнения. Модель следует им почти всегда, но под давлением длинной сессии, неоднозначности или инъекции из читаемого файла — может не последовать. Поэтому:

Каждый раз X → hook, а не проза. Прогон линтера после правок, запрет опасных флагов, форматирование — это PreToolUse/PostToolUse hooks и permissions, а не строчка YOU MUST в CLAUDE.md. Хук с выходом кода 2 жёстко блокирует вызов; управляемые настройки закрепляют правило на уровне организации.
Никогда не делай X → permissions/hook. Ошибочные флаги и лишние прогоны тестов лечатся не просьбой, а allowlist разрешённых команд и блокировкой остального.
Правило для части кода → path-scoped rule. Кодинг- стандарт для src/api/** держите в правиле с полем paths, чтобы он не тонул в общем шуме и не тратил контекст на несвязанной работе.
Раздутый CLAUDE.md — причина, а не лечение. Когда файл длинный, важные правила теряются в шуме и модель их игнорирует. Держите его до ~200 строк, ревьюйте как код, лишнее выносите в rules и skills.

Теперь про метрики и петлю улучшения — это ядро вопроса. Инженерная дисциплина здесь такая же, как в SDD: привязывать улучшения к измеримому оракулу, а не к ощущению. Практики, которые работают:

Базовое сравнение вместо интуиции. Чтобы понять, что скилл или правило реально помогает, гоняйте набор реалистичных промптов дважды — со скиллом и без — в свежих сессиях и сравнивайте результат. Свежая сессия важна: остаточный контекст маскирует пробелы в инструкции.
Метрики из ваших же наблюдений. Работа AutoLibra показывает, как превращать неформальные заметки вида агент опять вызвал не тот флаг в структурированные метрики оценки, привязанные к конкретному поведению, с мета-метриками покрытия и избыточности. Это ровно ваш случай: вы уже снимаете показатели — формализуйте их в оценочную рубрику.
Провалы из продакшена → в набор регрессии. Каждый случай, где агент наступил на грабли, превращайте в постоянный тест-кейс. Так разовая боль становится оракулом, который ловит регресс навсегда.
Петля с защитой от дрейфа. Разбор The Kitchen Loop описывает самоэволюционирующую кодовую базу из четырёх частей: поверхность спецификации (что продукт обещает), синтетическое нагрузочное тестирование пользователями, непобедимые тесты как истинный оракул и контроль дрейфа с автоматическими гейтами. На двух продакшн-системах — 1094+ смёрженных PR без регрессий за 285+ итераций. Урок: непрерывное улучшение безопасно только когда привязано к спеке и к тестам, которые нельзя обойти.

Что пойдёт не так. Если оптимизировать скиллы и рулы без регрессионного оракула, вы будете чинить одно и ломать другое, не замечая этого. Если складывать всё в CLAUDE.md как гарантию исполнения — под нагрузкой правила будут теряться. И если снимать метрики, но не привязывать их к фиксам, они станут дашбордом без петли: покажут деградацию, но не предотвратят её.

Ссылки

Как использовать spec driven development (SDD) на существующей системе с микросервисами и множеством отдельных репозиториев?

Механика. На существующей системе порядок обратный гринфилду: спеку не пишут с нуля, а извлекают из текущего поведения. Сначала реверс-спека — агент по коду и документации восстанавливает, что сервис делает сейчас, — и только потом вы двигаетесь в режиме spec-anchored: спека живёт рядом с сервисом и меняется раньше кода. Полный spec-as-source для легаси преждевременен: генерация ещё не заслужила доверия.

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

Работа Spec Kit Agents предлагает лечение — context-grounding: на каждой фазе агент через read-only probing hooks смотрит в реальный код, а validation hooks сверяют результат с ним. На оценке из 32 фич в пяти репозиториях подход держал 99.7–100% совместимости тестов на уровне репозитория. Практический вывод: живая спека должна отслеживать изменения интерфейсов между сервисами — когда агент поменял форму ответа API, это сразу отражается в спеке, и видно, каких потребителей чинить.

Как организовать по репозиториям:

Конституция на сервис, а не одна на всё. У каждого сервиса свои неизменные принципы и свой каталог specs/. Одна гигантская спека на всю систему нечитаема и быстро расходится с кодом.
Контрактные спеки на границах. Спека уровня контракта (например, OpenAPI) на стыке сервисов позволяет вести параллельную разработку и ловит интеграционные сбои до сборки.
Иерархия инструкций под репозиторий. В монорепозитории Claude Code подтягивает корневой и вложенные CLAUDE.md, а path-scoped rules грузятся только для своих путей. Для мультирепозитория ту же роль играет конституция и правила внутри каждого репозитория плюс общий слой на уровне организации.

Что пойдёт не так. Первая ошибка — одна спека на всю систему: она превращается в неподдерживаемый монолит и дрейфует от сервисов. Вторая — извлечь спеку один раз и забыть: без spec-anchored дисциплины она устаревает за недели. Третья — игнорировать контракты на стыках: тогда агент меняет форму ответа в одном сервисе и молча ломает потребителей в других репозиториях. И не раскатывайте полный цикл на всё сразу — Microsoft советует начать с одной болевой фичи, где расхождение видно, и расширять по мере доверия.