Spec-Driven Development: полноценная среда разработки с ИИ-агентами

Учащийся разбирает SDD не как генерацию большого документа перед кодом, а как систему исполнимых договорённостей. Спецификация должна направлять реализацию, review и тесты и обновляться вместе с принятыми решениями. Глубина spec зависит от риска и стоимости ошибки. Темы: • product intent, requirement, constraint, design и task spec; • progressive specification: от low-risk change до архитектурного RFC; • traceability: требование → решение → код → test evidence; • definition of ready/done, change control и борьба со spec drift. Практический артефакт: maturity assessment текущего процесса и целевая карта SDD.

Модуль учит разделять документы по владельцам и сроку жизни. Бизнес-требования, архитектурные решения, policies, задачи, API-контракты и runbooks не должны превращаться в один противоречивый файл. Для каждого типа определяется owner, source of truth, схема обновления и проверка свежести. Темы: • hierarchy of specs и правила разрешения конфликтов; • RFC/ADR, task artifact, API/data contract и acceptance criteria; • owner, version, status, freshness и superseded artifacts; • machine-checkable schemas, ссылки и автоматическая трассировка. Практический артефакт: spec map репозитория и шаблоны для трёх уровней риска.

Учащийся делает правила и факты discoverable: создаёт короткий bootstrap, маршрутизацию по типам задач и отдельные owner layers. Агент получает минимум контекста, необходимый конкретной работе, а не весь архив проекта. Границы репозитория, команды проверки и неизвестные области фиксируются явно. Темы: • bootstrap/AGENTS, policy, role, workflow, context, task, checklist и eval; • repository map, stack fingerprint, implementation patterns и unknowns; • progressive disclosure и targeted discovery вместо repository dump; • local sandbox, writable roots, secrets boundary и safe defaults. Практический артефакт: минимальный agent-ready prompt pack для учебного репозитория.

Модуль связывает отдельные артефакты в процесс. Для каждого этапа определяются вход, допустимые действия, результат, проверки и stop conditions. Low-risk изменение проходит короткий путь, а архитектурное, security-sensitive или data-changing изменение получает дополнительные design/review/approval gates. Темы: • intake, classification и task artifact; • discovery, planning, implementation и change log; • code/security/architecture review и независимая verification; • release candidate, manual QA/DevOps handoff, rollback и post-release evidence. Практический артефакт: workflow graph с fast path, high-risk path и escalation.

Учащийся проектирует skills как узкие пакеты инструкций, шаблонов и скриптов, которые подключаются только по ясному триггеру. Skill должен иметь конкретный результат, предусловия, ограничения и проверку, а не дублировать роль или workflow. Разбираются lifecycle, версии, тестирование и удаление устаревших skills. Темы: • критерии «нужен skill» против обычной инструкции или workflow; • anatomy: trigger, inputs, procedure, assets/scripts, checks и fallback; • композиция skills, конфликт инструкций и context budget; • versioning, ownership, regression-evals и каталогизация. Рекомендуемые категории skills для development environment: | Категория | Когда подключать | Типичный результат | |---|---|---| | Repository discovery | Новый/неизвестный репозиторий | Карта модулей, команд и границ | | Requirements/specification | Неясная или крупная задача | Spec, acceptance criteria, open questions | | Architecture/design | Долгоживущие границы и дорогие решения | ADR/RFC и trade-off analysis | | Language/framework implementation | Изменение конкретного стека | Patch по локальным паттернам | | Testing/QA | Нужна проверка поведения | Tests, evidence и manual QA gaps | | Security/privacy review | Trust boundary или sensitive data | Threats, controls и approval gates | | Code review | Готовый change set | Findings по severity и residual risk | | Documentation/handoff | Передача или релиз | README, runbook, QA/DevOps handoff | | Prompt maintenance | Меняется agent behavior | Owner-correct prompt artifact и eval impact | Практический артефакт: три собственных skills с trigger-тестами и примерами ошибочного подключения.

