Документация

Методология и рабочий процесс платформы: от боли к цепочке фреймворков, CLI и материализованной теории в .theory/.

Содержание

CLI:initlistselectmapapplystatusswitch
▸Основы

Что такое Theory

Theory of the System — это общее инженерное понимание проекта: зачем система устроена именно так, где проходят границы, какие решения нельзя ломать и почему.

Это не «ещё одна документация» и не набор диаграмм ради диаграмм. Теория — живая модель в головах команды, которую можно материализовать в артефактах и передавать дальше, когда люди меняются.

AskSerega помогает собрать первую версию теории: от конкретной боли — через цепочку фреймворков — к артефактам в .theory/.

▸Основы

Почему Питер Наур

В работе 1985 года Питер Наур показал: программирование — это не столько написание кода, сколько построение теории системы в голове разработчика. Код — лишь один из артефактов этой теории.

Когда теория утрачена (ушёл человек, команда выросла, legacy «просто работает»), код остаётся, а понимание исчезает. Менять такую систему страшно: непонятно, что сломается и почему когда-то приняли именно эти решения.

AskSerega опирается на эту идею: сначала восстановить и зафиксировать понимание, потом менять систему осознанно.

▸Основы

Почему AskSerega

Платформа состоит из трёх частей:

  • •Frameworks — инженерные модели и вопросы для построения понимания.
  • •CLI — инструмент, который проводит по цепочке и сохраняет артефакты в проекте.
  • •Docs — методология и рабочий процесс (эта страница).

Путь всегда один: Боль → Цепочка → Фреймворк → Артефакт → Теория.

▸Старт

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

Два способа начать — с сайта или из терминала.

На сайте

  1. Откройте каталог болей и выберите, что мешает сейчас.
  2. Получите цепочку фреймворков и откройте первый шаг.
  3. Скопируйте LLM-промт, примените к своему проекту, зафиксируйте результат.

В терминале

cd my-project
serega init
serega select
serega map
serega apply

После apply артефакты появятся в .theory/frameworks/.

▸Старт

Установка

Нужен Node.js 20.19+.

$ npm install -g askserega

Без глобальной установки:

$ npx askserega --help

Бинарная команда после установки — serega.

▸Старт

Настройка LLM

Команды serega init и serega apply (LLM-режим) ходят в OpenAI-compatible endpoint /v1/chat/completions: OpenAI, OpenRouter, Ollama и другие совместимые провайдеры.

Когда спрашивает

При первом запуске init или apply без сохранённого конфига CLI запускает короткий wizard и спрашивает три поля:

  • •baseURL — по умолчанию https://api.openai.com/v1
  • •apiKey — ввод маскируется
  • •model — по умолчанию gpt-4o

Куда сохраняется

Конфиг глобальный для пользователя, не в проекте:

~/.config/askserega/config.json

Файл создаётся с правами 600. Это не .theory/config.json — там только имя проекта и язык.

{
  "provider": {
    "baseURL": "https://api.openai.com/v1",
    "apiKey": "sk-…",
    "model": "gpt-4o"
  }
}

Примеры baseURL

ПровайдерbaseURL
OpenAIhttps://api.openai.com/v1
OpenRouterhttps://openrouter.ai/api/v1
Ollama (локально)http://localhost:11434/v1

Как изменить

Отдельной команды serega config пока нет. Чтобы сменить провайдера:

  • •отредактируйте ~/.config/askserega/config.json
  • •или удалите файл — при следующем init / apply wizard запустится снова

Безопасность

apiKey хранится в открытом виде (файл с правами 600). Не коммитьте этот путь и не копируйте конфиг в репозиторий проекта.

Без LLM

Офлайн работают list, select, map, switch, status и apply --no-llm. Если init упал на этапе LLM, каталог .theory/ уже создан — можно продолжить офлайн или перезапустить init.

$ serega init

