olek/AI_template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
AI_template/RESEARCH-SDD-TOOLS.md
olekhondera a9e5cfbdaf fix: use absolute path for sonar-scanner
2026-03-28 13:46:40 +02:00

27 KiB
Raw Permalink Blame History

Research: Spec-Driven Development Tools

Date: 2026-02-22

1. Spec Kit (GitHub)

Repo: https://github.com/github/spec-kit Stars: 71K+ | Language: Python | License: MIT

Суть

Официальный тулкит от GitHub для Specification-Driven Development (SDD). CLI-утилита specify, которая инициализирует проект с набором шаблонов и slash-команд для AI-агентов.

Ключевая идея — инверсия власти: спецификация является первичным артефактом, код — её производная. Поддерживать софт = развивать спецификации. Дебажить = чинить спецификации.

Воркфлоу

/speckit.constitution  →  архитектурные принципы (иммутабельные)
/speckit.specify       →  спецификация фичи (user stories, acceptance criteria)
/speckit.plan          →  техплан (research, data models, API contracts)
/speckit.tasks         →  executable task list с маркерами параллелизации [P]
/speckit.implement     →  выполнение тасков по плану

Структура файлов на выходе:

specs/[###-feature]/
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── tasks.md

Ключевые концепции

Constitution — "конституция" проекта с иммутабельными принципами:

  • Library-First: каждая фича начинается как standalone библиотека
  • CLI Interface Mandate: всё доступно через текстовый I/O
  • Test-First Imperative: тесты до кода (NON-NEGOTIABLE)
  • Simplicity Gate: максимум 3 проекта, без future-proofing
  • Anti-Abstraction Gate: используй фреймворк напрямую, без обёрток
  • Integration-First Testing: реальные БД вместо моков

Шаблоны как constraint для LLM:

  • Разделение WHAT/WHY vs HOW (спецификация не содержит деталей реализации)
  • Обязательные [NEEDS CLARIFICATION] маркеры вместо угадывания
  • Чеклисты как "юнит-тесты" для качества спецификации
  • Phase gates (pre-implementation): simplicity, anti-abstraction, integration-first
  • Иерархия деталей: основной документ — высокоуровневый, детали в отдельных файлах
  • Test-first ordering: контракты → тесты → код

Поддержка агентов: Claude Code, Cursor, Copilot, Gemini CLI, Codex, Windsurf, Roo Code, Kilo Code, Amp, Qoder, Jules, IBM Bob, SHAI, Auggie, Antigravity, generic (bring-your-own)

Сильные стороны

  • Жёсткая структура "сверху вниз" (spec → plan → tasks → code)
  • Traceability: каждое техническое решение привязано к конкретному требованию
  • Constitution обеспечивает архитектурную консистентность между генерациями
  • Шаблоны превращают LLM из "креативного писателя" в "дисциплинированного инженера"
  • Branching для exploration: разные имплементации из одной спецификации

Слабые стороны / ограничения

  • Нет итеративных петель с quality gates (всё линейно: specify → plan → tasks → implement)
  • Нет механизма самоулучшения скиллов на основе прошлых ошибок
  • Нет anti-hallucination gate (grounded mode)
  • Constitution — ручная настройка, нет auto-detection стека

2. AI Factory (lee-to)

Repo: https://github.com/lee-to/ai-factory Stars: 273 | Language: TypeScript | License: MIT

Суть

CLI-утилита + система скиллов для автоматизации AI-powered разработки. Одна команда ai-factory init детектит стек, устанавливает релевантные скиллы, конфигурирует MCP-серверы.

Воркфлоу

ai-factory init          →  детект стека, установка скиллов, конфигурация MCP
/aif                     →  главная точка входа (3 режима: existing/new/empty project)
/aif-plan [fast|full]    →  планирование (PLAN.md или plans/<branch>.md)
/aif-implement           →  выполнение плана
/aif-verify              →  верификация против плана
/aif-commit              →  conventional commits
/aif-review              →  code review
/aif-loop                →  итеративный reflex loop с quality gates
/aif-evolve              →  самоулучшение скиллов
/aif-grounded            →  reliability gate (anti-hallucination)

Структура файлов:

.ai-factory/
├── DESCRIPTION.md
├── ARCHITECTURE.md
├── RULES.md
├── PLAN.md
├── plans/<branch>.md
├── patches/*.md
└── evolution/
    ├── current.json
    └── <alias>/
        ├── run.json
        ├── history.jsonl
        └── artifact.md

Ключевые концепции

22 скилла (все с aif- префиксом) — от планирования до деплоя:

  • Core workflow: aif, aif-plan, aif-implement, aif-verify, aif-commit
  • Quality: aif-review, aif-security-checklist, aif-grounded
  • Iteration: aif-loop, aif-evolve, aif-improve
  • Infrastructure: aif-ci, aif-deploy, aif-dockerize, aif-build-automation
  • Meta: aif-skill-generator, aif-rules, aif-roadmap, aif-docs, aif-architecture

aif-loop (Reflex Loop) — итеративный цикл с quality gates:

PLAN → PRODUCE||PREPARE → EVALUATE → CRITIQUE → REFINE
  • Параллельное выполнение через Task-агенты
  • Двухфазная оценка (A/B с разными порогами: 0.8 и 0.9)
  • Stagnation detection (delta < 0.02 два раза подряд → стоп)
  • Persist на диск (run.json + history.jsonl) — можно resume после /clear
  • Stop conditions: threshold_reached, no_major_issues, iteration_limit, user_stop, stagnation

aif-evolve (Self-Improvement) — анализирует прошлые патчи/фиксы, находит паттерны ошибок и усиливает скиллы:

  • Собирает "intelligence" из patches, codebase conventions, linter configs
  • Группирует по категориям (null-check, async, N+1, etc.)
  • Генерирует project-specific улучшения для каждого скилла
  • Всё traceable: каждое улучшение привязано к конкретному патчу/паттерну
  • Требует подтверждения пользователя перед применением

aif-grounded (Reliability Gate) — anti-hallucination:

  • Классификация запроса: repo-grounded / doc-grounded / external-facts
  • Mandatory verification для изменяемых фактов (версии, "latest", цены)
  • Confidence gate 0-100: ответ только при 100/100
  • При < 100 выдаёт "INSUFFICIENT INFORMATION" + список чего не хватает

Transformer-система — один набор скиллов адаптируется под формат каждого агента через трансформеры (src/core/transformers/)

Сильные стороны

  • Итеративные петли с quality gates и persist (aif-loop)
  • Самоулучшение на основе прошлых ошибок (aif-evolve)
  • Anti-hallucination gate (aif-grounded)
  • Auto-detection стека при init
  • Богатый набор скиллов (22 штуки) покрывающий полный цикл
  • MCP-конфигурация из коробки

Слабые стороны / ограничения

  • Нет concept "конституции" — архитектурные принципы менее формализованы
  • Нет pre-implementation gates как в spec-kit
  • Шаблоны спецификаций менее структурированы (нет forced [NEEDS CLARIFICATION])
  • Меньше community adoption (273 vs 71K звёзд)

3. Сравнительная таблица

Аспект Spec Kit (GitHub) AI Factory (lee-to)
Фокус Spec-first: спецификация → план → таски → код Skill-система: набор workflow-скиллов
Stars 71K 273
CLI Python (specify init) Node.js (ai-factory init)
Подход Структура "сверху вниз" (waterfall-like) Итеративный с feedback loops
Constitution Да, шаблон + phase gates Нет (есть RULES.md, но менее формальный)
Spec templates Да, с constraint для LLM Нет явных spec-шаблонов
[NEEDS CLARIFICATION] Да, обязательно Нет
Iterative loops Нет Да (aif-loop с 6 фазами)
Quality gates Pre-implementation gates Evaluation с scoring + thresholds
Self-improvement Нет Да (aif-evolve)
Anti-hallucination Нет Да (aif-grounded)
Auto-detect stack Нет (ручная настройка) Да
MCP support Нет Да
Agents 20+ 15
Task parallelization Маркеры [P] в tasks.md Parallel Task agents в loop

4. Идеи для адаптации

Из Spec Kit взять:

  1. Constitution pattern — формализованные архитектурные принципы с phase gates
  2. Structured spec templates с forced [NEEDS CLARIFICATION] маркерами
  3. Pre-implementation gates (simplicity, anti-abstraction, integration-first)
  4. Traceability — каждое техническое решение привязано к требованию
  5. Шаблоны-как-constraint — управление поведением LLM через структуру документа
  6. Test-first ordering — контракты → тесты → код

Из AI Factory взять:

  1. aif-loop — reflex loop с PLAN→PRODUCE→EVALUATE→CRITIQUE→REFINE
  2. aif-evolve — self-improvement скиллов на основе прошлых ошибок
  3. aif-grounded — confidence gate с explicit evidence requirements
  4. Persist на диск — run.json + history.jsonl для resume после context clear
  5. Stagnation detection — автоматический стоп если прогресс < 0.02
  6. Parallel Task agents — параллельное выполнение независимых фаз

Комбинированный подход (гипотеза):

Constitution (spec-kit)
    ↓
Specify with [NEEDS CLARIFICATION] (spec-kit templates)
    ↓
Plan with pre-implementation gates (spec-kit)
    ↓
Tasks with [P] markers (spec-kit)
    ↓
Implement via Reflex Loop (ai-factory aif-loop)
    ↓
Verify + Grounded check (ai-factory aif-grounded)
    ↓
Evolve skills based on patches (ai-factory aif-evolve)

5. Ссылки

Глубокий Research: SDD-инструменты и AI-assisted Development (март 2026)

Ландшафт: что произошло с момента твоего исследования

Твой RESEARCH-SDD-TOOLS.md от 2026-02-22 зафиксировал Spec Kit и AI Factory. За 2 недели ландшафт значительно расширился:

Spec Kit вырос до 74.6K stars, 110+ релизов, поддерживает 22+ агентов. Но получил серьёзную критику:

  • CTO Scott Logic: "sea of markdown documents, long agent run-times and unexpected friction" — spec в 4x длиннее финального кода
  • Martin Fowler/Thoughtworks: "like using a sledgehammer to crack a nut" для мелких задач
  • Главная проблема: агенты не следуют инструкциям даже при больших контекстных окнах — "Just because context windows are larger doesn't mean AI will properly pick up on everything"

AI Factory — v2.6.0 (5 марта 2026), 7 релизов за 15 дней. Очень активная разработка. Добавили extensions system, persist explore context (RESEARCH.md), docs policy checkpoint, incremental evolve, self-update.

Новые игроки, которых нет в твоём research:

┌─────────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─────────────┐ │ Инструмент │ Суть │ Статус │ ├─────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤ │ AWS Kiro │ Enterprise SDD с deep AWS интеграцией, 3 фазы (Specify→Plan→Execute), сильный brownfield support │ Production │ ├─────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤ │ Tessl Framework │ Самый амбициозный — "spec-as-source", reverse-engineers specs из кода, Spec Registry с 10K+ библиотек против hallucination API │ Closed beta │ ├─────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤ │ BMAD Method │ AI personas (Analyst, PM, Architect, Dev, QA), docs-as-code, epic sharding для context collapse │ V6 stable │ ├─────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤ │ Qodo Rules │ AI governance — auto-generates, enforces, measures coding standards как policy │ Production │ ├─────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤ │ Beads (bd CLI) │ Git-backed graph-oriented issue tracker как external memory для агентов │ Active │ ├─────────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼─────────────┤ │ Repomix │ Пакует repo в single AI-friendly файл, MCP server mode, Tree-sitter compression │ Mature │ └─────────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴─────────────┘

Ключевые паттерны индустрии (консенсус 2026)

  1. Constitution Files — универсальный стандарт

Каждый инструмент теперь имеет "конституцию":

  • Spec Kit: memory/constitution.md — 9 Articles of Development (Library-First, Test-First, Simplicity Gate...)
  • Claude Code: CLAUDE.md — "as important as .gitignore"
  • Cursor: .cursor/rules/*.mdc с glob-scoped auto-attachment
  • Windsurf: .windsurfrules + автогенерируемые Memories
  • BMAD: PRD + Architecture docs как versioned constitutional assets

У тебя: RULES.md + agents/ — это уже конституция, но без pre-implementation gates и phase gates.

  1. Deterministic Orchestration + Bounded Agents

QuantumBlack (McKinsey) — ключевой инсайт: "Agents are good at generating content within a bounded problem; they struggle with meta-level decisions about workflow sequencing." Letting agents self-orchestrate fails at scale.

Выигрывающая архитектура: Deterministic orchestration layer (pipeline, DAG) → Agents generate content within bounded problems → Two-layer quality gates:

  1. Deterministic checks (linters, tests, structural validation)
  2. Critic agent validates against definition of done

Cursor's 1M-line browser (GPT-5.2): failed с equal-status agents, succeeded с hierarchy Planners → Workers → Judges.

  1. Iterative Loops — наука за ними

Академические результаты подтверждают эффективность:

  • Reflexion (Shinn et al.): GPT-4 HumanEval 67% → 88% (+21pp) через self-reflection
  • Self-Refine (Madaan et al.): +5% to +40% improvement через FEEDBACK→REFINE loop
  • CYCLE: до 63.5% relative improvement, причём маленькая модель с refinement побеждает большую без

Критический инсайт по stopping criteria: Secure Code Reflexion показал diminishing returns — Round 1: +6.00pp, Round 2: +1.66pp, Round 3: +1.03pp. Большая часть improvement в первой итерации.

  1. Quality Gates — двухслойная модель

Индустриальный консенсус:

  1. Layer 1 (deterministic): linters, test suites, type checking, structural validation — быстро, reliable
  2. Layer 2 (critic agent): dedicated LLM validates output against definition of done — для judgment calls

LLM-as-Judge: binary (pass/fail) или 3-point scales надёжнее 10-point scales. Strong judges: 80-90% agreement с humans. Multi-dimensional weighted rubrics работают для кода.

Scoring biases: verbosity bias (длинный = лучше), self-preference bias, position bias. Mitigation: разные model families для generator и judge.

  1. Self-Improvement — работает, но дорого
  • Darwin Godel Machine (Sakana AI): SWE-bench 20% → 50% через self-modification. Но стоит ~$22K и 2 недели.
  • Roblox: PR acceptance rate 30% → 60% через structured human feedback + domain expert labeling.
  • AI Factory aif-evolve: practical approach — mandatory patches после каждого fix, cursor-based incremental processing, skill-context overlays.
  • Writer: RL from self-reflection с minimal catastrophic forgetting.

Практичный подход: не self-modification кода агента, а structured memory из прошлых ошибок (patches → pattern extraction → skill improvement).

  1. Memory/Persistence — file-based побеждает

Vercel's experiment: 8KB AGENTS.md = 100% pass rate на Next.js 16 eval suite (vs 79% для complex skills approach). Presence of AGENTS.md = 29% reduction в runtime, 17% reduction в output tokens.

Letta benchmark: plain filesystem = 74% на memory tasks, beating specialized vector stores.

Memory hierarchy (CPU cache analogy):

  • L1 (always loaded): CLAUDE.md / RULES.md — 2-10KB
  • L2 (on-demand): Skills, file references — progressive disclosure
  • L3 (session history): Conversation with compaction
  • L4 (external retrieval): RAG, codebase search
  1. Anti-Hallucination — 10-layer defence

Layered defence model (от простого к сложному):

  1. Specification grounding (spec-first)
  2. RAG-based grounding (retrieve relevant code/docs)
  3. Confidence gates (100/100 or INSUFFICIENT INFORMATION)
  4. Chain-of-thought verification with citations
  5. Deterministic post-validation (linters, tests)
  6. Critic agent validation
  7. Cross-model QA
  8. Forced uncertainty markers ([NEEDS CLARIFICATION])
  9. Request classification (repo/doc/external-grounded)
  10. Spec Registry для external APIs

Шокирующая находка: "Maximum Effective Context Window" (MECW) dramatically ниже рекламируемого. Hallucination rates at 2000+ tokens = до 99% для некоторых моделей. Less context, better structured > more context.

  1. Claude Code Ecosystem — best practices

CLAUDE.md: target 50-100 lines, structure as WHAT/WHY/HOW, prefer pointers over copies, document what Claude gets wrong. Не используй для code style — linters дешевле и быстрее.

Skills: limit to 20-30 high-quality (quality > quantity). Progressive disclosure: metadata ~100 tokens for scanning, full body <5K when triggered.

Hooks: 12 lifecycle events, deterministic (always run). Key: PreToolUse для blocking, PostToolUse для auto-format/auto-commit.

Context: start fresh sessions per task (#1 tip), manual /compact at max 50%, Claude Code uses 5.5x fewer tokens than Cursor.

Что это значит для твоего AI_template

Сильные стороны (что ты уже сделал лучше многих)

  1. RULES.md — уже функционирует как конституция, чётко и лаконично
  2. 15 skills — хорошее покрытие lifecycle, правильная progressive disclosure архитектура
  3. 5 hooks — protect-files, bash-firewall, post-edit-format, audit-log, commit-docs-reminder
  4. 7 agent profiles — covers key domains
  5. Modular archetype system — 5 archetypes + mix & match modules

Критические пробелы (приоритизированные по impact)

P0 — Высший приоритет (фундамент):

  1. /specify skill — Structured spec creation с [NEEDS CLARIFICATION] markers (max 3), separation WHAT/WHY vs HOW, checklists as "unit tests for spec quality". Output: specs/[feature]/spec.md
  2. /plan skill — Technical plan с pre-implementation gates (Simplicity Gate, Anti-Abstraction Gate, Integration-First Gate). Output: specs/[feature]/plan.md + tasks.md
  3. Two-layer quality gate в /review skill — сейчас у тебя review как code review. Нужно усилить: Layer 1 (deterministic: run linters/tests/build) + Layer 2 (critic agent against spec/plan)

P1 — Высокий приоритет (iterative quality):

  1. /loop skill — Reflex loop PRODUCE→EVALUATE→CRITIQUE→REFINE. Two-phase scoring (0.8/0.9). Stagnation detection (delta < 0.02). Persist state (run.json + history.jsonl) для resume после /clear. Max 3-5 iterations (research shows diminishing returns after round 1-2)
  2. /grounded skill — Confidence gate: classify request (repo/doc/external), mandatory verification for changeable facts, 100/100 or INSUFFICIENT INFORMATION. Strict output format.

P2 — Средний приоритет (learning):

  1. /fix + patch system — Mandatory learning artifact после каждого bug fix в patches/YYYY-MM-DD-HH.mm.md. Problem, Root Cause, Solution, Prevention, Tags.
  2. /evolve skill — Cursor-based incremental processing patches → pattern extraction → skill-context overlays. Никогда не модифицирует base skills, только overlays.

P3 — Улучшения:

  1. Constitution pattern — Формализовать immutable principles в отдельный файл (или секцию RULES.md) с phase gates. Сейчас RULES.md смешивает operational rules и architectural principles.
  2. Task parallelization — [P] markers в task lists + execution waves (Wave 1: parallel independent, Wave 2: depends on Wave 1...).
  3. CLAUDE.md generation — сейчас нет CLAUDE.md в проекте. /init-project skill должен генерировать его из RULES.md + RECOMMENDATIONS.md.

Рекомендуемый порядок реализации

Phase A: Spec-first foundation /specify → /plan → enhance /review with two-layer gates

Phase B: Iterative quality /loop → /grounded

Phase C: Learning system /fix (patches) → /evolve (skill improvement)

Phase D: Polish Constitution formalization → Task parallelization → CLAUDE.md generation

Каждая фаза самостоятельно ценна — можно остановиться после любой.

Reference in New Issue View Git Blame Copy Permalink