MCP рассматривается как способ дать агенту структурированный доступ к данным и действиям, а не как список обязательных серверов. Учащийся начинает с read-only источников, отделяет данные от команд, документирует permissions и добавляет write-capabilities только после threat model, idempotency и approval flow. Темы: • resources, tools, prompts и границы MCP server; • authentication, least privilege, tenant/data isolation и audit log; • input/output validation, prompt injection из tool output и data poisoning; • availability, timeout, retries, rate limits и graceful degradation. Рекомендуемые классы MCP/connectors: | Интеграция | Ценность | Режим по умолчанию | Обязательный gate | |---|---|---|---| | Официальная документация | Актуальные API и версии | Read-only | Provenance и domain allowlist | | Репозиторий и code search | Код, diff, история решений | Read-only; scoped write | Branch/path scope и review | | Issue tracker/project system | Требования и статус | Read-only | Явное approval на создание/изменение | | Browser automation | Реальный UI и e2e evidence | Изолированная тестовая среда | Запрет production side effects | | Database | Схемы и диагностические данные | Schema/read-only replica | Data minimization и query limits | | CI/build system | Логи и результаты checks | Read-only | Approval на rerun/cancel/config change | | Observability | Логи, traces, metrics | Read-only | Redaction, retention и tenant scope | | Design/knowledge base | Макеты и внутренние документы | Read-only | Freshness, ACL и source attribution | | Deployment platform | Release operations | Не подключать по умолчанию | Отдельный operator approval и rollback | Практический артефакт: MCP threat model, permission matrix и интеграция минимум одного read-only connector.

RAG вводится только после постановки retrieval-проблемы: знания слишком велики, часто меняются или распределены по системам и не могут безопасно загружаться целиком. Если нужные правила малы и стабильны, прямой versioned context лучше и дешевле. Учащийся строит pipeline с доступами, provenance, цитированием, freshness и измерением recall, а не просто создаёт vector database. Темы: • decision: direct context, search/tool call, long context или RAG; • ingestion, parsing, semantic chunking, metadata и document version; • hybrid retrieval, filters, top-k, reranking и context assembly; • retrieval evals, groundedness, citation accuracy, freshness и poisoning tests. Минимальная RAG-конфигурация: 1. Определить конкретные вопросы и authoritative sources. 2. Сохранять `source_id`, owner, version, timestamp, ACL и document section. 3. Делить документы по смысловым/структурным границам, а не слепо по числу символов; сохранять заголовки и соседний контекст. 4. Использовать metadata filters и hybrid lexical/vector retrieval там, где это улучшает eval-набор. 5. Ограничивать количество фрагментов, удалять дубликаты, при необходимости применять reranking. 6. Требовать citations/provenance в ответе и отделять retrieved fact от inference. 7. Переиндексировать изменённые источники, удалять superseded документы и соблюдать ACL при retrieval. 8. Измерять retrieval recall@k, precision/relevance, groundedness, freshness и end-to-end task success на golden questions. Практический артефакт: небольшой RAG-index, набор минимум из 30 golden questions и сравнительный отчёт direct context vs search vs RAG.

Учащийся подключает multi-agent только там, где задачи действительно независимы, нужна отдельная проверка или контекст одного специалиста мешает другому. Parent остаётся ответственным за scope, интеграцию и финальную проверку; subagents получают минимальный контекст, ограниченные права и явный output contract. Темы: • single-agent baseline и критерии оправданной делегации; • task slicing, context isolation, concurrency и ownership; • implementer/reviewer separation и независимость evidence; • merge conflicts, duplicate work, handoff schema и terminal-agent limits. Практический артефакт: multi-agent workflow с двумя независимыми ветками работы и parent review.

Модуль строит layered verification: deterministic checks выполняются раньше субъективной оценки, а agent-generated code не получает доверия только потому, что выглядит правдоподобно. Риск-классификация определяет глубину review, тестирования, human approval и release evidence. Темы: • lint/type/schema/unit/integration/e2e и manual evidence pyramid; • spec-to-test traceability, contract tests и regression gates; • dependency, secret, SAST/security review и untrusted generated code; • CI isolation, reproducibility, flaky tests и performed-vs-proposed honesty. Практический артефакт: CI policy и verification matrix для трёх уровней риска.

Учащийся выбирает реальный или учебный репозиторий, создаёт минимальную SDD-среду и проводит через неё одну low-risk и одну architecture-significant задачу в безопасном тестовом scope. Оценивается не количество prompt-файлов, а предсказуемость маршрутизации, качество specs, достаточность context, независимая verification и отсутствие избыточной автономии. Темы: • baseline процесса, target operating model и success metrics; • реализация prompt pack, skills, MCP и при необходимости RAG; • два end-to-end delivery trials и анализ отказов; • governance, ownership, cost model, rollout и improvement backlog. Итоговый проект должен включать: • bootstrap и task routing; • policies, roles и workflows с ясными owner boundaries; • repository context и freshness rules; • task/spec/RFC templates и traceability; • минимум три skills и один read-only MCP connector; • обоснованное решение о RAG: working prototype с evals либо documented no-RAG decision; • CI/verification gates, review flow и manual handoff; • dashboard метрик, failure log, rollback/fallback и план сопровождения.