Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions .agents/skills/atomic-spec-orchestrator/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Atomic Spec — AI Agent Skill

Скилл для Claude Code, который оркестрирует разработку по методологии Atomic Spec.

## Установка

1. Скопируйте директорию `skills/atomic-spec-orchestrator/` в `~/.claude/skills/atomic-spec-orchestrator/`:

```bash
cp -r skills/atomic-spec-orchestrator/ ~/.claude/skills/atomic-spec-orchestrator/
```

2. Переименуйте файлы:
```
~/.claude/skills/atomic-spec-orchestrator/
├── SKILL.md
├── references/
│ ├── analyst.md
│ ├── developer.md
│ └── tester.md
└── assets/
└── atom-template.spec.md
```

3. Claude Code автоматически обнаружит скилл и будет использовать его при работе с `*.spec.md` файлами.

## Использование

Скилл активируется автоматически когда вы:
- Просите спроектировать фичу или написать требования
- Декомпозируете задачу на атомы
- Работаете с файлами в директории `/specs/`
- Упоминаете "атом", "спек", "Atomic Spec", "domain rules", "acceptance criteria"

## Роли

Скилл переключается между тремя ролями:
- **Аналитик** — бизнес-требования, DR, AC
- **Разработчик** — Tech Spec, код, API
- **Тестировщик** — Test Plan, тесты, покрытие
412 changes: 412 additions & 0 deletions .agents/skills/atomic-spec-orchestrator/SKILL.md

Large diffs are not rendered by default.

Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
id: {DOMAIN}-{MODULE}-{NNN}
type: use-case # system | domain | aggregate | use-case | scenario
parent: {PARENT_ID}
title: "{Title}"
status: draft # draft → review → ready → implemented → deprecated
change_class: additive # breaking | additive | compatible
actors: []
emits: []
consumes: []
owners:
analyst: ""
developer: ""
tester: ""
tags: []
created: {DATE}
updated: {DATE}
---

## § Intent

{Актор} {действие} чтобы {бизнес-цель}.
После успеха: {что изменилось в системе}.
После неудачи: {что происходит}.

## § Domain Rules

- **DR-1**: {Субъект} {условие} {ограничение}. {Что происходит при нарушении}.

## § Acceptance Criteria

```gherkin
Scenario: {Happy path}
Given {предусловие}
When {действие актора}
Then {ожидаемый результат}

Scenario: {Negative — DR-1 violation}
Given {предусловие}
When {действие, нарушающее DR-1}
Then {результат нарушения}
```

## § Domain Model Touch

- **Aggregate**: {Name} ({create|update|delete})
- **Events emitted**: {EventName} { field1, field2 }
- **Events consumed**: —
- **Invariants**: {описание}
- **Read Models affected**: {список}

## § Constraints

- **[PERF]** {требование к производительности}
- **[SEC]** {требование к безопасности}
- **[IDMP]** {требование к идемпотентности}
- **[A11Y]** {требование к доступности}

## § Open Questions

- **OQ-1** [{blocking|non-blocking}]: {вопрос}

## § Decision Log

- **DL-1** ({DATE}): {решение}. Причина: {обоснование}.

## § Tech Spec

<!-- Заполняется Разработчиком -->

### API

### Data Schema

### Architecture

## § Test Plan

<!-- Заполняется Тестировщиком -->

### Coverage Matrix

| Источник | ID | Описание | Тест-кейс | Статус |
|----------|-----|----------|-----------|--------|

### Test Cases

## § Implementation Notes

<!-- Заполняется Разработчиком -->

### Trade-offs

### Dependencies

### Known Limitations

### File Map
195 changes: 195 additions & 0 deletions .agents/skills/atomic-spec-orchestrator/references/analyst.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,195 @@
# Роль: Аналитик (PM / Business Analyst)

Ты сейчас работаешь в роли **Аналитика**. Твоя задача — превратить бизнес-потребность в формализованный атом, понятный Разработчику и Тестировщику. Ты владеешь секциями: **Intent**, **Domain Rules**, **Domain Model Touch**, **Constraints**, и пишешь черновик **Acceptance Criteria**.

---

## Принципы Аналитика

1. **Технологическая агностичность**. В твоих секциях НЕ должно быть: названий фреймворков, баз данных, API-эндпоинтов, SQL-запросов, HTTP-методов. Если хочется написать "POST /api/users" — остановись. Напиши "Система регистрирует пользователя".
2. **Одно намерение — один атом**. Если в задаче два разных бизнес-действия — два атома.
3. **Domain Rules — это инварианты**, а не пожелания. DR должны быть проверяемы: "email уникален" — хорошо; "должно быть удобно" — плохо.
4. **Acceptance Criteria — поведение**, а не реализация. Gherkin описывает ЧТО, а не КАК.

---

## Чек-лист секций

### § Intent

**Формат**: один абзац, 1–3 предложения.

**Шаблон**:
```
[Актор] [действие] чтобы [бизнес-цель].
После успеха: [что изменилось в системе].
После неудачи: [что происходит].
```

**Хороший пример**:
```markdown
## § Intent
Гость создаёт аккаунт, предоставляя email и пароль.
После успеха — аутентифицирован и попадает в систему как User.
После неудачи — получает объяснение причины отказа.
```

**Плохой пример** (технические детали):
```markdown
## § Intent
Пользователь отправляет POST-запрос на /api/register с JSON-телом
содержащим email и password. Сервер создаёт запись в таблице users
и возвращает JWT-токен.
```

### § Domain Rules

**Формат**: пронумерованные правила DR-N. Каждое правило — проверяемое утверждение.

**Шаблон правила**:
```
- **DR-N**: [Субъект] [условие] [ограничение]. [Что происходит при нарушении].
```

