diff --git a/RESEARCH-SDD-TOOLS.md b/RESEARCH-SDD-TOOLS.md new file mode 100644 index 0000000..04bc60d --- /dev/null +++ b/RESEARCH-SDD-TOOLS.md @@ -0,0 +1,230 @@ +# 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/.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/.md +├── patches/*.md +└── evolution/ + ├── current.json + └── / + ├── 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. Ссылки + +- Spec Kit manifesto: https://github.com/github/spec-kit/blob/main/spec-driven.md +- Spec Kit README: https://github.com/github/spec-kit +- AI Factory README: https://github.com/lee-to/ai-factory +- AI Factory AGENTS.md: https://github.com/lee-to/ai-factory/blob/2.x/AGENTS.md