docs: add SDD tools research (Spec Kit + AI Factory)

Comparative analysis of GitHub's spec-kit and lee-to/ai-factory
for spec-driven development workflows and iterative AI coding.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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/<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. Ссылки
+
+- 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