From dev-pomogator
Greenfield architecture decisions — enumerates tech-stack axes from a PRD, generates per-axis multi-variant markdown + self-contained HTML (rendered in browser), auto-applies the recommendation (auto-mode default) with optional override, cascades dependent axes. Standalone triggers (RU): "выбери стек", "спроектируй архитектуру", "архитектура для", "варианты архитектуры"; (EN): "choose stack", "design architecture", "architecture decision", "stack options". Also invoked by create-spec Phase 1.75 (greenfield only) once for axis-enumeration plus once per axis. Do NOT use for brownfield refactors (existing build manifest), single-tech feature decisions, or post-implementation reviews.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev-pomogator:architecture-decision-builderThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Для greenfield-проекта (только PRD-маркдауны, кода нет) разложить выбор стека на decision-axes (database / auth / hosting / email / ...), и по каждой оси выдать ≥3 варианта с pros/cons/cost/«когда выбрать»/рекомендацией — как markdown + self-contained HTML (открывается в браузере, markdown глазами читать тяжело). Helper-скрипты — детерминированная механика (detect/render/compile/audit); **проза...
Для greenfield-проекта (только PRD-маркдауны, кода нет) разложить выбор стека на decision-axes (database / auth / hosting / email / ...), и по каждой оси выдать ≥3 варианта с pros/cons/cost/«когда выбрать»/рекомендацией — как markdown + self-contained HTML (открывается в браузере, markdown глазами читать тяжело). Helper-скрипты — детерминированная механика (detect/render/compile/audit); проза-анализ вариантов (pros/cons с пруфами) — твоя работа как LLM, mirror variant-matrix (helpers parse, skill fills content).
При генерации каждого варианта ОБЯЗАТЕЛЬНО:
[VERIFIED via <source>] или [UNVERIFIED]. Cost — cited или [UNVERIFIED — knowledge cutoff], не голые уверенные числа.mcp__context7__resolve-library-id → mcp__context7__query-docs и пометь [VERIFIED via context7:<lib> <ver>]. Если context7 не нашёл библиотеку → [UNVERIFIED — Context7 no match], НЕ выдумывай. context7 недоступен/rate-limit → fallback на тот же [UNVERIFIED] маркер (не blocking).VariantModel.correction_log[] строкой «предполагал X → обнаружил Y → исправил потому что Z». Рендерится секцией ## Corrections. Не выдумывай фейковые корректировки если их не было — пустой log не рендерит секцию.business_summary (бизнес-линза, plain language): gets (какую способность получает бизнес), time_to_market (срок до первого результата), cost (деньги: старт + при росте), risk (главный бизнес-риск). Без жаргона — это читает не инженер.scorecard[] (имплементатор-линза, многокритериальная карта): по КАЖДОМУ критерию {criterion, verdict (good/ok/bad), value, source?}. Обязательный набор критериев: Стоимость, Лёгкость интеграции, Кривая обучения, Ops-нагрузка, SSL/HTTPS, Масштабирование, Vendor lock-in, Экосистема (+ axis-специфичные). Критерии должны совпадать у всех вариантов оси (иначе карта-сравнение кривая). verdict нормализован по СМЫСЛУ: good=зелёный (хорошо для проекта), bad=красный — «ops низкий»=good, «lock-in высокий»=bad.reality_check[] («из реала» — то что укусит, а вендор замалчивает): что придётся НАСТРАИВАТЬ И СКЛЕИВАТЬ РУКАМИ. Обязательно покрой, если применимо: SSL-серты + HTTPS-конфиг (certbot/nginx/auto-renew), бэкапы + проверка restore, мониторинг + алерты, secrets-wiring/ротация, обновления безопасности ОС, склейка между компонентами (firewall, healthchecks, межсервисная авторизация). Для managed-платформ честно пиши что покрыто платформой, а что всё равно на тебе (алерты, custom-домен серт, бэкапы на free-плане). Голый «good/bad» буллет НЕ заменяет reality_check — это конкретные операционные шаги.source). «Источников мало» = провал R3/R8.cost_at_scale[] — кривая ДЕНЕГ, не точка: [{tier:"MVP/100",cost:"$0"},{tier:"10k",cost:"$25"},{tier:"100k",cost:"$300+"}]. Ловушка дешёвого MVP должна быть видна.time_costs — кривая ВРЕМЕНИ команды (деньги это не всё): to_market (до первого прода), to_feature (типичная фича на этом стеке), to_test (настройка+прогон тестов), to_support (мейнтенанс в месяц). Считай ВСЕ четыре — выбор который дёшев деньгами, но жрёт время на тесты/поддержку, должен это показать.exit_cost (на варианте) — конкретная цена СЛЕЗТЬ («Postgres выгрузишь легко, Auth+RLS переписывать ~2 нед»). Делает Vendor lock-in не ярлыком, а числом.door_type (на оси) — one-way (необратимое, выход дорогой → ресёрчь в 10× глубже) vs two-way (обратимое → не переусердствуй). Рамка Bezos: БД/auth обычно one-way, email/CDN — two-way.sensitivity[] (на оси) — «рекомендация МЕНЯЕТСЯ если…»: ["→ Railway если нужен чистый Node-рантайм","→ VPS если бюджет критичен И есть devops"]. Решение как функция параметров, не догма.real_world_precedent[].relevance — ПОЧЕМУ пруф релевантен ИМЕННО этому проекту (похожая система/кейс), не просто звёзды. «74k★» доказывает популярность, не пригодность для cron+webhook+SMS. Ищи прецедент похожей системы.Рекомендация зависит от ЦЕЛИ проекта, не абсолютна. Перед per-axis loop выбери политику ОДИН раз глобально (step 1.5 ниже). 5 политик:
| PolicyId | Цель | recommended-вариант |
|---|---|---|
mvp-poc (default) | Прототип/MVP — быстрее запуститься (time-to-market↓) | самый простой/быстрый в реализации |
production-grade | Прод на годы | надёжность/SLA/observability |
cost-optimal | Минимум денег | самый дешёвый при приемлемом качестве |
scale-ready | Рост нагрузки | горизонтальное масштабирование |
portability | Без vendor lock-in | переносимость между провайдерами |
Каждому варианту проставь policy_fit: PolicyId[] (под какие политики он оптимален). Helper выбирает recommended = вариант чей policy_fit включает selected_policy (fallback is_recommended). Артефакт рендерит demonstration-таблицу (вариант × 5 политик) — наглядно показывает что выбор зависит от цели. Default mvp-poc обоснован: проще/быстрее → TTM↓; не требует обязательного ответа (auto-mode сохранён).
CLI: tools/specs-generator/architecture-decision/architecture-decision-cli.ts
detect-axes <prd-path> → {axes_detected, axes[], skipped_reason?}. 3-layer detection (BMAD seed + keyword + NEEDS CLARIFICATION). Brownfield build-manifest → axes_detected=0.generate-axis <axis-model.json> <outDir> → {mdPath, htmlPath, wordBudgetOk}. Рендерит AxisModel (варианты заполнены тобой) в md+html. Recommendation pinned top.open-browser <html-path> → {launched, fallback?}. Cross-platform, ENOENT-safe.compile-index <spec-dir> → {axes_total, axes_pending, rows}. Idempotent INDEX.md+html.audit <spec-dir> → {findings[]}. ARCHITECTURE_COVERAGE (FR-9, 9-я категория): pending axis→WARNING, accepted→MATRIX_COMPLETE, escape→ESCAPE_HATCH_USED/WARNING_REASON_TOO_SHORT.audit-completeness <spec-dir> → {findings[]}. COMPLETENESS_COVERAGE (FR-12, 10-я категория): читает COMPLETENESS.md ledger (8 dimensions) — pending/missing→DIMENSION_PENDING WARNING, all addressed/out-of-scope→COMPLETENESS_COMPLETE, escape [skip-completeness-dimension:]→WARNING_REASON_TOO_SHORT. Отдельная команда (не merged в audit — architecture audit unmixed для eval determinism).synthesis <spec-dir> [insights.json] → {synthesisMd, insights_count, rejected[]}. FR-13 cross-axis synthesis: ты авторишь insights[] ({axes[≥2], title, description, recommendation, trade_off?}) в JSON, helper валидирует (каждый insight ссылается на ≥2 РЕАЛЬНЫХ axis-id) + рендерит SYNTHESIS.md+.html. Невалидные → rejected[] с причиной (не silently). insights_count=0 валидно (1-axis spec).record-verify <spec-dir> <lib> [ver] → {recorded}. FR-20 anti-hallucination: вызывай ПОСЛЕ реального context7-вызова, чтобы подкрепить [VERIFIED via context7:<lib>] маркер. Пишет в .architecture-verify.jsonl.audit-markers <spec-dir> → {findings[]}. FR-20: сканит AXIS-*.md на [VERIFIED via context7:<lib>], сверяет с verify-log; маркер без записи → UNBACKED_VERIFIED_MARKER WARNING (фабрикованный пруф). Presence маркера ≠ правдивость — gate делает R3/R15 аудируемыми, не trust-based.full-report <spec-dir> [insights.json] → {reportPath, axes_count, insights_count, completeness_count}. FR-19: собирает ЕДИНЫЙ self-contained ARCHITECTURE.html из AXIS-*.model.json (пишутся generate-axis автоматически) + insights + COMPLETENESS.md → index-матрица + каждая ось (богатые карточки: 2 линзы + scorecard + reality + экономика) + synthesis + completeness. Рендерится через те же renderAxisSection/renderSynthesisSection (НЕ скрейп HTML) — отчёт наследует весь rich-контент. Запускать ПОСЛЕ всех generate-axis + synthesis.detect-axes <prd> → tier-grouped список (Critical/Important/Deferred). Если brownfield (axes_detected=0) → выйти, сообщить skipped_reason. Иначе показать оси, write QUEUE.json.
1.5. Policy selection (FR-16) — ОДИН раз глобально. AskUserQuestion: «Под какую цель выбираем стек?» с опцией [MVP / прототип] ПЕРВОЙ (Recommended) и [Production]. Это единственный полу-блокирующий вопрос; default — mvp-poc (если auto-mode / нет ответа). Запиши selected_policy в QUEUE.json, прокидывай в каждый AxisModel. НЕ спрашивай политику per-axis — она глобальна.policy_fit[]). ≥1 вариант вне очевидного дефолта (R8). Проставь selected_policy (из step 1.5) в AxisModel.generate-axis → md+html (recommended выбирается policy-aware: policy_fit ∋ selected_policy, fallback is_recommended; рендерит demonstration-таблицу + policy-badge). open-browser.compile-index.COMPLETENESS.md рядом с INDEX — markdown-таблица | Dimension | Status | Pointer / Reason | из 8 system-completeness измерений: internal-consistency, flow-completeness, compliance-privacy, auth-secrets, observability, data-lifecycle, cost-quota, deploy-ops. Каждое: addressed (+ где в дизайне) / out-of-scope ([skip-completeness-dimension: <reason ≥12>]) / pending. cost-quota оцени ДО lock осей — единственное измерение, которое может изменить axis-решение (напр. poll-cadence выбивает invocation-quota → переключись на event-driven ДО фиксации стека). Per-axis качество (R1-R12) ≠ полнота системы (R13-R20): ось может быть «выбрана отлично», а флоу/секрет/комплаенс/стоимость — пропущены. Маппинг измерений ← 12 реальных дыр scenario-bhph → AWS Well-Architected.
Agent tool), который НЕ писал архитектуру — настоящая вторая пара глаз, не самопроверка. Дай ему ТОЛЬКО 8 пунктов + PRD + дизайн (не свои выводы), попроси для КАЖДОГО пункта сверить «PRD требует X — закрыт ли X реальным компонентом дизайна?» и вернуть status + пруф-ссылку (addressed без пруфа = подозрительно). «PRD хочет, компонента нет» = pending. Self-grade замылен — подтверждено research (CorrectBench/DeepVerifier) И слепым прогоном bhph (автор пропустил 3 дыры, свежий агент нашёл за проход).
3.5. Cross-axis synthesis (FR-13). Когда все оси resolved — прочитай все AXIS-*.md side-by-side и найди emergent-выводы поперёк осей (cross-axis dependency / избыточность компонента / вторичный эффект). Главный кейс bhph «Variant F» был именно такой: hosting=Supabase + auth=Supabase → n8n-orchestrator избыточен. Заавторь insights[] (каждый axes[] ≥2 реальных axis-id) в JSON → synthesis <spec-dir> insights.json → SYNTHESIS.md+html. Проверь rejected[] в ответе (insight с <2 осями или unknown axis-id отклонён). 0 insights валидно (независимые оси / 1-axis spec).audit <spec-dir> (ARCHITECTURE_COVERAGE — нет pending осей) И audit-completeness <spec-dir> (COMPLETENESS_COVERAGE — все 8 измерений addressed/out-of-scope). Любой AXIS_PENDING / DIMENSION_PENDING WARNING блокирует STOP — закрой ось/измерение, отметь out-of-scope с reason, или escape. Команды раздельны намеренно: architecture audit остаётся unmixed для eval-детерминизма.full-report <spec-dir> [insights.json] → единый ARCHITECTURE.html (index-матрица + все оси с богатыми карточками + synthesis + completeness, self-contained). open-browser на него. Одним сообщением показать все авто-выборы. Юзер переопределяет в свободной форме («ось hosting — возьми Variant B»). INDEX.html остаётся как лёгкая статус-матрица; ARCHITECTURE.html — полный отчёт «всё в одном».--interactive): на каждой оси AskUserQuestion [Беру рекомендацию] / [Variant B] / [Variant C] / [Отложить]..specs/{slug}/ARCHITECTURE/AXIS-NN-{id}.md|.html|.model.json + INDEX.md|.html + COMPLETENESS.md + SYNTHESIS.md|.html + ARCHITECTURE.html (full-report)./architecture-decisions/{slug}/ (incl. COMPLETENESS.md, SYNTHESIS.md, ARCHITECTURE.html)AXIS-*.model.json — persisted AxisModel (источник для full-report re-render; не для глаз)package.json/*.csproj/pyproject.toml/Cargo.toml/go.mod) — brownfield..claude/rules/specs-workflow/architecture-decision/when-to-build-architecture.md.[skip-architecture-axis: <reason ≥12 chars>] в PRD/axis frontmatter — пропустить ось. Логируется в .claude/logs/spec-architecture-escapes.jsonl. reason <12 chars → WARNING_REASON_TOO_SHORT. См. .claude/rules/specs-workflow/architecture-decision/escape-hatch-audit.md.
evals/ — deterministic eval-runner (tools/eval-runner-adb.py, host, no Docker) + qualitative rubric R1-R20 (evals/rubric.json; R1-R9 per-axis decision quality, R10-R12 per-variant design discipline, R13-R20 system-completeness layer). Golden bench evals/artifact-bench/scenario-bhph/. Прогон: python tools/eval-runner-adb.py. Completeness gate (R13-R20) enforced deterministically via audit-completeness COMPLETENESS_COVERAGE (FR-12, отдельная команда), tested via eval-7/8 (eval-runner-adb.py).
| Command | Returns |
|---|---|
| detect-axes | {axes_detected, axes[], skipped_reason?} |
| generate-axis | {axis_id, mdPath, htmlPath, wordsPerVariant[], wordBudgetOk} |
| open-browser | {launched, fallback?} |
| compile-index | {axes_total, axes_pending, rows[]} |
| audit | {findings[]} (ARCHITECTURE_COVERAGE) |
| audit-completeness | {findings[]} (COMPLETENESS_COVERAGE, FR-12) |
| synthesis | {synthesisMd, insights_count, rejected[]} (FR-13 cross-axis) |
| full-report | {reportPath, axes_count, insights_count, completeness_count} (FR-19 ARCHITECTURE.html) |
| record-verify | {recorded} (FR-20 back a real context7 verification) |
| audit-markers | {findings[]} (FR-20 UNBACKED_VERIFIED_MARKER) |
.specs/architecture-decision-builder/.claude/skills/variant-matrix-build/SKILL.md.claude/rules/specs-workflow/architecture-decision/when-to-build-architecture.md.claude/rules/specs-workflow/architecture-decision/escape-hatch-audit.md.claude/skills/create-spec/references/phase1.75_architecture-decisions.mdnpx claudepluginhub stgmt/dev-pomogator --plugin dev-pomogatorGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.