414 lines
27 KiB
Markdown
414 lines
27 KiB
Markdown
# 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
|
||
|
||
|
||
|
||
|
||
Глубокий 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.
|
||
|
||
2. 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.
|
||
|
||
3. 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 в первой итерации.
|
||
|
||
4. 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.
|
||
|
||
5. 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).
|
||
|
||
6. 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
|
||
|
||
7. 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.
|
||
|
||
8. 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):
|
||
|
||
4. /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)
|
||
5. /grounded skill — Confidence gate: classify request (repo/doc/external), mandatory verification for changeable facts, 100/100 or INSUFFICIENT INFORMATION. Strict output format.
|
||
|
||
P2 — Средний приоритет (learning):
|
||
|
||
6. /fix + patch system — Mandatory learning artifact после каждого bug fix в patches/YYYY-MM-DD-HH.mm.md. Problem, Root Cause, Solution, Prevention, Tags.
|
||
7. /evolve skill — Cursor-based incremental processing patches → pattern extraction → skill-context overlays. Никогда не модифицирует base skills, только overlays.
|
||
|
||
P3 — Улучшения:
|
||
|
||
8. Constitution pattern — Формализовать immutable principles в отдельный файл (или секцию RULES.md) с phase gates. Сейчас RULES.md смешивает operational rules и architectural principles.
|
||
9. Task parallelization — [P] markers в task lists + execution waves (Wave 1: parallel independent, Wave 2: depends on Wave 1...).
|
||
10. 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
|
||
|
||
Каждая фаза самостоятельно ценна — можно остановиться после любой.
|
||
|