Настроим LLM-провайдера (OpenAI-compatible /v1/chat/completions).
? baseURL:  https://api.openai.com/v1
? apiKey:  ********
? model:  gpt-4o

✓ Конфиг сохранён: ~/.config/askserega/config.json
⚠ apiKey хранится в открытом виде (права 600) — не коммить этот файл.
▸Инструменты

CLI

CLI — консольный компаньон каталога: нашёл боль → получил цепочку → применил шаги → прогресс лежит в .theory/. Типичный поток: init → select → map → apply → status.

init и apply (LLM-режим) требуют настроенного провайдера — см. Настройка LLM. Остальные команды работают офлайн.

serega init

Создать .theory/ и собрать контекст проекта

Создаёт каталог .theory/ (config.json + state.json), добавляет его в .gitignore, затем запускает LLM-сессию: читает package.json / README / git remote, задаёт 1–2 уточняющих вопроса и сохраняет .theory/theory.json. Повторный init обновляет теорию.

Флаги

ФлагОписание
--name <name>название проекта (иначе из package.json / папки)

Пример вывода

$ serega init

✓ .theory/ создан
✓ добавлен в .gitignore

Соберу контекст проекта…
? Чем занимается сервис?  Биллинг подписок
? Что сейчас важнее всего понять?  Границы billing

✓ theory.json сохранён
  подсказка: serega select — выбрать боль

serega list

Справочник каталога без .theory/

Печатает боли и/или фреймворки из каталога. Не требует инициализированного проекта — удобно посмотреть, что есть, до init.

Флаги

ФлагОписание
--symptomsтолько боли (поведение по умолчанию)
--frameworksтолько фреймворки
--allболи и фреймворки

Пример вывода

$ serega list

Боли · 24

Знания и их передача · 6

  Ушёл разработчик — потеряли контекст  know-004
  цель: Сохранить контекст системы независимо от конкретных людей
  цепочка (4): system-context-mapping → c4-model → adr → …

  …

$ serega list --frameworks

Фреймворки · 18

  C4 Model  c4-model · architecture · medium
    Визуализировать систему на разных уровнях абстракции

serega select

Выбрать активную боль вручную

Интерактивный выбор: категория → симптом. Выбранная боль становится activeSymptom в state.json. Требует .theory/ (сначала init).

Флаги

Без флагов.

Пример вывода

$ serega select

? Категория боли:
  ❯ Знания и их передача
    Понимание системы
    Границы и зависимости
    Сложность и изменения

? Симптом:
  ❯ Ушёл разработчик — потеряли контекст
    Новый разработчик долго погружается в проект
    …

✓ Активная боль: Ушёл разработчик — потеряли контекст (know-004)
  подсказка: serega map — посмотреть цепочку

serega map

Цепочка фреймворков активной боли

Показывает roadmap текущей боли: выполненные шаги [✓], текущий [▶], ожидающие [ ], и краткое «зачем» для каждого шага. Требует activeSymptom.

Флаги

Без флагов.

Пример вывода

$ serega map

Roadmap для: Ушёл разработчик — потеряли контекст
know-004 · 4 шага

  [✓] 1. System Context Mapping  system-context-mapping
      Зафиксировать внешний контекст системы
      применён 2026-08-01 · LLM
  [▶] 2. C4 Model  c4-model
      Разложить систему по уровням
  [ ] 3. ADR  adr
      Сохранить причины ключевых решений
  [ ] 4. …

  подсказка: serega apply c4-model

serega apply [slug]

Применить фреймворк или всю цепочку

Без slug — интерактивно проходит цепочку activeSymptom (или --symptom). Со slug — один фреймворк. По умолчанию LLM-режим пишет артефакт в .theory/frameworks/<slug>.md. --no-llm включает офлайн-workshop по algorithm[]. Без --focus CLI один раз спросит фокус (Enter — весь проект).

Флаги

