Skip to content

getting-started.md

Latest commit

 

History

History
194 lines (135 loc) · 7.52 KB

getting-started.md

File metadata and controls

194 lines (135 loc) · 7.52 KB

English | Русский

Быстрый старт

Это пошаговое руководство поможет вам создать ваш первый атом спецификации по методологии Atomic Spec.

Предварительные требования

Для работы с Atomic Spec вам понадобятся всего два инструмента:

  • Текстовый редактор — любой, поддерживающий Markdown (VS Code, Sublime Text, vim и т.д.)
  • Git — для версионирования атомов и прохождения пайплайна

Никаких специальных фреймворков, генераторов или CLI-утилит не требуется. Методология работает на уровне файлов и соглашений.

Шаг 1. Создание структуры каталогов

Создайте корневой каталог для спецификаций в вашем проекте:

mkdir -p specs/

Рекомендуемая структура:

specs/
  domain-a/
    SPEC-001.md
    SPEC-002.md
  domain-b/
    SPEC-010.md

Каждый домен получает свой подкаталог. Имя каталога соответствует ограниченному контексту (Bounded Context) вашей предметной области.

Шаг 2. Копирование шаблона

Скопируйте файл шаблона атома в нужный каталог:

cp templates/atom-template.md specs/domain-a/SPEC-001.md

Или создайте файл вручную со следующей структурой:

---
id: SPEC-001
type: feature
title: ""
parent: null
children: []
supersedes: null
see-also: []
emits: []
consumes: []
actors: []
tags: []
open-questions: []
status: draft
implementation: none
verification: none
owners:
  analyst: ""
  developer: ""
  tester: ""
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

## Intent

## Domain Rules

## Acceptance Criteria

## Decision Matrix (DMT)

## Constraints

## Open Questions

## Decision Log

Шаг 3. Заполнение атома как Аналитик

Роль Аналитика — первая в пайплайне. Вы заполняете следующие секции:

3.1. Frontmatter

Заполните метаданные в YAML-блоке:

  • id — уникальный идентификатор (например, SPEC-001)
  • type — тип атома (feature, rule, constraint, event, model)
  • title — краткое название на понятном бизнесу языке
  • actors — кто участвует в сценарии (например, [Покупатель, Система])
  • emits / consumes — события, которые этот атом порождает или потребляет
  • status: draft — начальный статус

3.2. Intent (Намерение)

Опишите суть атома в 1-3 предложениях. Без технических деталей. Только бизнес-смысл.

## Intent

Покупатель может отменить заказ в течение 30 минут после оформления,
если заказ ещё не передан в доставку. При отмене средства возвращаются
на исходный способ оплаты.

3.3. Domain Rules (Доменные правила)

Перечислите правила предметной области. Каждое правило имеет уникальный ID и описание последствий нарушения.

## Domain Rules

- **DR-001**: Отмена возможна только в статусе `placed` или `confirmed`.
  Нарушение: система отклоняет запрос с ошибкой `ORDER_NOT_CANCELLABLE`.
- **DR-002**: Время на отмену — 30 минут с момента `order.placed`.
  Нарушение: система отклоняет запрос с ошибкой `CANCELLATION_WINDOW_EXPIRED`.

3.4. Acceptance Criteria (Критерии приёмки)

Напишите минимум один Gherkin-сценарий. Сценарии должны быть технологически нейтральными.

## Acceptance Criteria

**AC-001**: Успешная отмена заказа
Given заказ в статусе "placed" создан 10 минут назад
When Покупатель запрашивает отмену заказа
Then заказ переходит в статус "cancelled"
And средства возвращаются на исходный способ оплаты

**AC-002**: Отмена после истечения окна
Given заказ в статусе "placed" создан 40 минут назад
When Покупатель запрашивает отмену заказа
Then система отклоняет запрос с ошибкой "CANCELLATION_WINDOW_EXPIRED"

3.5. Constraints (Ограничения)

Укажите нефункциональные требования: производительность, безопасность, идемпотентность и др.

3.6. Open Questions

Зафиксируйте открытые вопросы. Блокирующие вопросы должны быть закрыты до прохождения гейта.

Шаг 4. Прохождение Gate A

Gate A — это контрольная точка между Аналитиком и Разработчиком. Убедитесь, что:

  1. Intent заполнен (1-3 предложения, без технических деталей)
  2. Есть минимум одно доменное правило с ID и последствием нарушения
  3. Написан минимум один Gherkin-сценарий
  4. Акторы указаны в frontmatter и в AC
  5. События (emits/consumes) заполнены
  6. В Intent и Domain Rules нет технических решений
  7. Все блокирующие Open Questions закрыты
  8. Указан тип изменения (change type)
  9. На каждый happy-path есть хотя бы один негативный AC

Создайте PR с веткой spec/SPEC-001 и пройдите ревью.

Шаг 5. Фаза Разработчика (кратко)

После прохождения Gate A Разработчик:

  • Заполняет секции Tech Spec, Platform API, Implementation Notes
  • Пишет код реализации
  • Проходит Gate B

Шаг 6. Фаза Тестировщика (кратко)

После прохождения Gate B Тестировщик:

  • Заполняет секции Test Plan, Platform Tests
  • Строит Coverage Matrix (AC -> Test Case -> DR)
  • Проверяет покрытие всех AC и DR тестами
  • Проходит Gate C

После прохождения Gate C атом считается завершённым: status: active, implementation: done, verification: passed.

Что дальше