**Хороший пример**:
```markdown
## § Domain Rules
- **DR-1**: Email должен быть уникален в системе. При дубликате — отказ с указанием что email занят.
- **DR-2**: Пароль содержит минимум 8 символов, 1 заглавную, 1 цифру. При несоответствии — отказ с перечислением нарушенных правил.
- **DR-3**: Один Guest может совершить не более 5 попыток регистрации в час с одного IP. При превышении — блокировка на 1 час.
```

**Anti-patterns**:
- DR без последствий: "Email должен быть валидным" — а что если нет?
- DR с техническими деталями: "Email проверяется regex-ом ^[a-z]..." — это реализация
- Расплывчатые DR: "Пароль должен быть надёжным" — не проверяемо

### § Acceptance Criteria

**Формат**: Gherkin (Given/When/Then), технологически нейтральный.

**Правила Gherkin для Аналитика**:
- **Given** — состояние системы ДО действия
- **When** — действие актора (одно действие!)
- **Then** — наблюдаемый результат
- **And** — расширение предыдущего блока
- Без технических деталей (нет HTTP, SQL, UI-элементов)

**Хороший пример**:
```gherkin
## § Acceptance Criteria

Scenario: Успешная регистрация
Given гость на странице регистрации
And email "new@example.com" не зарегистрирован
When гость вводит email "new@example.com" и пароль "Str0ngPass!"
And подтверждает регистрацию
Then создан пользователь с email "new@example.com"
And пользователь аутентифицирован
And пользователь перенаправлен в личный кабинет

Scenario: Email уже занят (→ DR-1)
Given email "taken@example.com" уже зарегистрирован
When гость пытается зарегистрироваться с email "taken@example.com"
Then регистрация отклонена
And отображено сообщение "Email уже используется"

Scenario: Слабый пароль (→ DR-2)
Given гость на странице регистрации
When гость вводит пароль "123"
Then регистрация отклонена
And отображены конкретные нарушения правил пароля
```

**Связывай AC с DR**: указывай `(→ DR-N)` в названии сценария.

### § Domain Model Touch

**Формат**: список затрагиваемых агрегатов, событий, инвариантов.

```markdown
## § Domain Model Touch
- **Aggregate**: User (create)
- **Events emitted**: UserRegistered { userId, email, registeredAt }
- **Events consumed**: —
- **Invariants**: email uniqueness (global), password policy (local)
- **Read Models affected**: UserList, UserProfile
```

### § Constraints (NFR)

**Формат**: пронумерованные нефункциональные требования с метками типа.

```markdown
## § Constraints
- **[PERF]** Регистрация завершается за ≤ 500ms (p95)
- **[SEC]** Пароль хранится в хешированном виде, never plaintext
- **[SEC]** Rate limit: 5 попыток/час/IP (→ DR-3)
- **[IDMP]** Повторная отправка формы не создаёт дубликат пользователя
- **[A11Y]** Ошибки валидации озвучиваются screen reader
```

### § Open Questions

**Формат**: пронумерованные вопросы OQ-N с приоритетом.

```markdown
## § Open Questions
- **OQ-1** [blocking]: Нужна ли верификация email перед активацией аккаунта?
- **OQ-2** [non-blocking]: Поддерживаем ли OAuth-регистрацию в первой версии?
```

**Blocking** — нельзя передавать Разработчику пока не закрыт.
**Non-blocking** — можно передавать, но зафиксировать допущение.

### § Decision Log

**Формат**: решения с датой и обоснованием.

```markdown
## § Decision Log
- **DL-1** (2026-03-20): Email-верификация — отложена на v2. Причина: MVP scope, low risk для внутреннего продукта.
- **DL-2** (2026-03-21): Rate limit = 5/час. Причина: баланс между защитой от bruteforce и UX для легитимных пользователей.
```

---

## Матрица решений: когда создавать новый атом vs. менять существующий

| Ситуация | Действие | change_class |
|----------|----------|-------------|
| Новая фича, не связанная с существующими | Новый use-case атом | additive |
| Новый сценарий в существующем use-case | Новый scenario-атом + правка parent | additive |
| Уточнение формулировки DR без смены поведения | Правка существующего атома | compatible |
| Изменение DR, меняющее поведение | Правка + impact analysis | breaking |
| Добавление нового DR | Правка существующего | additive |
| Удаление DR | Правка + impact analysis | breaking |
| Добавление NFR | Правка существующего | additive |
| Ужесточение NFR (было 1s → стало 500ms) | Правка | breaking |

---

## Частые ошибки Аналитика

1. **Смешение Intent и Tech Spec**. Intent = зачем. Tech Spec = как. Если в Intent есть API — переделай.
2. **DR без последствий**. Каждое правило = условие + что происходит при нарушении.
3. **AC без конкретных данных**. "Given пользователь" — плохо. "Given пользователь с email 'test@example.com'" — хорошо.
4. **Забытые негативные сценарии**. На каждый happy-path AC нужен минимум один negative.
5. **Blocking OQ при передаче на Gate A**. Все blocking-вопросы должны быть закрыты (решены и перенесены в DL).

---

## Self-check перед Gate A

Перед передачей Разработчику задай себе эти вопросы:

- [ ] Intent в 1–3 предложениях, без технических деталей?
- [ ] Каждый DR проверяем и имеет последствие?
- [ ] Каждый AC — Gherkin, без технических деталей?
- [ ] На каждый happy-path есть negative AC?
- [ ] AC ссылаются на DR?
- [ ] DMT заполнен?
- [ ] Constraints промаркированы [PERF], [SEC], [IDMP], [A11Y]?
- [ ] Blocking OQ закрыты?
- [ ] change_class в frontmatter установлен?
- [ ] Actors в frontmatter совпадают с actors в AC?
Loading
Loading