braindump-to-canon

🚀 Стадия 1 в pipeline canon-dev: сырая идея → формальные каноны

Когда использовать

• Пользователь описывает продукт свободным текстом или голосом
• Есть фрагменты идей в чатах, заметках, презентации, но нет связной документации
• Нужно начать новый продукт «по правилам» с самого начала
• Существующий продукт нужно ретроактивно задокументировать (legacy → canon)
• Один новый модуль для существующего продукта — нужны канон и ТЗ

Когда НЕ использовать

• Каноны уже написаны и нужна доработка → canon-review
• Каноны готовы, нужен план реализации → canon-roadmap
• Нужна именно дизайн-система → design-canon (но делается после этого скилла, продуктовые каноны определяют дизайн-границы)

Философия скилла

Этот скилл — структурированное архитектурное интервью. Не «угадай что хотел пользователь», а «задай правильные вопросы, заставляющие пользователя сформулировать решения, которые он откладывал».

Большинство продуктовых решений у заказчика — в виде «ну это очевидно» или «потом разберёмся». Скилл их вытаскивает наружу через целенаправленные вопросы и фиксирует в каноне.

Принцип: никакого guessing. Если ответ неизвестен — спросить. Если пользователь говорит «не знаю» — предложить 2-3 варианта с trade-off'ами, попросить выбрать. Если выбор реально невозможен сейчас — пометить как «открытый вопрос» в каноне с условиями для решения.

Структура процесса

┌──────────────────────────────────────────────────────────────────┐
│  Phase 1 — Discovery (загрузить и понять braindump)              │
└──────────────────────────────────────────────────────────────────┘
                                ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 2 — Scope clarification (15-30 вопросов в 3-5 раундах)    │
└──────────────────────────────────────────────────────────────────┘
                                ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 3 — Module decomposition (выявить модули продукта)        │
└──────────────────────────────────────────────────────────────────┘
                                ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 4 — Stack decision (предложить + утвердить стек)          │
└──────────────────────────────────────────────────────────────────┘
                                ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 5 — Cross-cutting canons (главный канон + системный)      │
└──────────────────────────────────────────────────────────────────┘
                                ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 6 — Per-module canons (один канон на модуль)              │
└──────────────────────────────────────────────────────────────────┘
                                ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 7 — Per-module ТЗ (детализация полей, API, lifecycle)     │
└──────────────────────────────────────────────────────────────────┘
                                ↓
┌──────────────────────────────────────────────────────────────────┐
│  Phase 8 — Hand-off to canon-review (или прямо в canon-roadmap)  │
└──────────────────────────────────────────────────────────────────┘

Не все фазы должны проходить в одной сессии. Это длинный процесс — для среднего продукта 5-8 рабочих сессий по 1-2 часа.

Phase 1 — Discovery

Загрузи всё что есть от пользователя. Это может быть:

• Текст braindump'а
• Транскрипция голосового сообщения
• Презентация / pitch deck
• Существующая документация (даже фрагменты)
• Скриншоты конкурентов
• Письма / переписка

Прочитай всё. Не сокращай. Не обобщай прежде чем понять.

После прочтения — выпиши первичную сводку в формате:

## Что я понял про продукт

Назначение: [одно предложение]
Аудитория: [одно предложение]
Главный value-prop: [одно предложение]
Известные модули: [список]
Известные ограничения: [список — техника, бюджет, дедлайны]
Известные неопределённости: [список — что пользователь явно сказал «пока не знаю»]

Покажи сводку пользователю. Спроси: «Это правильное понимание? Что упущено или искажено?». Корректируй, прежде чем двигаться дальше.

Phase 2 — Scope clarification

Задавай вопросы в раундах по 5-7 штук. Не вали 30 вопросов одновременно — пользователь устанет и ответит халтурно. Раунды:

Раунд 1: Назначение и границы

• Какую главную задачу пользователя решает продукт? (не функционально — а в его жизни)
• Кто конкретно пользователь? Роль, размер компании, типичный день
• Что НЕ делает этот продукт? Чем мы готовы пожертвовать ради фокуса
• Чем мы отличаемся от существующих решений? В одном предложении
• Какой первый сценарий который должен идеально работать?

Раунд 2: Доменные сущности

• Какие главные «вещи» в системе? (e.g. для финансов: операция, счёт, контрагент)
• Между ними какие связи? (1-к-1, 1-к-многим, многие-ко-многим)
• Что является «источником истины» для каждой сущности?
• Какие сущности — read-only производные (не источник, а отчёт/представление)?

Раунд 3: Lifecycle и состояния

• У каких сущностей есть состояния (статусы)? Перечисли.
• Какие переходы разрешены? Какие запрещены?
• Что происходит когда пользователь пытается сделать запрещённый переход?
• Есть ли «закрытие периода» / «архивирование» / «soft-delete»?

Раунд 4: Multi-tenancy и масштаб

• Один пользователь — одна компания? Или может быть несколько?
• Может ли пользователь принадлежать нескольким компаниям?
• Кто видит чьи данные? Уровни доступа?
• Сколько компаний / пользователей / записей ожидается через год? Через три?

Раунд 5: Внешние интеграции

• С какими внешними системами интегрируемся? (банки, гос-сервисы, CRM, бухгалтерия)
• Это блокирующая зависимость или nice-to-have?
• Что делаем когда внешняя система недоступна?
• Есть ли регуляторные требования? (ФЗ-152, GDPR, SOC2, отраслевые стандарты)

Раунд 6: Денежная логика (если применимо)

• Где деньги в системе? Хранение, движение, отчётность
• Валюты — одна или несколько?
• Как храним суммы — копейки/центы как integer?
• Есть ли обязательная двойная запись (бухгалтерская)?
• Как обрабатываем округление?

Раунд 7: Аудит и безопасность

• Какие действия должны логироваться обязательно?
• Кто может видеть журнал аудита?
• Есть ли «критические действия» которые требуют двух факторов / подтверждения второго пользователя?
• Как храним персональные данные?

Раунд 8: Out-of-scope и анти-паттерны

• Что точно не делает наш продукт?
• Какие фичи, которые в схожих продуктах есть, мы сознательно не делаем?
• Какие архитектурные подходы мы отвергаем?

Phase 3 — Module decomposition

После раундов вопросов — формализуй карту модулей.

Рабочее определение модуля: относительно изолированный функциональный домен с собственными сущностями, lifecycle'ом и API. Если границы между двумя областями расплывчатые — обсуди это явно с пользователем, не разделяй сам.

Покажи карту в виде:

## Карта модулей

01-Система           ← сквозной системный слой (auth, settings, audit, rules)
02-{Доменный модуль} ← основной функционал
03-{Другой модуль}
04-{...}
0N-Аналитика         ← обзорный слой над всеми модулями (обычно последний)

Для каждого:

• Главные сущности
• Зависимости от других модулей
• Является ли источником истины для каких-то данных или агрегатором

Утверди карту с пользователем. Изменения в карте дешёвы сейчас, дороги после канонов.

Phase 4 — Stack decision

Это критичный момент. Стек определяет много решений в канонах (например, доступные DB-features влияют на формулировки антидублей).

Задача — предложить стек с обоснованием, дать пользователю выбор, зафиксировать решение.

Шаблон stack-decision

# Stack Decision

## Front
**Предложение:** Next.js 16 (App Router, RSC) + React 19 + TypeScript strict + Tailwind 4 + shadcn/ui
**Почему:** SSR-friendly для SEO/perf, RSC даёт чёткую границу client/server, типобезопасность критична для денежной логики.
**Альтернативы рассмотрены:**
- Remix: похож, но shadcn-ecosystem чуть меньше развит
- SvelteKit: меньше exposure у среднего разработчика, hiring-риск
- Vue/Nuxt: TypeScript-DX слабее

## Back / API
**Предложение:** Next.js Route Handlers + BetterAuth + Zod
**Почему:** монорепо, один TypeScript-стек, BetterAuth даёт organization-плагин из коробки, Zod валидирует и API, и формы

## DB
**Предложение:** PostgreSQL 18 + Drizzle ORM
**Почему:** PG — надёжен, поддержка JSON / partial indexes / advisory locks (нужны для антидублей), Drizzle даёт честные миграции и type-safe queries
**Альтернативы:**
- Prisma: больше абстракции, но N+1 ловушки чаще
- Supabase: vendor-lock, не нужен для self-hosted

## Платежи / деньги (если применимо)
**Предложение:** [контекст-зависимо]

## ИИ / LLM (если применимо)
**Предложение:** OpenRouter (provider-neutral) + OpenAI SDK (де-факто стандарт API)

## Деплой
**Предложение:** Railway (если SMB) / VPS+Docker (если контроль) / Vercel (если только Front)

## Pinned versions
[Зафиксировать конкретные major-версии чтобы они не дрейфовали при инициализации проекта]

Покажи. Жди ответ. Любые изменения — фиксируй с обоснованием в STACK.md.

Phase 5 — Cross-cutting canons

Это верхний уровень документации. Два файла:

docs/КАНОНЫ/00-Главный-канон.md

Структура (см. references/canon-template.md для полного шаблона):

# Главный канон продукта «{name}»

## 1. Что это за продукт
[Назначение — одно предложение]
[Аудитория]
[Положение на рынке: чем отличается, что НЕ делает]

## 2. Главные инварианты системы
[Список 5-12 фундаментальных правил, нарушение которых делает продукт сломанным]

Например:
- Источник истины — БД, не экран
- Деньги хранятся в копейках (integer), никогда float
- Документ не равен деньгам, оплата не равна проведению
- Аналитика читает, не пишет
- Multi-tenancy через organization_id, утечка между tenants — критический инцидент