ФлагОписание
[slug]slug фреймворка; без slug — режим цепочки
--prompt-onlyLLM-режим (по умолчанию)
--no-llmworkshop без LLM, документ не сохраняется
--symptom <id>боль для режима цепочки (становится активной)
--focus <text>фокус: область, путь или задача
--focus-file <path>бриф фокуса из файла (или - для stdin)

Пример вывода

$ serega apply c4-model --focus "billing в src/billing"

Фокус: billing в src/billing
Генерирую артефакт…

✓ Artifact created
  .theory/frameworks/c4-model.md

$ serega apply

Цепочка: know-004 · 4 шага

  [▶] 2/4  C4 Model
  ? Применить этот шаг?  Yes / Skip / Stop

✓ c4-model сохранён
  подсказка: serega map — прогресс

serega status

Дашборд прогресса по болям

Показывает контекст проекта из theory.json, прогресс по каждой выбранной боли (done/total), активную боль и последние применённые фреймворки.

Флаги

Без флагов.

Пример вывода

$ serega status

Теория проекта: billing-service
Подписки и счета. Монолит на NestJS…
…

Симптомы:
  2/4  Ушёл разработчик — потеряли контекст  know-004 ← активный
  0/3  Всё связано со всем  bound-001

Применённые фреймворки:
  2026-08-01  c4-model · LLM
  2026-08-01  system-context-mapping · LLM

  подсказка: serega map — текущая цепочка

serega switch [symptomId]

Переключить активную боль

Меняет activeSymptom. Прогресс всех болей сохраняется — можно возвращаться к незавершённым цепочкам. Без аргумента — интерактивный выбор.

Флаги

ФлагОписание
[symptomId]id боли, например know-004 или bound-001

Пример вывода

$ serega switch bound-001

✓ Активная боль: Всё связано со всем (bound-001)
  подсказка: serega map — посмотреть цепочку
▸Инструменты

Фреймворки

Фреймворк — инженерная модель с целью, вопросами, алгоритмом, LLM-промтом и ожидаемым артефактом. Это не статья «про архитектуру», а рабочий шаг к пониманию системы.

Каталог на сайте: /frameworks. В CLI тот же набор доступен через serega list --frameworks.

На странице фреймворка есть промт, алгоритм, примеры артефактов и место в цепочке боли (?symptom=).

▸Инструменты

Цепочки и боли

Боль (symptom) — конкретная проблема команды: «ушёл человек — потеряли контекст», «всё связано со всем», «legacy страшно трогать».

Для каждой боли задана цепочка фреймворков: порядок шагов, который ведёт от симптома к теории. Цепочка — единственный источник связей «фреймворк ↔ боль»; членство и порядок живут в каталоге болей, а не в MDX фреймворка.

В CLI: select выбирает боль, map показывает цепочку, apply проходит её по шагам.

▸Инструменты

.theory/

Каталог .theory/ — локальное состояние теории проекта. Обычно добавляется в .gitignore при init.

.theory/
├── config.json       # имя проекта, язык
├── state.json        # активная боль, прогресс шагов
├── theory.json       # контекст проекта из init
├── frameworks/       # результаты apply: <slug>.md
└── backups/          # бэкапы при повторном apply

Именно сюда складывается материализованная теория: артефакты фреймворков и контекст, который CLI подмешивает в следующие промты.

▸Практика

Примеры

Ушёл ключевой разработчик

Выберите боль про потерю контекста → пройдите цепочку (контекст системы, границы, ADR) → сохраните артефакты в .theory/. Новый человек онбордится через теорию, а не через устные легенды.

Страшно менять legacy

Начните с боли про страх изменений → dependency / impact mapping → зафиксируйте, что связано и где безопасные границы. Дальше изменения опираются на модель, а не на удачу.

Неясные границы сервисов

Боль про связанность → bounded contexts / C4 / context mapping → артефакты с явными границами ответственности. Команда получает общий язык для следующего рефакторинга.

Готовые входы: боли на главной · каталог фреймворков.