feat(feature-spec): add SDD-style Q&A skill for feature planning (#172)
* feat(feature-spec): add SDD-style Q&A skill for feature planning * docs(pr-172): add handoff, ADR-072, update project-map --------- Co-authored-by: opencode-agent <agent@opencode.local>
This commit is contained in:
Sergey
GitHub
parent
c491b5fad1
commit
43b60d6101
5 changed files with 164 additions and 0 deletions
5
.opencode/commands/feature-spec.md
Normal file
5
.opencode/commands/feature-spec.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
description: Feature spec — SDD-style Q&A before implementation
|
||||
agent: build
|
||||
---
|
||||
Load the `feature-spec` skill via `skill({name: "feature-spec"})` and follow its ПРОТОКОЛ strictly. Главный агент — оркестратор: Q&A с юзером по SDD-шаблону, план в чате, затем issue через `issue` скилл. Не создаёт issues сам — только планирует. Не запускает /run-pipeline — юзер сам.
|
||||
98
.opencode/skills/feature-spec/SKILL.md
Normal file
98
.opencode/skills/feature-spec/SKILL.md
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
---
|
||||
name: feature-spec
|
||||
description: Lightweight SDD-style Q&A skill for feature planning. Guides the agent through Spec-Driven Development questions before implementation. Produces a structured plan with 7 SDD sections (Контекст, Задача, Контракты, Инварианты, Граничные случаи, Вне scope, Критерии приемки). Also when user says "спека фичи", "feature spec", "план фичи", "обсудим фичу", "spec feature", "спецификация фичи".
|
||||
---
|
||||
|
||||
# Feature Spec
|
||||
|
||||
Лёгкий SDD-скилл: Q&A с юзером по SDD-шаблону → план в чате → issue через `issue` скилл.
|
||||
|
||||
## Когда использовать
|
||||
|
||||
| Ситуация | Инструмент |
|
||||
|----------|-----------|
|
||||
| 1 файл, очевидное поведение | Прямой чат, без формальностей |
|
||||
| 2+ компонента, бизнес-правила, diff >400 строк | `/feature-spec` |
|
||||
| Новый проект с нуля | `/spec` (9 фаз) |
|
||||
|
||||
## ПРОТОКОЛ
|
||||
|
||||
### 1. Анализ
|
||||
|
||||
Юзер описывает фичу. Агент читает SDD-шаблон (ниже) и определяет, каких данных не хватает.
|
||||
|
||||
### 2. Q&A
|
||||
|
||||
Агент задаёт вопросы списком — НЕ гадает. Пример:
|
||||
|
||||
```
|
||||
Не хватает информации по:
|
||||
1. Контракты: какой формат запроса/ответа? Какие коды ошибок?
|
||||
2. Инварианты: какие лимиты? Какой TTL? Какая модель/библиотека?
|
||||
3. Граничные случаи: что если внешний сервис недоступен? Что если данных нет?
|
||||
4. Вне scope: что точно НЕ делаем в этой итерации?
|
||||
```
|
||||
|
||||
Юзер отвечает. Если ответ неполный — агент уточняет. Q&A продолжается пока все 7 секций не заполнены.
|
||||
|
||||
### 3. План
|
||||
|
||||
Когда все данные собраны, агент выводит структурированный план:
|
||||
|
||||
```
|
||||
## Контекст
|
||||
Зачем: [мотивация]
|
||||
Контекст: [текущее состояние]
|
||||
|
||||
## Задача
|
||||
[Что делаем — архитектурный подход, пошагово]
|
||||
|
||||
## Контракты
|
||||
[API, форматы, коды ошибок]
|
||||
|
||||
## Инварианты
|
||||
[Правила без исключений: лимиты, ограничения, выбор технологий]
|
||||
|
||||
## Граничные случаи
|
||||
[Что при ошибках: невалидный вход, отказ сервиса, превышение лимита]
|
||||
|
||||
## Вне scope
|
||||
[Что НЕ делаем]
|
||||
|
||||
## Критерии приемки
|
||||
- [ ] Сценарий 1: "пользователь делает X → видит Y"
|
||||
- [ ] Сценарий 2
|
||||
```
|
||||
|
||||
### 4. Handoff
|
||||
|
||||
После готовности плана:
|
||||
- Агент: "План готов. Скажи 'создай issue' чтобы создать issue, потом запусти /run-pipeline."
|
||||
- Юзер: "создай issue" → загружается `issue` скилл → `create-issue` tool (7 секций) → issue создан
|
||||
- Юзер: `/run-pipeline` → реализация
|
||||
|
||||
## Правила
|
||||
|
||||
- **Не гадай** — если данных не хватает, задай вопрос
|
||||
- **Будь конкретным** — не "используй кеш", а "Redis с TTL 7 дней"
|
||||
- **Спека описывает ЧТО, не КАК** — контракты и решения, не алгоритмы
|
||||
- **Каждый пункт 1-3 предложения** — если больше, это две задачи
|
||||
- **Если фича простая** (1 файл, очевидное поведение) — скажи юзеру что спека не нужна
|
||||
- **Не создавай issues сам** — только планируй. Issues через `issue` скилл по команде юзера
|
||||
- **Не запускай /run-pipeline** — юзер делает это сам
|
||||
- **Не создавай файлы** — план живёт в чате, потом в issue
|
||||
- **1 issue = 1 PR** — если фича большая, предложи разбить на подзадачи
|
||||
|
||||
## SDD-шаблон (7 секций)
|
||||
|
||||
Совпадает с `create-issue` validation (PR #169):
|
||||
|
||||
| # | Секция | Что содержит |
|
||||
|---|--------|-------------|
|
||||
| 1 | `## Контекст` | Зачем (мотивация) + текущее состояние |
|
||||
| 2 | `## Задача` | Что делаем — пошагово, с путями к файлам |
|
||||
| 3 | `## Контракты` | Ожидаемое поведение: API, форматы, коды ошибок |
|
||||
| 4 | `## Инварианты` | Правила без исключений: лимиты, ограничения, технологии |
|
||||
| 5 | `## Граничные случаи` | Что при ошибках: edge cases, отказы сервисов |
|
||||
| 6 | `## Вне scope` | Что НЕ делаем в этой итерации |
|
||||
| 7 | `## Критерии приемки` | Проверяемые сценарии: "X → видит Y" |
|
||||
28
docs/decisions/072-pr-172-feature-spec-skill.md
Normal file
28
docs/decisions/072-pr-172-feature-spec-skill.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# ADR-072: Feature-spec skill — SDD-style Q&A for feature planning
|
||||
|
||||
## Статус
|
||||
|
||||
Accepted (PR #172)
|
||||
|
||||
## Контекст
|
||||
|
||||
При реализации фич через прямой чат агент часто не получает результат с первого промпта. Причины: нет зафиксированных контрактов, граничных случаев, out-of-scope. Агент угадывает решения вместо того, чтобы спросить.
|
||||
|
||||
Существующий `/spec` скилл (9 фаз, 7 файлов) — для новых проектов, слишком тяжёл для feature-level работы. После PR #169 `create-issue` tool валидирует 7 SDD-секций. Нужен лёгкий скилл, который через Q&A вырабатывает план фичи по SDD-шаблону.
|
||||
|
||||
## Решение
|
||||
|
||||
Создан `feature-spec` скилл — лёгкая SDD-дисциплина для feature-level работы:
|
||||
- Slash-команда `/feature-spec` загружает скилл
|
||||
- Скилл направляет Q&A: агент задает вопросы по 7 SDD-секциям, не гадает
|
||||
- План остаётся в чате (без файлов спеки)
|
||||
- После Q&A юзер говорит "создай issue" → issue через `issue` скилл + `create-issue` tool (7 секций)
|
||||
- Затем `/run-pipeline` реализует
|
||||
|
||||
Decision criteria: feature-spec нужен когда 2+ компонента, бизнес-правила, diff >400 строк. Не нужен для 1 файла или простых правок.
|
||||
|
||||
## Альтернативы
|
||||
|
||||
1. **Обогатить `issue` скилл SDD-секциями** — но issue скилл фокусируется на создании issues, а не на Q&A-планировании
|
||||
2. **Добавить "feature mode" в `/spec`** — усложнило бы существующий 9-фазный скилл
|
||||
3. **Два режима в create-issue (sdd flag)** — отвергнуто в пользу единого 7-секционного стандарта (PR #169)
|
||||
31
docs/handoff/pr-172-feature-spec-skill.md
Normal file
31
docs/handoff/pr-172-feature-spec-skill.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
pr: 172
|
||||
title: feat(feature-spec): add SDD-style Q&A skill for feature planning
|
||||
---
|
||||
|
||||
## Что сделано
|
||||
|
||||
- `.opencode/commands/feature-spec.md` — slash-команда `/feature-spec` (pattern как spec.md, run-pipeline.md)
|
||||
- `.opencode/skills/feature-spec/SKILL.md` — скилл с:
|
||||
- SDD-шаблон (7 секций, совпадает с create-issue validation)
|
||||
- Инструкции Q&A: агент задает вопросы списком, не гадает
|
||||
- Decision criteria: когда feature-spec нужен (2+ компонента, бизнес-правила, diff >400 строк), когда нет (1 файл — прямой чат)
|
||||
- Handoff: план в чате → юзер говорит "создай issue" → issue скилл → /run-pipeline
|
||||
|
||||
## Почему
|
||||
|
||||
При реализации фич через прямой чат агент часто не получает результат с первого промпта — нет зафиксированных контрактов, граничных случаев, out-of-scope. Feature-spec — лёгкий скилл: Q&A по SDD-шаблону → план в чате → issue через `issue` скилл → `/run-pipeline`. Не требует oracle-скрипта, файлов спеки или создания issues.
|
||||
|
||||
## Pending
|
||||
|
||||
- Обновить AGENTS.md если нужно упомянуть feature-spec в pipeline или workflow
|
||||
- Добавить feature-spec в README репозитория (если применимо)
|
||||
- Мониторить использование: действительно ли Q&A улучшает результаты с первого промпта
|
||||
|
||||
## Watch out
|
||||
|
||||
- Feature-spec НЕ создаёт issues — только планирует. Юзер должен сказать "создай issue"
|
||||
- Feature-spec НЕ запускает /run-pipeline — юзер делает это сам
|
||||
- SDD-шаблон должен совпадать с 7 секциями create-issue validation (PR #169)
|
||||
- Если фича простая (1 файл) — агент должен сказать что спека не нужна
|
||||
- Нет oracle-скрипта — это Q&A, не детерминистичный процесс как /spec
|
||||
|
|
@ -21,6 +21,7 @@ opencode-config/
|
|||
│ │ └── reviewer.md # Code review subagent (verdict via `post-review` tool: APPROVE|REQUEST_CHANGES|NEEDS_DISCUSSION) — PR#46, PR#69
|
||||
│ ├── commands/
|
||||
│ │ ├── configure-opencode.md # /configure-opencode — edit opencode.json
|
||||
│ │ ├── feature-spec.md # /feature-spec — SDD-style Q&A for feature planning (loads feature-spec skill) — PR#172
|
||||
│ │ ├── repo-readme.md # /repo-readme — standardized README generation (frontmatter agent: build, loads repo-readme skill) — PR#158
|
||||
│ │ ├── run-pipeline.md # /run-pipeline — 7-phase PR pipeline
|
||||
│ │ └── spec.md # /spec — 9-phase spec generation
|
||||
|
|
@ -30,6 +31,7 @@ opencode-config/
|
|||
│ │ ├── branch/SKILL.md # Branch naming conventions
|
||||
│ │ ├── code-standards/SKILL.md # Universal code style rules
|
||||
│ │ ├── configure-opencode/SKILL.md # Canonical rule: write to .opencode/
|
||||
│ │ ├── feature-spec/SKILL.md # SDD-style Q&A for feature planning (7 SDD sections, decision criteria, handoff to issue skill) — PR#172
|
||||
│ │ ├── get-project-map/SKILL.md # Maintain docs/project-map/
|
||||
│ │ ├── issue/SKILL.md # GitHub issue creation (7 SDD sections template) — PR#169
|
||||
│ │ ├── memory/SKILL.md # opencode-memory usage guide
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue