create-spec

Prompt file imported from nikitaCodeSave/postgres-admin (.claude/commands/create-spec.md). Fill in {{arg1}} before use. Copyright stays with the author.

Помогаю создать детальную спецификацию для РЕАЛИЗОВАННОЙ фичи.

Контекст

После того как фича реализована, создаем полную спецификацию в docs/specs/ с описанием:

• Как работает фича
• Какие API endpoints реализованы
• Какие компоненты созданы
• Примеры использования
• Известные ограничения

Существующие specs

!ls -1 docs/specs/*.md 2>/dev/null | grep -E '[0-9]{3}'

Следующий номер: !ls -1 docs/specs/*.md 2>/dev/null | grep -E '[0-9]{3}' | tail -1 | grep -oE '[0-9]{3}' | awk '{printf "%03d\n", {{arg1}}+1}' || echo "001"

Последние коммиты (для контекста)

!git log --oneline -10

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

1. Определить следующий номер на основе существующих specs

2. Задать вопросы:

   • Название фичи? (короткое, описательное)
   • Какую проблему решает?
   • Как работает фича? (user flow)
   • Какие backend endpoints реализованы?
   • Какие frontend компоненты созданы?
   • Есть ли изменения в БД?
   • Примеры использования?
   • Известные ограничения?
   • Связанные commit hashes?

3. Создать файл спецификации:

   • Использовать шаблон: docs/specs/spec-template.md
   • Имя файла: docs/specs/NNN-feature-name.md где NNN = следующий номер
   • Заполнить все секции детально
   • Установить статус "Active"
   • Указать дату реализации: !date +%Y-%m-%d
   • Добавить ссылки на код (file:line)

4. Если фича была в backlog:

   • Спросить нужно ли удалить файл из docs/backlog/features/
   • Или обновить его статус на "Completed" со ссылкой на spec

Разница между Backlog Feature и Spec

Backlog Feature (планирование):

• Что ХОТИМ сделать
• Почему это нужно
• Предварительные требования
• Оценка сложности

Spec (реализовано):

• Что СДЕЛАЛИ
• Как это РАБОТАЕТ
• Детали реализации
• API reference
• Примеры использования

Структура spec

# NNN. Название Фичи

**Версия**: v0.1.0
**Дата реализации**: YYYY-MM-DD
**Автор**: [Имя]
**Status**: Active

## Краткое описание
1-2 предложения о фиче

## Проблема
Какую проблему решает

## Решение
Как работает фича

## Архитектура
### Backend
- Endpoints
- Services
- Models

### Frontend
- Components
- Hooks
- Routes

### Database
- Таблицы
- Индексы

## API Reference
Детальное описание API endpoints

## Примеры использования
Примеры кода, curl команды

## Конфигурация
Env variables, настройки

## Ограничения
Что НЕ работает, known limitations

## Известные проблемы
Ссылки на bugs

## Связанные ресурсы
- ADR: [ADR-NNNN]
- Commits: [hash]
- Related specs: [NNN]

## Changelog
- v0.1.0 (DATE): Initial implementation

Важно

• 📝 Spec пишется ПОСЛЕ реализации, не до
• 🎯 Быть детальным - это reference документация
• 💻 Включать примеры кода
• 🔗 Ссылаться на конкретные файлы и строки (file.py:123)
• ⚠️ Честно описывать ограничения
• 🔄 Связывать с ADR если есть архитектурные решения