Spec Generator Skill

Overview

Skill для создания проектных спецификаций в Kiro-style формате: три связанных документа с трассировкой требований к задачам.

Когда использовать

• •Начало нового проекта — создание полной спецификации
• •Документирование существующего проекта
• •Запросы типа: "создай спеку", "напиши ТЗ", "документируй проект"

Структура

Спецификация состоит из 3 файлов в директории spec/:

project/
└── spec/
    ├── requirements.md   # ЧТО делаем
    ├── design.md         # КАК делаем
    └── tasks.md          # КОГДА делаем

Файлы

1. requirements.md

Содержит:

• •Контекст и цели проекта
• •Стейкхолдеры
• •Out of Scope (явно!)
• •Функциональные требования (REQ-XXX) в формате User Story + GIVEN-WHEN-THEN
• •Нефункциональные требования (NFR-XXX)
• •Ограничения и техстек
• •Критерии приёмки по milestones

Формат требования:

#### REQ-001: Название
**As a** <роль>
**I want** <действие>
**So that** <ценность>

**Acceptance Criteria:**
\```gherkin
GIVEN <предусловие>
WHEN <действие>
THEN <результат>
AND <дополнительный результат>
\```

**Priority:** P0 | P1 | P2 | P3
**Traces to:** [TASK-XXX], [DESIGN-XXX]

2. design.md

Содержит:

• •Архитектурные принципы
• •Высокоуровневая диаграмма (ASCII)
• •Компоненты системы (DESIGN-XXX)
• •API и интерфейсы
• •Схемы данных
• •Ключевые решения (ADR)
• •Directory structure

Формат компонента:

### DESIGN-001: Название компонента

#### Описание
...

#### Interface
\```python
class Component(ABC):
    @abstractmethod
    def method(self, param: Type) -> ReturnType:
        pass
\```

#### Конфигурация
\```yaml
component:
  option: value
\```

**Traces to:** [REQ-XXX]

3. tasks.md

Содержит:

• •Легенда приоритетов и статусов
• •Задачи (TASK-XXX) с чеклистами
• •Зависимости между задачами
• •Трассировка к требованиям
• •Dependency graph
• •Summary по milestones

Формат задачи:

### TASK-001: Название
🔴 P0 | ⬜ TODO | Est: 3d

**Description:**
Краткое описание задачи.

**Checklist:**
- [ ] Подзадача 1
- [ ] Подзадача 2
- [ ] Подзадача 3

**Traces to:** [REQ-XXX], [REQ-YYY]
**Depends on:** [TASK-ZZZ]
**Blocks:** [TASK-AAA]

Трассировка

Ключевая фича — связь между документами:

REQ-001 ──────► DESIGN-001
    │               │
    │               ▼
    └─────────► TASK-001

• •Каждое требование ссылается на design и tasks
• •Каждый design ссылается на требования
• •Каждая задача ссылается на требования и design
• •Используй формат [REQ-XXX], [DESIGN-XXX], [TASK-XXX]

Приоритеты

Статусы

Процесс создания

1. •

   Собери контекст:

   • •Какую проблему решаем?
   • •Кто пользователи?
   • •Какие ограничения?
2. •

   Начни с requirements.md:

   • •Цели и метрики успеха
   • •Out of scope (важно!)
   • •Требования в формате user stories
   • •Acceptance criteria в GIVEN-WHEN-THEN
3. •

   Затем design.md:

   • •Архитектура от требований
   • •Компоненты и интерфейсы
   • •ADR для ключевых решений
   • •Ссылки на требования
4. •

   Завершай tasks.md:

   • •Декомпозиция design на задачи
   • •Зависимости между задачами
   • •Оценки и приоритеты
   • •Milestones

Шаблоны

Шаблоны файлов находятся в templates/:

• •requirements.template.md — шаблон требований
• •design.template.md — шаблон дизайна
• •tasks.template.md — шаблон задач
• •workflow.template.md — руководство по workflow
• •task.py — CLI для управления задачами
• •executor.py — автовыполнение через Claude CLI
• •executor.config.yaml — конфигурация executor
• •Makefile.template — Make команды для проекта

Примеры

См. примеры в examples/:

• •atp-platform/ — Agent Test Platform

Task Management

Спецификация включает CLI для управления задачами:

# === Ручной режим ===
python task.py list              # Список задач
python task.py next              # Следующие задачи
python task.py start TASK-001    # Начать
python task.py done TASK-001     # Завершить

# === Автоматический режим (Claude CLI) ===
python executor.py run           # Выполнить следующую задачу
python executor.py run --all     # Выполнить все готовые
python executor.py status        # Статус
python executor.py retry TASK-001

Автоматическое выполнение:

• •Формирует промпт из spec/* для Claude
• •Запускает claude -p "<prompt>"
• •Проверяет результат (тесты, lint)
• •При неудаче — retry с лимитом
• •Защита: max_retries=3, max_consecutive_failures=2

Также создаётся Makefile с targets:

• •make exec — выполнить следующую задачу
• •make exec-all — выполнить все готовые
• •make exec-mvp — только MVP milestone

Подробнее в spec/WORKFLOW.md.

Best Practices

1. •Out of Scope обязателен — явно указывай, что НЕ входит в проект
2. •Acceptance criteria конкретны — GIVEN-WHEN-THEN, не абстракции
3. •Трассировка полная — каждое требование связано с задачами
4. •Приоритеты честные — не все P0, распределяй реалистично
5. •Оценки приблизительные — лучше диапазон (3-5d), чем точная цифра
6. •ADR для важных решений — документируй "почему", а не только "что"
7. •Dependency graph — визуализируй зависимости задач
8. •Тесты в каждой задаче — Definition of Done включает unit tests
9. •NFR на testing — требование на coverage обязательно
10. •Test tasks первыми — TASK-100 (Test Infrastructure) блокирует остальные