## 3. Карта модулей и поток данных
[Диаграмма зависимостей]
[Direction of truth flow]

## 4. Сквозные правила
[Правила которые касаются всех модулей: аудит, валидация, error-handling, naming]

## 5. Что точно не делает продукт
[Анти-фичи, обоснованно out-of-scope]

docs/КАНОНЫ/Канон_Система.md

Системный слой — то что есть в любом приложении: auth, users, roles, settings, audit-log, rules-registry. Шаблон в references/canon-template.md.

Phase 6 — Per-module canons

Для каждого модуля из Phase 3 — отдельный файл Канон_{Модуль}.md. Структура — см. references/canon-template.md.

Важно: каноны модулей пишутся в одном порядке для целостности — сначала те что являются источниками истины (например, Финансы — источник для Аналитики), потом те что зависимы.

Каждый канон проходит мини-чек прежде чем считается готовым:

• Назначение в одно предложение
• 5-10 главных архитектурных правил
• Все главные сущности перечислены и разведены (не сливаются)
• Lifecycle статусов прописан полностью с переходами
• Источники истины определены явно
• Связь с другими модулями (что отдаём, что берём)
• Антидубли прописаны (если применимо)
• Out-of-scope явно
• Тест-кейсы / приёмочные критерии (5-10 пунктов)

Phase 7 — Per-module ТЗ

ТЗ детальнее канона — это спецификация для разработчика. Структура — см. references/tz-template.md.

ТЗ может писаться итеративно: версия 1 покрывает базовое, версия 2 расширяет (как ТЗ_Профиль_компании_v1 → v2 в реальном проекте). Это нормально и даже желательно — лучше выпустить v1 и начать строить, чем доводить v2 до perfection три месяца.

Phase 8 — Hand-off

После завершения — рекомендуй пользователю следующий скилл:

• Если каноны новые / без проверки → canon-review (Phase 2 проверки)
• Если каноны проверены и нужен дизайн → design-canon
• Если всё готово и нужен план → canon-roadmap

Сформулируй короткую сводку: «Готово N канонов и M ТЗ. Решений по стеку: K. Открытых вопросов: P. Следующий шаг: {скилл}».

Открытые вопросы — отдельный артефакт

В процессе фазы 2-7 будут возникать вопросы, на которые пользователь скажет «не знаю» или «решу позже». Не пропускай их. Веди файл:

docs/КАНОНЫ/OPEN-QUESTIONS.md

## Открытые вопросы

### Q1. {Тема}
- **Вопрос:** ...
- **Контекст почему важно:** ...
- **Варианты:**
  - A: ... (trade-off)
  - B: ... (trade-off)
- **Когда нужно решение:** [при каких обстоятельствах вопрос блокирует развитие]
- **Кто решает:** [пользователь / совет с экспертом / отложено до запуска]

Этот файл обязательно показать пользователю в конце сессии. Открытые вопросы убивают продукт тихо — лучше их фиксировать наглядно.

Anti-patterns (агенту)

❌ «Я понял, сейчас напишу всё сразу» — нет. Структурированное интервью обязательно. Иначе каноны будут отражать твоё понимание, не пользователя.

❌ «Пользователь не знает, я предположу разумное» — нет. Дай 2-3 варианта с trade-off'ами и зафиксируй выбор.

❌ «Сначала ТЗ, потом канон» — нет. Канон → ТЗ. ТЗ детализирует канон, не предшествует ему.

❌ «Канон — это много текста, давай покороче» — нет. Канон — это полное описание правил. Сокращённый канон не работает как источник истины.

❌ «Пользователь сказал "сделай как у Stripe"» — нет. «Как у Stripe» — это десятки конкретных решений. Уточни какие именно: API-стиль? UI? Lifecycle документов? Каждое — отдельный вопрос.

Critical principles

1. Каждое решение фиксируется текстом. «Договорились голосом» не существует.
2. Открытые вопросы — отдельный артефакт. Не молча оставлять, не догадываться.
3. Канон выше кода. Если впоследствии код противоречит — правится код, не канон.
4. Структура важнее красоты. Используй шаблоны (references/), не изобретай каждый раз.
5. Tone — calm-formal. Сравни с docs/BRAND-VOICE.md.

Templates и references

• references/canon-template.md — шаблон файла канона модуля
• references/tz-template.md — шаблон файла ТЗ модуля
• references/stack-decision-framework.md — расширенный фреймворк выбора стека
• references/clarifying-questions-bank.md — банк вопросов по доменам

Финальная заметка

Этот скилл превращает идею в фундамент. Если фундамент кривой — здание будет крениться. Не торопись. Структурированное интервью кажется медленным, но компенсирует себя десятикратно на стадии реализации, когда канон отвечает на 80% вопросов которые иначе обсуждались бы в чате.

Когда пользователь говорит «давай быстрее» — напомни: вы строите фундамент. На фундаменте экономить нельзя.