Какая информация является важной для постановки задачи разработчику?

Информация для постановки задачи разработчику

Основной принцип

Постановка задачи (task) - это контракт между аналитиком и разработчиком. Информация должна быть полной настолько, чтобы разработчик мог начать работу БЕЗ дополнительных уточнений.

1. Контекст и бизнес-цель

Почему это важно: разработчик должен понять, зачем нужна задача, чтобы принимать правильные решения при возникновении вопросов.

Что включать:

• Бизнес-проблема: что разбивается в текущей системе?
• Цель: что мы хотим достичь?
• Метрика успеха: как поймём, что решили проблему?
• Ограничения: есть ли сроки, бюджет, политические ограничения?

Пример:

❌ Плохо: «Нужно создать API для поиска вопросов»
✓ Хорошо: «Пользователи ищут вопросы по ключевым словам,
если не найдут за 3 секунды - уходят. Нужен полнотекстовый
Поиск с ранжированием по релевантности. Целевое время
ответа < 200ms для базы из 75k вопросов."

2. Функциональные требования (FR)

Что должна делать функция:

• Input: какие данные поступают?
• Processing: что нужно сделать?
• Output: какой результат вернуть?
• Edge cases: граничные случаи

Пример для поиска:

Input: query (строка 1-500 символов)
Processing:
- Поиск по title и description вопросов
- Ранжирование по релевантности
- Фильтрация по профессии (опционально)
- Сортировка по дате (свежие первыми)

Output: массив вопросов [id, title, profession, date]
Edge cases:
- Если query пусто → ошибка 400
- Если не найдено → пустой массив []
- Если >1000 результатов → paginate (limit=20)

3. Нефункциональные требования (NFR)

Что это: требования к качеству, не к функциональности

• Производительность: время ответа, throughput
• Масштабируемость: на скольких пользователей рассчитано?
• Безопасность: какие данные передаются? авторизация нужна?
• Надёжность: 99.5% uptime? что при ошибке БД?
• Maintainability: нужны ли логи? как отлаживать?

Пример:

Производительность:
- 95th percentile latency: < 200ms
- 99th percentile: < 500ms
- Throughput: 100 RPS

Безопасность:
- Аутентификация обязательна (Bearer Token)
- Логирование всех запросов в CloudWatch
- Rate limit: 100 req/min на пользователя

Надёжность:
- Retry logic: 3 попытки с exponential backoff
- Circuit breaker если Elasticsearch недоступен
- Fallback на полный scan, если поиск сломался

4. Acceptance Criteria (AC)

Это чеклист, по которому разработчик поймёт, когда задача "готова"

Формат GIVEN-WHEN-THEN (BDD):

AC#1: Базовый поиск
GIVEN пользователь авторизован
WHEN отправит query="system analyst interview"
THEN получит 20+ вопросов с этими словами в title
     и relevance score > 0.5

AC#2: Пустой поиск
GIVEN пользователь авторизован
WHEN отправит пустой query
THEN получит 400 Bad Request с сообщением
     "Query cannot be empty"

AC#3: Производительность
GIVEN база 75k вопросов
WHEN поиск по популярному слову (1000+ результатов)
THEN ответ < 200ms
     и результаты пагинированы (limit=20)

AC#4: Фильтр по профессии
GIVEN поиск="database"
  AND фильтр profession_id=26974d40...
WHEN отправит запрос
THEN получит только вопросы для System Analyst

5. API Specification (для backend задач)

Если это backend задача - дай полный контракт:

ENDPOINT: GET /api/v1/questions/search

Query Parameters:
- query: string (required, 1-500 chars)
- profession_id: UUID (optional)
- limit: int (default=20, max=100)
- offset: int (default=0)
- sort_by: enum ["relevance", "date"] (default="relevance")

Headers:
- Authorization: Bearer {token} (required)

Response 200:
{
  "total": 1523,
  "limit": 20,
  "offset": 0,
  "results": [
    {
      "id": "uuid",
      "title": "...",
      "profession": "System Analyst",
      "relevance_score": 0.95,
      "created_at": "2026-03-28T10:00:00Z"
    }
  ]
}

Response 400:
{"error": "Query cannot be empty"}

Response 401:
{"error": "Unauthorized"}

6. Database Changes (если требуется)

• Какие таблицы затрагиваются?
• Нужны ли миграции?
• Нужны ли индексы для производительности?

Пример:

Требуется:
- Индекс на questions.title (FULLTEXT для поиска)
- Индекс на questions.created_at (для сортировки)
- Индекс на questions.profession_id (для фильтра)

Миграция (Goose):
CREATE FULLTEXT INDEX idx_questions_title
ON questions (title, description);

7. Зависимости

От кого зависит эта задача?

• Другие задачи
• Внешние системы (API, БД)
• Сроки согласования

Пример:

Блокирует:
- Frontend задачу "Поиск вопросов по UI" (зависит от API)

Депендит от:
- Миграции БД для индексов (должна быть применена первой)
- Elasticsearch setup (если используем ES вместо PostgreSQL FT)

8. Тестирование

Что разработчик должен покрыть тестами:

Unit tests:
- Happy path: поиск найдёт результаты
- Empty query: вернёт 400
- No results: вернёт пустой массив
- Pagination: limit и offset работают
- Filtering: фильтр по profession_id работает

Integration tests:
- С реальной БД (PostgreSQL)
- С реальными данными (100+ вопросов)

Performance tests:
- Поиск по 1000+ результатов < 200ms
- Throughput 100 RPS

Coverage: > 90%

9. Логирование и Мониторинг

Логируй:
- Все поиски (query, results_count, latency)
- Ошибки (400, 500)
- Slow queries (> 100ms)

Мониторь:
- Search latency (p50, p95, p99)
- Error rate
- Количество "no results" запросов

10. Дополнительная информация

• Design/Mockups: если есть
• Аналоги/Вдохновение: примеры из конкурентов
• Known Issues: что может быть сложным?
• Future Work: что запланировано на будущее?

Структура задачи в Jira/Linear

Титл: Search questions by title and description

Description:
## Overview
[Бизнес-цель]

## Functional Requirements
[Input, Processing, Output, Edge cases]

## Acceptance Criteria
- [ ] AC#1: Базовый поиск
- [ ] AC#2: Пустой поиск
- [ ] AC#3: Производительность
- [ ] AC#4: Фильтр по профессии

## Technical Spec
[API контракт, БД изменения, зависимости]

## Testing
[Unit, Integration, Performance]

## Resources
[Ссылки на диаграммы, документацию]

Красные флаги (когда информация неполная)

🚩 Если разработчик спрашивает 🚩 Если есть опечатки и неточности 🚩 Если AC не покрывают edge cases 🚩 Если нет примеров в API спецификации 🚩 Если нет информации о производительности → Задача не готова к разработке

Итого

Хорошая постановка включает:

1. Контекст (ПОЧЕМУ)
2. Требования (ЧТО)
3. Спецификация (КАК)
4. Критерии принятия (КОГДА готово)
5. Тесты (ПРОВЕРКА)

Это экономит часы разработки и спасает от доработок.