1324 lines
75 KiB
Markdown
1324 lines
75 KiB
Markdown
# Исследование мультиагентных оркестраторов и проект собственного
|
||
|
||
## Дата: 15 марта 2026
|
||
## Проект: Kin — виртуальная софтверная компания
|
||
|
||
---
|
||
|
||
## ЧАСТЬ 1: Анализ Ruflo (ex Claude Flow)
|
||
|
||
### 1.1 Общие сведения
|
||
|
||
- **Репо**: github.com/ruvnet/ruflo
|
||
- **Автор**: ruvnet (один разработчик)
|
||
- **Звёзды**: ~20K, форки: ~2.3K
|
||
- **Коммиты**: 5,800+, 55 alpha-итераций
|
||
- **Текущая версия**: v3.5.0 (февраль 2026) — первый "стабильный" релиз
|
||
- **Стек**: TypeScript/Node.js, WASM (Rust) для policy engine и embeddings
|
||
- **Пакеты**: @claude-flow/cli, claude-flow, ruflo — все три являются обёртками над @claude-flow/cli
|
||
|
||
### 1.2 Архитектура (заявленная)
|
||
|
||
```
|
||
User → Ruflo CLI/MCP → Router → Swarm → Agents → Memory → LLM Providers
|
||
↑ ↓
|
||
└──────────────── Learning Loop ←────────────────────────┘
|
||
```
|
||
|
||
**Ключевые компоненты:**
|
||
- **CLI/MCP интерфейс** — входная точка, 175+ MCP-тулов
|
||
- **Router** — маршрутизация задач к агентам, автоматический выбор модели (haiku/sonnet/opus)
|
||
- **Swarm Manager** — управление топологией (hierarchical, mesh, ring, star)
|
||
- **Agent System** — 60+ предопределённых агентов в 16 категориях
|
||
- **Memory** — SQLite (.swarm/memory.db), ReasoningBank с hash-based embeddings
|
||
- **Hive Mind** — queen/worker иерархия с "consensus" протоколами
|
||
|
||
### 1.3 Что РЕАЛЬНО работает (по issue tracker и коду)
|
||
|
||
**Механизм запуска агентов:**
|
||
- Ключевая функция: `launchClaudeCodeWithSwarm` в `src/cli/commands/swarm-new.ts`
|
||
- ЧТО ОНА ДЕЛАЕТ: формирует гигантский `swarmPrompt` (текстовую строку) и передаёт его в `claude` CLI
|
||
- ПО СУТИ: это prompt engineering — агенты "существуют" как инструкции в промпте одного Claude Code
|
||
- Файлы генерируются прямо в корень проекта (issue #398 — нет контроля output directory)
|
||
|
||
**Критический баг (issue #955):**
|
||
- `--claude` флаг в `hive-mind spawn` ДОКУМЕНТИРОВАН, но НЕ РЕАЛИЗОВАН
|
||
- Команда спавнит "worker agent" (запись в БД), но НЕ запускает Claude Code
|
||
- Флаг молча игнорируется
|
||
|
||
**Memory система:**
|
||
- SQLite-based, работает
|
||
- ReasoningBank использует hash-based embeddings (не требует API) — быстрые, но примитивные
|
||
- 2-3ms latency для поиска — это хорошо
|
||
- Persistent между сессиями
|
||
|
||
**GUI:**
|
||
- Web UI на порту 3000 (WebSocket)
|
||
- Терминальный эмулятор в браузере
|
||
- @liamhelmer/claude-flow-ui — отдельный npm-пакет для UI
|
||
|
||
### 1.4 Что МАРКЕТИНГ vs РЕАЛЬНОСТЬ
|
||
|
||
| Заявлено | Реальность |
|
||
|----------|-----------|
|
||
| 60+ специализированных агентов | Папки с CLAUDE.md промптами в .agents/skills/, по сути — шаблоны для system prompt |
|
||
| Byzantine consensus | Протокол описан, но по issue tracker - не используется в реальных сценариях |
|
||
| Neural pattern recognition | Hash-based embeddings + паттерн-матчинг, не нейросеть |
|
||
| 127 параллельных агентов (из issue #125) | Это wishlist/epic, не реализация. Реально — один claude процесс с большим промптом |
|
||
| Self-learning | Запись success/failure в SQLite + маршрутизация на основе прошлых результатов. Работает, но это не ML |
|
||
| WASM SIMD acceleration | Rust-based WASM для embeddings — реально работает, даёт скорость |
|
||
| Hive Mind | Queen = координирующий промпт, Workers = записи в БД, НЕ отдельные Claude процессы |
|
||
|
||
### 1.5 Что ВЗЯТЬ из Ruflo
|
||
|
||
**Сильные стороны (стоит перенять):**
|
||
|
||
1. **MCP-интеграция** — агент-оркестратор как MCP-сервер для Claude Code. Это позволяет Claude Code вызывать оркестратор как тулзу, а не наоборот. Элегантно.
|
||
|
||
2. **SQLite memory с namespace** — простая, надёжная, persistent. Key-value с namespace (architecture/, bugs/, decisions/) — хороший паттерн.
|
||
|
||
3. **Model routing** — автоматический выбор haiku для простых задач, opus для сложных. Экономит деньги.
|
||
|
||
4. **Anti-drift defaults** — `topology: hierarchical` + `maxAgents: 8` + `strategy: specialized`. Маленькие команды с чёткими ролями дрифтят меньше.
|
||
|
||
5. **ADR (Architecture Decision Records)** — spec-first подход, где архитектура описана в ADR-файлах и агенты обязаны следовать.
|
||
|
||
6. **Hook system** — pre-task/post-task хуки для автоматизации (pre: загрузить контекст, post: сохранить результат).
|
||
|
||
7. **Структура .agents/skills/** — каждый агент = директория с CLAUDE.md (system prompt) + tools + config. Модульно, расширяемо.
|
||
|
||
**Слабые стороны (НЕ повторять):**
|
||
|
||
1. **Fake parallelism** — агенты не являются отдельными процессами. Это один Claude Code с большим промптом, притворяющимся несколькими агентами. ГЛАВНАЯ ПРОБЛЕМА — контекст всё равно один, compaction убивает всех одновременно.
|
||
|
||
2. **Over-engineering** — 215 MCP tools, 87 в wiki, byzantine consensus — для одного разработчика это красные флаги. Много surface area, мало глубины.
|
||
|
||
3. **Размытие ответственности пакетов** — 3 npm-пакета (@claude-flow/cli, claude-flow, ruflo) — это один и тот же код. Ребрендинг создаёт путаницу.
|
||
|
||
4. **Нет реальной изоляции контекста** — это ключевое. Если агент-программист и агент-тестировщик живут в одном контексте, compaction убивает нюансы обоих.
|
||
|
||
5. **Документация как продукт** — README и Wiki описывают фичи, которые не реализованы (issue #955). Доверять нельзя.
|
||
|
||
---
|
||
|
||
## ЧАСТЬ 2: Анализ других фреймворков (ключевые выводы)
|
||
|
||
### 2.1 CrewAI (Python)
|
||
|
||
- **Модель**: Role-based crews + Event-driven Flows
|
||
- **Сильное**: Быстрое прототипирование, MCP + A2A поддержка, 44K+ GitHub stars
|
||
- **Слабое**: Ограниченный checkpointing, роли через prompt engineering (не настоящая изоляция)
|
||
- **Для нас**: Flows (event-driven оркестрация поверх crews) — хорошая концепция
|
||
|
||
### 2.2 LangGraph (Python)
|
||
|
||
- **Модель**: Directed graph с conditional edges, checkpointing
|
||
- **Сильное**: Лучшая в индустрии persistence/state, time-travel debug
|
||
- **Слабое**: Высокий порог входа, привязка к LangChain экосистеме
|
||
- **Для нас**: Концепция checkpointing + graph-based flow
|
||
|
||
### 2.3 Claude Agent SDK
|
||
|
||
- **Модель**: Tool-use chain с sub-agents
|
||
- **Сильное**: Нативная интеграция с Claude, safety-first
|
||
- **Слабое**: Только Claude модели, лёгкий на оркестрацию
|
||
- **Для нас**: Lifecycle hooks
|
||
|
||
### 2.4 Нативные субагенты Claude Code
|
||
|
||
- **Как работают**: `claude -p "task" --session-id "id"` запускает ОТДЕЛЬНЫЙ процесс
|
||
- **КЛЮЧЕВОЕ**: Это РЕАЛЬНАЯ изоляция контекста! Каждый субагент — отдельное контекстное окно
|
||
- **Ограничение**: Нет координации "из коробки", нет shared memory, нет PM-слоя
|
||
|
||
---
|
||
|
||
## ЧАСТЬ 3: Архитектура Kin (наш проект)
|
||
|
||
### 3.1 Ключевой принцип
|
||
|
||
> **Каждый агент = отдельный Claude Code процесс с изолированным контекстом.**
|
||
> Compaction в рамках одного агента не убивает нюансы, потому что его контекст маленький и специализированный.
|
||
> PM-агент держит мета-уровень, а не весь код.
|
||
|
||
### 3.2 Живая иерархия с динамической маршрутизацией
|
||
|
||
Не pipeline (A→B→C→D), а **живая организация**: каждый уровень понимает
|
||
свою зону ответственности и собирает нужную команду под задачу.
|
||
|
||
```
|
||
[Ты (Михаил)] ← человеческая речь, свободная форма:
|
||
│ "клиент пишет что фильтры глючат на айфоне когда быстро тыкаешь"
|
||
│ "нужен агрегатор туров, чтобы парсить предложения"
|
||
│ "что у меня горит?"
|
||
│ "посмотри что там с NeverDNS, давно не трогали"
|
||
▼
|
||
[Intake-менеджер] — УМНЫЙ агент (Sonnet), НЕ код на Python.
|
||
│ Почему агент, а не код:
|
||
│ - Клиент пишет "фильтры глючат на айфоне когда быстро тыкаешь"
|
||
│ → код не поймёт нюанс "быстро тыкаешь" = race condition
|
||
│ → агент переформулирует для команды
|
||
│ - Ты пишешь "посмотри что там с NeverDNS"
|
||
│ → это не задача, это запрос на статус + возможно ревью
|
||
│ → агент разберётся
|
||
│
|
||
│ Что делает:
|
||
│ 1. Понимает контекст (ты — директор и продажник, клиенты через тебя)
|
||
│ 2. Определяет проект, тип задачи, срочность
|
||
│ 3. Задаёт уточняющие вопросы если надо
|
||
│ 4. Формулирует задачу на языке команды
|
||
│ 5. Для простых запросов (статус) — SQL к БД, без агентов
|
||
│ 6. Для задач — маршрутизирует к нужному PM проекта
|
||
│ 7. Для новых проектов — запускает цепочку research → design → architecture
|
||
│
|
||
│ Его контекст: список проектов + статусы (из БД, маленький)
|
||
│ НЕ знает: код, архитектуру, детали — только "кто чем занимается"
|
||
│
|
||
├── [PM:vdolipoperek] ── знает проект ГЛУБОКО
|
||
│ │ Что знает: модули, tech stack, decisions, грабли, текущий статус
|
||
│ │ Что умеет: декомпозировать задачу, выбрать нужных специалистов
|
||
│ │ Его контекст: decisions + modules + текущие tasks (из БД)
|
||
│ │
|
||
│ │ Intake передаёт: "Баг: фильтры поиска не применяются при
|
||
│ │ быстром переключении на iOS Safari.
|
||
│ │ Источник: жалоба клиента. Приоритет: высокий."
|
||
│ │
|
||
│ │ PM думает: "фильтры — это модуль search. iOS Safari —
|
||
│ │ у нас уже была decision #15 про position:fixed.
|
||
│ │ Нужен дебагер на модуль search."
|
||
│ │
|
||
│ │ ┌─── [Дебагер] ← описание бага + код модуля + decision #15
|
||
│ │ │ │ ищет проблему
|
||
│ │ │ │ нашёл: "race condition в async фильтре"
|
||
│ │ │ ▼
|
||
│ │ │ [Тестировщик] ← найденный баг + модуль
|
||
│ │ │ │ regression test, подтверждает баг
|
||
│ │ │ ▼
|
||
│ │ │ [Фронтендер] ← баг + тест + spec модуля
|
||
│ │ │ │ фиксит, тест проходит
|
||
│ │ │ ▼
|
||
│ │ └─── [PM] ← результат. Записывает decision:
|
||
│ │ "race condition в SearchFilters — debounce + AbortController"
|
||
│ │ → Intake сообщает тебе → ты сообщаешь клиенту
|
||
│ │
|
||
│ │ Другой пример: "добавить оплату на сайт"
|
||
│ │ PM: "новый модуль, нужна полная команда"
|
||
│ │
|
||
│ │ ┌─── [Маркетолог] ← "платежи на сайте турагентства"
|
||
│ │ │ │ исследует: как конкуренты делают checkout,
|
||
│ │ │ │ какие conversion-паттерны, trust signals
|
||
│ │ │ ▼
|
||
│ │ │ [UX-дизайнер] ← research маркетолога + brief
|
||
│ │ │ │ проектирует: user flow оплаты, wireframes
|
||
│ │ │ ▼
|
||
│ │ │ [Архитектор] ← UX flow + brief + все decisions проекта
|
||
│ │ │ │ spec: модули, API, БД, интеграция с платёжкой
|
||
│ │ │ ▼
|
||
│ │ │ [Безопасник] ← spec (PCI DSS для платежей!)
|
||
│ │ │ │ security requirements
|
||
│ │ │ ▼
|
||
│ │ │ [Бэкендер] ← spec + security reqs (параллельно!)
|
||
│ │ │ [Фронтендер] ← spec + UX wireframes
|
||
│ │ │ ▼
|
||
│ │ │ [Ревьюер] + [Тестировщик] + [Безопасник]
|
||
│ │ └─── [PM] ← всё готово, decisions обновлены
|
||
│ │
|
||
├── [PM:sharedbox] ── знает свой проект так же глубоко
|
||
│ └── (своя динамическая команда)
|
||
│
|
||
├── [PM:neverdns] ── знает: готов, в маркетинг-фазе
|
||
│ └── (маркетолог, копирайтер, SEO — другая команда!)
|
||
│
|
||
└── ... (остальные проекты)
|
||
|
||
|
||
[Для НОВЫХ проектов — отдельная цепочка:]
|
||
|
||
Intake: "нужен агрегатор туров"
|
||
│
|
||
├── [Бизнес-аналитик] ← хотелки + контекст (турагентство)
|
||
│ │ исследует: бизнес-модель, монетизация, целевая аудитория
|
||
│ │ может спавнить:
|
||
│ │ [Исследователь рынка] ← конкуренты, ниша
|
||
│ │ [Исследователь API] ← какие API поставщиков туров есть
|
||
│ │ [Исследователь юридики] ← лицензии, договора
|
||
│ ▼
|
||
├── [UX-дизайнер] ← research + хотелки
|
||
│ │ user journey, wireframes ключевых страниц
|
||
│ │ смотрит конкурентов, лучшие практики
|
||
│ ▼
|
||
├── [Маркетолог] ← research + UX
|
||
│ │ стратегия продвижения, SEO, механики удержания
|
||
│ │ что учесть при разработке для маркетинга
|
||
│ ▼
|
||
├── [Архитектор] ← research + UX + marketing reqs
|
||
│ │ project_blueprint: модули, tech stack, план
|
||
│ │ учитывает существующий стек (Vue/Nuxt)
|
||
│ ▼
|
||
└── Создаётся проект в БД → назначается PM → работа начинается
|
||
```
|
||
|
||
### 3.3 Типы задач и маршруты (PM выбирает динамически)
|
||
|
||
PM проекта — это не тупой маршрутизатор, это агент, который ПОНИМАЕТ задачу.
|
||
Но чтобы понимал хорошо, ему нужны "шаблоны маршрутов" как подсказки:
|
||
|
||
```yaml
|
||
# В промпте PM: "ты знаешь эти типы задач и кого вызывать"
|
||
|
||
routes:
|
||
debug:
|
||
description: "Найти и исправить баг"
|
||
typical_flow:
|
||
- debugger: "найди причину, опиши"
|
||
- tester: "напиши regression test, подтверди баг"
|
||
- developer: "исправь, тест должен пройти"
|
||
pm_decides:
|
||
- какой модуль затронут (из знания проекта)
|
||
- frontend или backend баг
|
||
- нужен ли security review (если баг в auth/payments)
|
||
|
||
feature:
|
||
description: "Новая фича"
|
||
typical_flow:
|
||
- architect: "спроектируй"
|
||
- developer: "реализуй" (может быть несколько параллельно)
|
||
- reviewer: "проверь"
|
||
- tester: "протестируй"
|
||
pm_decides:
|
||
- масштаб (один компонент или новый модуль)
|
||
- нужен ли architect (мелкая фича → сразу developer)
|
||
- параллелить ли frontend/backend
|
||
|
||
refactor:
|
||
description: "Рефакторинг существующего кода"
|
||
typical_flow:
|
||
- architect: "оцени scope, предложи план"
|
||
- developer: "рефактори по плану"
|
||
- tester: "прогони существующие тесты"
|
||
pm_decides:
|
||
- затрагивает ли другие модули
|
||
- нужна ли миграция данных
|
||
|
||
security_audit:
|
||
description: "Проверка безопасности"
|
||
typical_flow:
|
||
- security: "проверь по OWASP"
|
||
- developer: "исправь найденное"
|
||
- security: "подтверди исправления"
|
||
|
||
new_project:
|
||
description: "Создание нового проекта с нуля"
|
||
typical_flow:
|
||
- analyst: "исследуй рынок, конкурентов, API"
|
||
- architect: "спроектируй на основе исследования"
|
||
- pm: "декомпозируй blueprint на задачи"
|
||
- # далее — обычные feature/debug задачи
|
||
|
||
hotfix:
|
||
description: "Срочное исправление в продакшене"
|
||
typical_flow:
|
||
- debugger: "найди причину"
|
||
- developer: "минимальный fix"
|
||
- tester: "smoke test"
|
||
constraints:
|
||
- максимум 1 час
|
||
- минимум изменений
|
||
- deploy сразу
|
||
```
|
||
|
||
### 3.4 Пул специалистов (агенты-рабочие)
|
||
|
||
Рабочие агенты — НЕ фиксированный набор. Это **пул ролей**, из которых PM
|
||
собирает команду под задачу. Каждый — отдельный Claude Code процесс.
|
||
|
||
```yaml
|
||
specialists:
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# ИССЛЕДОВАНИЯ И АНАЛИТИКА
|
||
# ═══════════════════════════════════════════════
|
||
|
||
business_analyst:
|
||
prompt: prompts/business_analyst.md
|
||
context: "задание + бизнес-контекст проекта"
|
||
tools: [WebSearch, WebFetch, Read, Write]
|
||
model: opus # стратегические решения
|
||
description: >
|
||
Бизнес-аналитик. Исследует бизнес-модель, монетизацию, целевую
|
||
аудиторию, юридические аспекты. Может спавнить исследователей.
|
||
|
||
market_researcher:
|
||
prompt: prompts/market_researcher.md
|
||
context: "тема исследования + рамки"
|
||
tools: [WebSearch, WebFetch, Write]
|
||
model: sonnet
|
||
description: >
|
||
Исследователь рынка. Конкуренты, ниша, тренды, ценообразование.
|
||
Подчинённый аналитика — копает конкретную тему.
|
||
|
||
tech_researcher:
|
||
prompt: prompts/tech_researcher.md
|
||
context: "что исследовать + ограничения"
|
||
tools: [WebSearch, WebFetch, Read, Write]
|
||
model: sonnet
|
||
description: >
|
||
Технический исследователь. API поставщиков, библиотеки,
|
||
интеграции, бенчмарки. Знает где искать доки, changelog, issues.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# ДИЗАЙН И UX
|
||
# ═══════════════════════════════════════════════
|
||
|
||
ux_designer:
|
||
prompt: prompts/ux_designer.md
|
||
context: "brief + research + примеры конкурентов"
|
||
tools: [WebSearch, WebFetch, Read, Write]
|
||
model: opus # UX-решения критичны для продукта
|
||
description: >
|
||
UX-дизайнер. User journey, wireframes (текстовые/Mermaid),
|
||
information architecture, interaction patterns.
|
||
Смотрит на конкурентов, лучшие практики, accessibility.
|
||
|
||
ui_designer:
|
||
prompt: prompts/ui_designer.md
|
||
context: "wireframes + style guide проекта"
|
||
tools: [Read, Write]
|
||
model: sonnet
|
||
description: >
|
||
UI-дизайнер. Визуальный дизайн, компонентная система,
|
||
типографика, цвета, spacing. Описывает на уровне CSS tokens.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# МАРКЕТИНГ И КОНТЕНТ
|
||
# ═══════════════════════════════════════════════
|
||
|
||
marketer:
|
||
prompt: prompts/marketer.md
|
||
context: "research + продукт + целевая аудитория"
|
||
tools: [WebSearch, WebFetch, Read, Write]
|
||
model: sonnet
|
||
description: >
|
||
Маркетолог. Стратегия продвижения, SEO-требования для разработки,
|
||
conversion-паттерны, A/B тест гипотезы, trust signals.
|
||
Знает исследования по поведению пользователей.
|
||
Даёт требования разработчикам: что учесть в коде для маркетинга.
|
||
|
||
copywriter:
|
||
prompt: prompts/copywriter.md
|
||
context: "brief + tone of voice + целевая аудитория"
|
||
tools: [Read, Write]
|
||
model: sonnet
|
||
description: >
|
||
Копирайтер. Тексты для UI (кнопки, заголовки, ошибки),
|
||
лендинги, описания, meta-теги. Знает русский и английский.
|
||
|
||
seo_specialist:
|
||
prompt: prompts/seo_specialist.md
|
||
context: "сайт + ниша + текущие метрики (если есть)"
|
||
tools: [WebSearch, WebFetch, Read, Write, Bash]
|
||
model: sonnet
|
||
description: >
|
||
SEO-специалист. Техническое SEO, структура URL, meta-теги,
|
||
schema.org разметка, Core Web Vitals, sitemap.
|
||
Даёт конкретные требования фронтендеру и бэкендеру.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# ПРОЕКТИРОВАНИЕ
|
||
# ═══════════════════════════════════════════════
|
||
|
||
architect:
|
||
prompt: prompts/architect.md
|
||
context: "brief + ВСЕ decisions проекта + tech_stack + research (если есть)"
|
||
tools: [Read, Write]
|
||
model: opus # критические решения — максимум мозгов
|
||
description: >
|
||
Системный архитектор. Проектирует архитектуру, модули, API,
|
||
схему БД, интеграции. Выдаёт implementation spec.
|
||
Не пишет код — пишет спецификации.
|
||
|
||
db_architect:
|
||
prompt: prompts/db_architect.md
|
||
context: "spec + текущая схема БД"
|
||
tools: [Read, Write]
|
||
model: opus
|
||
description: >
|
||
Архитектор БД. Схема, миграции, индексы, нормализация.
|
||
Когда SQLite хватит, когда переходить на PostgreSQL.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# РАЗРАБОТКА
|
||
# ═══════════════════════════════════════════════
|
||
|
||
frontend_dev:
|
||
prompt: prompts/frontend_dev.md
|
||
context: "spec модуля + wireframes + relevant decisions (gotchas)"
|
||
tools: [Read, Write, Edit, Bash]
|
||
model: sonnet
|
||
working_dir: "{project_path}"
|
||
description: >
|
||
Фронтендер. Vue/Nuxt/React, CSS, анимации, responsive.
|
||
Работает в директории проекта.
|
||
|
||
backend_dev:
|
||
prompt: prompts/backend_dev.md
|
||
context: "spec модуля + API contracts + relevant decisions"
|
||
tools: [Read, Write, Edit, Bash]
|
||
model: sonnet
|
||
working_dir: "{project_path}"
|
||
description: >
|
||
Бэкендер. Node.js/Python, API, интеграции, бизнес-логика.
|
||
|
||
fullstack_dev:
|
||
prompt: prompts/fullstack_dev.md
|
||
context: "spec модуля + relevant decisions"
|
||
tools: [Read, Write, Edit, Bash]
|
||
model: sonnet
|
||
working_dir: "{project_path}"
|
||
description: >
|
||
Фулстекер. Для мелких задач, где нет смысла делить.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# КАЧЕСТВО
|
||
# ═══════════════════════════════════════════════
|
||
|
||
debugger:
|
||
prompt: prompts/debugger.md
|
||
context: "описание бага + код модуля + логи (если есть)"
|
||
tools: [Read, Bash, Write] # НЕТ Edit! Дебагер ищет, не чинит.
|
||
model: opus # дебаг требует глубокого reasoning
|
||
description: >
|
||
Дебагер. Ищет причину бага, описывает root cause, НЕ исправляет.
|
||
Предлагает решение, но не трогает код.
|
||
|
||
reviewer:
|
||
prompt: prompts/reviewer.md
|
||
context: "код + spec + conventions проекта"
|
||
tools: [Read] # ТОЛЬКО чтение! Ревьюер не правит.
|
||
model: sonnet
|
||
description: >
|
||
Ревьюер. Code review: соответствие spec, качество, паттерны,
|
||
naming, edge cases. Только читает, не правит.
|
||
|
||
tester:
|
||
prompt: prompts/tester.md
|
||
context: "код + spec"
|
||
tools: [Read, Write, Edit, Bash]
|
||
model: sonnet
|
||
working_dir: "{project_path}"
|
||
description: >
|
||
Тестировщик. Unit, integration, e2e тесты. Гоняет, ищет edge cases.
|
||
|
||
qa_analyst:
|
||
prompt: prompts/qa_analyst.md
|
||
context: "spec + UX flow + текущие тесты"
|
||
tools: [Read, Write]
|
||
model: sonnet
|
||
description: >
|
||
QA-аналитик. Тест-планы, тест-кейсы, acceptance criteria.
|
||
Не пишет код тестов — описывает ЧТО тестировать.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# ИНФРАСТРУКТУРА И БЕЗОПАСНОСТЬ
|
||
# ═══════════════════════════════════════════════
|
||
|
||
sysadmin:
|
||
prompt: prompts/sysadmin.md
|
||
context: "инфраструктура проекта + текущий стек"
|
||
tools: [Read, Write, Edit, Bash]
|
||
model: sonnet
|
||
description: >
|
||
Сисадмин. Docker, nginx, CI/CD, мониторинг, бэкапы.
|
||
Знает когда SQLite хватит и когда нужен PostgreSQL.
|
||
Настраивает фаерволы, SSL, деплой. Ставит пакеты/модули.
|
||
|
||
devops:
|
||
prompt: prompts/devops.md
|
||
context: "инфраструктура + pipeline + tech stack"
|
||
tools: [Read, Write, Edit, Bash]
|
||
model: sonnet
|
||
description: >
|
||
DevOps. CI/CD pipeline, автодеплой, blue-green, rollback.
|
||
Docker Compose, GitHub Actions / Forgejo CI.
|
||
|
||
security:
|
||
prompt: prompts/security.md
|
||
context: "код + security-relevant decisions"
|
||
tools: [Read, Bash]
|
||
model: opus # безопасность — не экономим
|
||
description: >
|
||
Безопасник. OWASP, CVE, auth, injection, secrets, dependencies.
|
||
Проверяет фаерволы, ставит ограничения. Знает актуальные уязвимости.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# ЮРИДИЧЕСКАЯ ПОДДЕРЖКА
|
||
# ═══════════════════════════════════════════════
|
||
|
||
legal:
|
||
prompt: prompts/legal.md
|
||
context: "описание задачи/модуля + юрисдикция + тип бизнеса"
|
||
tools: [WebSearch, WebFetch, Read, Write]
|
||
model: opus # юридические решения критичны
|
||
description: >
|
||
Юрист. Анализирует задачу с точки зрения законности:
|
||
- Можно ли так делать? (ЗоЗПП, 152-ФЗ, 54-ФЗ, GDPR...)
|
||
- Что нужно сделать чтобы было можно? (оферта, согласие, лицензия)
|
||
- Какие документы нужны? (политика конфиденциальности, договор)
|
||
- Какие риски? (штрафы, блокировки, претензии)
|
||
НЕ заменяет настоящего юриста — даёт направление и чеклист.
|
||
PM вызывает когда: коммерция, персональные данные, платежи,
|
||
пользовательский контент, трансграничные операции.
|
||
PM НЕ вызывает когда: внутренний инструмент без юрлица.
|
||
|
||
legal_researcher:
|
||
prompt: prompts/legal_researcher.md
|
||
context: "юридический вопрос + юрисдикция"
|
||
tools: [WebSearch, WebFetch, Read, Write]
|
||
model: sonnet
|
||
description: >
|
||
Юридический исследователь. Ищет актуальные нормативные акты,
|
||
судебную практику, разъяснения регуляторов.
|
||
Подчинённый юриста — копает конкретный вопрос.
|
||
|
||
# ═══════════════════════════════════════════════
|
||
# САППОРТ И ОБРАТНАЯ СВЯЗЬ
|
||
# ═══════════════════════════════════════════════
|
||
|
||
support:
|
||
prompt: prompts/support.md
|
||
context: "описание продукта + FAQ + known issues + decisions (gotchas)"
|
||
tools: [Read, Write]
|
||
model: sonnet
|
||
description: >
|
||
Саппорт-агент. Общается с пользователем (через тебя или напрямую).
|
||
Задаёт правильные вопросы, собирает анамнез:
|
||
- Что именно не работает? На каком устройстве/браузере?
|
||
- Воспроизводится ли стабильно? Когда началось?
|
||
- Скриншот/видео?
|
||
Формирует структурированный тикет для PM.
|
||
НЕ обещает сроки, НЕ принимает решения, НЕ выполняет просьбы.
|
||
|
||
support_guard:
|
||
prompt: prompts/support_guard.md
|
||
context: "бизнес-правила проекта + security policies"
|
||
tools: [Read]
|
||
model: sonnet
|
||
description: >
|
||
Фильтр саппорта (безопасник обратной связи).
|
||
Проверяет ВСЕ входящие от клиентов перед тем как они попадут в систему:
|
||
- "Дайте мне данные других пользователей" → REJECT + лог
|
||
- "Сделайте скидку 90%" → REJECT (не в компетенции системы)
|
||
- "Удалите мой аккаунт" → ESCALATE to human (Михаил решает)
|
||
- "Кнопка не работает" → PASS to support → PM
|
||
Классифицирует: bug / feature_request / question / abuse / escalate
|
||
```
|
||
|
||
### 3.4a Саппорт: от ручного к автоматическому (эволюция)
|
||
|
||
```
|
||
=== ФАЗА 1: Саппорт через тебя (сейчас) ===
|
||
|
||
[Клиент] → пишет тебе в WhatsApp/Telegram
|
||
│
|
||
▼
|
||
[Ты] → пересказываешь Intake-менеджеру:
|
||
│ "клиент пишет что фильтры глючат на айфоне"
|
||
▼
|
||
[Intake] → формулирует → [PM проекта] → команда работает
|
||
│
|
||
▼
|
||
[PM] → результат → [Intake] → тебе → ты отвечаешь клиенту
|
||
|
||
|
||
=== ФАЗА 2: Саппорт-агент общается с тобой (скоро) ===
|
||
|
||
[Клиент] → пишет тебе
|
||
│
|
||
▼
|
||
[Ты] → копируешь сообщение клиента в kin:
|
||
│ kin support vdol "текст клиента"
|
||
▼
|
||
[Support] → задаёт тебе уточняющие вопросы:
|
||
│ "Спросите клиента: на каком устройстве? В каком браузере?
|
||
│ Воспроизводится ли если обновить страницу?"
|
||
▼
|
||
[Ты] → спрашиваешь клиента → добавляешь ответы
|
||
▼
|
||
[Support] → формирует тикет → [Support Guard проверяет] → [PM]
|
||
│
|
||
▼
|
||
[PM] → результат → [Support] формулирует ответ клиенту
|
||
→ "Мы нашли и исправили проблему с фильтрами.
|
||
Обновите страницу — должно работать."
|
||
▼
|
||
[Ты] → отправляешь клиенту (можешь отредактировать)
|
||
|
||
|
||
=== ФАЗА 3: Telegram-бот для клиентов (перспектива) ===
|
||
|
||
[Клиент] → пишет в Telegram-бот проекта напрямую
|
||
│
|
||
▼
|
||
[Support Guard] → фильтрует:
|
||
│ abuse/manipulation → BLOCK + лог для тебя
|
||
│ escalation → NOTIFY тебя
|
||
│ нормальный запрос → PASS
|
||
▼
|
||
[Support Bot] → общается с клиентом:
|
||
│ задаёт вопросы, собирает анамнез, показывает FAQ
|
||
│ если FAQ решает проблему → закрывает
|
||
│ если нет → формирует тикет
|
||
▼
|
||
[PM] → принимает тикет, запускает команду
|
||
▼
|
||
[PM] → результат → [Support Bot] → отвечает клиенту
|
||
│
|
||
│ ВСЕ ответы клиентам проходят через Support Guard:
|
||
│ - не раскрывает внутреннюю архитектуру
|
||
│ - не обещает невозможное
|
||
│ - не подтверждает уязвимости
|
||
│ - вежливо, в стиле бренда
|
||
▼
|
||
[Ты] → получаешь summary: "Клиент X обратился с багом Y,
|
||
команда исправила, клиент получил ответ Z"
|
||
(можешь вмешаться в любой момент)
|
||
|
||
|
||
=== ФАЗА 4: Проект живёт сам (далёкая перспектива) ===
|
||
|
||
[Клиенты] → боты → [Support] → [PM] → [Команда] → [Deploy]
|
||
│ │
|
||
▼ ▼
|
||
[Аналитика использования] [Автодеплой фиксов]
|
||
│
|
||
▼
|
||
[Маркетолог] → "конверсия упала на 5% на странице X"
|
||
→ [PM] → [UX-дизайнер] → [Фронтендер] → [A/B тест]
|
||
|
||
[Ты] = стратегическое управление + финальное approve на крупные изменения
|
||
```
|
||
|
||
**Таблицы для саппорта (добавить в БД):**
|
||
|
||
```sql
|
||
-- Тикеты от пользователей
|
||
CREATE TABLE support_tickets (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
project_id TEXT NOT NULL REFERENCES projects(id),
|
||
source TEXT NOT NULL, -- 'manual', 'telegram_bot', 'email'
|
||
client_id TEXT, -- идентификатор клиента (telegram id, email...)
|
||
client_message TEXT NOT NULL, -- исходное сообщение клиента
|
||
classification TEXT, -- 'bug', 'feature_request', 'question', 'abuse', 'escalate'
|
||
guard_result TEXT, -- 'pass', 'reject', 'escalate'
|
||
guard_reason TEXT, -- почему отклонено/эскалировано
|
||
anamnesis JSON, -- собранная информация (устройство, шаги, скриншоты)
|
||
task_id TEXT REFERENCES tasks(id), -- связанная задача (если создана)
|
||
response TEXT, -- ответ клиенту
|
||
response_approved BOOLEAN DEFAULT FALSE, -- ты одобрил ответ?
|
||
status TEXT DEFAULT 'new', -- new, collecting_info, in_progress, resolved, rejected
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
resolved_at DATETIME
|
||
);
|
||
|
||
-- Настройки бота для каждого проекта
|
||
CREATE TABLE support_bot_config (
|
||
project_id TEXT PRIMARY KEY REFERENCES projects(id),
|
||
telegram_bot_token TEXT, -- токен Telegram-бота (encrypted)
|
||
welcome_message TEXT, -- приветствие
|
||
faq JSON, -- часто задаваемые вопросы
|
||
auto_reply BOOLEAN DEFAULT FALSE, -- автоматически отвечать клиентам?
|
||
require_approval BOOLEAN DEFAULT TRUE, -- требовать одобрение ответов?
|
||
brand_voice TEXT, -- стиль общения ("формальный", "дружелюбный")
|
||
forbidden_topics JSON, -- что нельзя обсуждать с клиентами
|
||
escalation_keywords JSON -- триггеры для эскалации к тебе
|
||
);
|
||
|
||
CREATE INDEX idx_tickets_project ON support_tickets(project_id, status);
|
||
CREATE INDEX idx_tickets_client ON support_tickets(client_id);
|
||
```
|
||
|
||
**Итого: ~24 специализации в 9 отделах:**
|
||
|
||
| Отдел | Роли | PM вызывает когда |
|
||
|-------|------|-------------------|
|
||
| Исследования | business_analyst, market_researcher, tech_researcher | Новый проект, новый модуль, выбор технологии |
|
||
| Дизайн | ux_designer, ui_designer | Новый модуль, редизайн, улучшение UX |
|
||
| Маркетинг | marketer, copywriter, seo_specialist | Запуск, лендинги, SEO, контент |
|
||
| Проектирование | architect, db_architect | Новый модуль, рефакторинг, масштабирование |
|
||
| Разработка | frontend_dev, backend_dev, fullstack_dev | Реализация |
|
||
| Качество | debugger, reviewer, tester, qa_analyst | Баги, ревью, тесты |
|
||
| Инфраструктура | sysadmin, devops, security | Деплой, CI/CD, безопасность |
|
||
| Юридическая | legal, legal_researcher | Коммерция, ПД, платежи, оферты, лицензии |
|
||
| Саппорт | support, support_guard | Обратная связь от клиентов |
|
||
|
||
PM не вызывает всех — он собирает команду под задачу:
|
||
- Мелкий баг от клиента: support → PM → debugger → tester → frontend_dev
|
||
- Новый модуль с платежами: legal → marketer → ux → architect → security → devs → review
|
||
- Новый коммерческий проект: analyst → researchers → legal → ux → marketer → architect
|
||
- Внутренний инструмент: architect → fullstack_dev → tester (без юриста и маркетолога)
|
||
|
||
**Разделение прав (КРИТИЧНО):**
|
||
- Исследователи/аналитики: WebSearch + Read + Write (документы). Не трогают код.
|
||
- Дизайнеры: Read + Write (спеки, wireframes). Не трогают код.
|
||
- Маркетологи: WebSearch + Read + Write. Не трогают код — дают требования.
|
||
- Архитектор: Read + Write (спеки). Не пишет код.
|
||
- Дебагер: Read + Bash. Ищет, НЕ правит.
|
||
- Ревьюер: ТОЛЬКО Read. Не трогает.
|
||
- Разработчики: полный доступ, но только к своему модулю.
|
||
- Сисадмин/DevOps: полный доступ к инфраструктуре.
|
||
- Безопасник: Read + Bash. Не правит — выдаёт требования.
|
||
- Саппорт: Read + Write (тикеты). Не трогает код, не принимает решений.
|
||
- Support Guard: ТОЛЬКО Read. Фильтр — пропускает/блокирует/эскалирует.
|
||
|
||
### 3.5 Протокол обмена между агентами
|
||
|
||
Агенты общаются ТОЛЬКО через структурированные артефакты в БД.
|
||
Никакого shared context. Каждый артефакт — JSON файл + запись в tasks.
|
||
|
||
**Универсальный формат передачи:**
|
||
```json
|
||
{
|
||
"task_id": "VDOL-042",
|
||
"from_role": "pm",
|
||
"to_role": "debugger",
|
||
"type": "debug_request",
|
||
"payload": {
|
||
"bug_description": "Фильтры поиска не применяются при быстром переключении",
|
||
"module": "search",
|
||
"affected_files": [
|
||
"src/components/search/SearchFilters.vue",
|
||
"src/composables/useSearch.ts",
|
||
"src/api/search.ts"
|
||
],
|
||
"known_context": [
|
||
"Фильтры используют async API вызовы",
|
||
"Раньше был похожий баг с debounce (decision #15)"
|
||
],
|
||
"reproduction_steps": "Быстро кликнуть 3 разных фильтра подряд"
|
||
}
|
||
}
|
||
```
|
||
|
||
**PM формирует payload, подтягивая из decisions:**
|
||
```python
|
||
# context_builder собирает для дебагера
|
||
context = {
|
||
"task": db.get_task("VDOL-042"),
|
||
"module_files": git.list_files("src/components/search/"),
|
||
"relevant_decisions": db.get_decisions(
|
||
project_id="vdol",
|
||
category="search",
|
||
types=["gotcha", "workaround"]
|
||
),
|
||
"recent_bugs": db.get_tasks(
|
||
project_id="vdol",
|
||
module="search",
|
||
status="done",
|
||
type="debug",
|
||
limit=5
|
||
)
|
||
}
|
||
```
|
||
|
||
### 3.6 Коммуникация между рабочими агентами
|
||
|
||
Рабочие агенты могут "общаться", но не напрямую — через PM как посредника,
|
||
или через артефакты в файловой системе:
|
||
|
||
```
|
||
[Дебагер] → пишет debug_report.json → [PM читает]
|
||
PM решает: "нужен фронтендер для фикса"
|
||
[PM] → формирует fix_request.json (debug_report + spec) → [Фронтендер]
|
||
[Фронтендер] → правит код → [Тестировщик] запускает тесты
|
||
[Тестировщик] → test_result.json → [PM]
|
||
PM решает: "тесты прошли, закрываю задачу" или "фейл, обратно фронтендеру"
|
||
```
|
||
|
||
**НО: для скорости можно разрешить прямую цепочку без PM:**
|
||
|
||
```
|
||
# PM заранее описывает pipeline
|
||
kin run VDOL-042 --pipeline "debugger → tester → frontend_dev → tester"
|
||
# Каждый агент передаёт результат следующему через файл
|
||
# PM получает только финальный результат + все промежуточные в логах
|
||
```
|
||
|
||
### 3.7 Механизм запуска (как это работает технически)
|
||
|
||
```bash
|
||
# Сценарий 1: ты пишешь в Telegram
|
||
"продебажь фильтры в vdolipoperek"
|
||
|
||
# Диспетчер (Python):
|
||
# 1. Парсит: проект=vdol, тип=debug, что=фильтры
|
||
# 2. Запускает PM проекта:
|
||
|
||
claude -p "$(cat prompts/pm.md)
|
||
|
||
ПРОЕКТ: vdolipoperek
|
||
TECH STACK: Vue 3, TypeScript, Nuxt
|
||
ТЕКУЩИЕ DECISIONS:
|
||
$(kin decisions vdol --category search --format brief)
|
||
|
||
ЗАДАЧА: продебажь фильтры — не применяются при быстром переключении
|
||
ДОСТУПНЫЕ СПЕЦИАЛИСТЫ: debugger, frontend_dev, backend_dev, tester, reviewer, security
|
||
ШАБЛОНЫ МАРШРУТОВ: $(cat routes.yaml)
|
||
|
||
Декомпозируй задачу и верни JSON с pipeline." \
|
||
--session-id "pm-vdol-$(date +%s)" \
|
||
--output-format json
|
||
|
||
# PM возвращает:
|
||
{
|
||
"task_id": "VDOL-043",
|
||
"pipeline": [
|
||
{"role": "debugger", "module": "search", "brief": "..."},
|
||
{"role": "tester", "depends_on": "debugger", "brief": "regression test"},
|
||
{"role": "frontend_dev", "depends_on": "tester", "brief": "fix"},
|
||
{"role": "tester", "depends_on": "frontend_dev", "brief": "verify fix"}
|
||
],
|
||
"decisions_to_load": [15, 23] # PM знает какие decisions релевантны
|
||
}
|
||
|
||
# Runner исполняет pipeline:
|
||
for step in pipeline:
|
||
context = context_builder.build(step.role, step.module, step.decisions)
|
||
result = claude_run(step.role, context, project_path)
|
||
save_result(step, result)
|
||
if not result.success:
|
||
escalate_to_pm(step, result) # PM решает что делать
|
||
```
|
||
|
||
```bash
|
||
# Сценарий 2: новый проект
|
||
"нужен агрегатор туров, чтобы парсить предложения и показывать клиентам"
|
||
|
||
# Диспетчер определяет: тип=new_project
|
||
# Запускает Аналитика (БЕЗ PM, потому что проекта ещё нет):
|
||
|
||
claude -p "$(cat prompts/analyst.md)
|
||
Исследуй тему: агрегатор туров для турагентства.
|
||
Контекст: существующий сайт vdolipoperek.com (Vue/Nuxt).
|
||
Нужно: конкуренты, доступные API поставщиков туров, ценообразование,
|
||
технические ограничения. Верни market_research.json" \
|
||
--session-id "analyst-new-$(date +%s)" \
|
||
--tools WebSearch,WebFetch,Write
|
||
|
||
# Аналитик может спавнить исследователей:
|
||
# - "исследователь API" — ищет API TUI, Pegas, Anex...
|
||
# - "исследователь конкурентов" — анализирует level.travel, onlinetours...
|
||
|
||
# После: Архитектор получает research + хотелки:
|
||
claude -p "$(cat prompts/architect.md)
|
||
ИССЛЕДОВАНИЕ: $(cat market_research.json)
|
||
ХОТЕЛКИ: агрегатор туров, парсинг предложений, отображение клиентам
|
||
СУЩЕСТВУЮЩИЙ СТЕК: Vue 3, Nuxt, Node.js
|
||
Спроектируй project_blueprint.json" \
|
||
--session-id "arch-new-$(date +%s)"
|
||
|
||
# Blueprint → создаётся проект в БД → назначается PM → работа начинается
|
||
```
|
||
|
||
### 3.5 State Management
|
||
|
||
**SQLite база — мультипроектная с рождения:**
|
||
|
||
```sql
|
||
-- Проекты (центральный реестр)
|
||
CREATE TABLE projects (
|
||
id TEXT PRIMARY KEY, -- 'vdol', 'sharedbox', 'neverdns', 'barsik', 'askai'
|
||
name TEXT NOT NULL, -- 'В долю поперёк', 'SharedBox', 'NeverDNS'
|
||
path TEXT NOT NULL, -- ~/projects/mailbox, ~/projects/vdolipoperek
|
||
tech_stack JSON, -- ["vue3", "typescript", "nuxt"]
|
||
status TEXT DEFAULT 'active', -- active, paused, maintenance, ready
|
||
priority INTEGER DEFAULT 5, -- 1=критический, 10=когда-нибудь
|
||
pm_prompt TEXT, -- путь к кастомному промпту PM для этого проекта
|
||
claude_md_path TEXT, -- путь к CLAUDE.md проекта
|
||
forgejo_repo TEXT, -- owner/repo для синхронизации issues
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- Задачи (привязаны к проекту)
|
||
CREATE TABLE tasks (
|
||
id TEXT PRIMARY KEY, -- VDOL-042, SB-015, NDNS-003
|
||
project_id TEXT NOT NULL REFERENCES projects(id),
|
||
title TEXT NOT NULL,
|
||
status TEXT DEFAULT 'pending', -- pending, decomposed, in_progress, review, done, blocked
|
||
priority INTEGER DEFAULT 5,
|
||
assigned_role TEXT, -- architect, developer, reviewer, tester, security
|
||
parent_task_id TEXT REFERENCES tasks(id), -- для подзадач
|
||
brief JSON, -- Task Brief от PM
|
||
spec JSON, -- Implementation Spec от архитектора
|
||
review JSON, -- Review Result
|
||
test_result JSON, -- Test Result
|
||
security_result JSON, -- Security Check Result
|
||
forgejo_issue_id INTEGER, -- связка с Forgejo issue
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- Решения и грабли (КЛЮЧЕВАЯ ТАБЛИЦА — то что теряется при compaction)
|
||
-- Это ВНЕШНЯЯ ПАМЯТЬ PM-агента для каждого проекта
|
||
CREATE TABLE decisions (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
project_id TEXT NOT NULL REFERENCES projects(id),
|
||
task_id TEXT REFERENCES tasks(id), -- может быть NULL для общепроектных решений
|
||
type TEXT NOT NULL, -- 'decision', 'gotcha', 'workaround', 'rejected_approach', 'convention'
|
||
category TEXT, -- 'architecture', 'ui', 'api', 'security', 'devops', 'performance'
|
||
title TEXT NOT NULL,
|
||
description TEXT NOT NULL,
|
||
tags JSON, -- ["ios-safari", "css", "bottom-sheet"] для поиска
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- Логи агентов (для дебага, обучения и cost tracking)
|
||
CREATE TABLE agent_logs (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
project_id TEXT NOT NULL REFERENCES projects(id),
|
||
task_id TEXT REFERENCES tasks(id),
|
||
agent_role TEXT NOT NULL, -- pm, analyst, architect, debugger, frontend_dev, etc.
|
||
session_id TEXT, -- claude --session-id
|
||
action TEXT NOT NULL, -- 'decompose', 'implement', 'review', 'test', 'fix', 'research'
|
||
input_summary TEXT, -- что получил (краткое описание, не полный текст)
|
||
output_summary TEXT, -- что выдал
|
||
tokens_used INTEGER,
|
||
model TEXT, -- haiku, sonnet, opus
|
||
cost_usd REAL, -- стоимость вызова
|
||
success BOOLEAN,
|
||
error_message TEXT,
|
||
duration_seconds INTEGER,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- Модули проекта (PM знает структуру)
|
||
-- Это "карта" проекта для PM: он знает какие модули есть и кого вызвать
|
||
CREATE TABLE modules (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
project_id TEXT NOT NULL REFERENCES projects(id),
|
||
name TEXT NOT NULL, -- 'search', 'auth', 'payments', 'ui-kit'
|
||
type TEXT NOT NULL, -- 'frontend', 'backend', 'shared', 'infra'
|
||
path TEXT NOT NULL, -- 'src/components/search/', 'src/api/search.ts'
|
||
description TEXT, -- 'Поиск и фильтрация туров'
|
||
owner_role TEXT, -- 'frontend_dev', 'backend_dev' — кого вызывать
|
||
dependencies JSON, -- ["auth", "api-client"] — зависимости между модулями
|
||
UNIQUE(project_id, name)
|
||
);
|
||
|
||
-- Pipelines (история запусков — для обучения и повторного использования)
|
||
CREATE TABLE pipelines (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
task_id TEXT NOT NULL REFERENCES tasks(id),
|
||
project_id TEXT NOT NULL REFERENCES projects(id),
|
||
route_type TEXT NOT NULL, -- 'debug', 'feature', 'refactor', 'hotfix', 'new_project'
|
||
steps JSON NOT NULL, -- pipeline JSON от PM
|
||
status TEXT DEFAULT 'running', -- running, completed, failed, cancelled
|
||
total_cost_usd REAL,
|
||
total_tokens INTEGER,
|
||
total_duration_seconds INTEGER,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||
completed_at DATETIME
|
||
);
|
||
|
||
-- Кросс-проектные зависимости и связи
|
||
CREATE TABLE project_links (
|
||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||
from_project TEXT NOT NULL REFERENCES projects(id),
|
||
to_project TEXT NOT NULL REFERENCES projects(id),
|
||
type TEXT NOT NULL, -- 'depends_on', 'shares_component', 'blocks'
|
||
description TEXT,
|
||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||
);
|
||
|
||
-- Индексы для быстрого доступа PM-агентов
|
||
CREATE INDEX idx_tasks_project_status ON tasks(project_id, status);
|
||
CREATE INDEX idx_decisions_project ON decisions(project_id);
|
||
CREATE INDEX idx_decisions_tags ON decisions(tags); -- для JSON-поиска по тегам
|
||
CREATE INDEX idx_agent_logs_project ON agent_logs(project_id, created_at);
|
||
CREATE INDEX idx_agent_logs_cost ON agent_logs(project_id, cost_usd);
|
||
```
|
||
|
||
### 3.6 Контекст-билдер (КЛЮЧЕВОЙ КОМПОНЕНТ)
|
||
|
||
Перед запуском любого агента, система собирает контекст из БД:
|
||
|
||
```
|
||
kin run VDOL-042
|
||
│
|
||
▼
|
||
[context-builder]
|
||
│
|
||
├── Читает task VDOL-042 из tasks table → brief, spec
|
||
├── Читает decisions WHERE project_id='vdol' → релевантные грабли
|
||
│ (фильтрует по category и tags, не грузит ВСЕ решения)
|
||
├── Читает projects WHERE id='vdol' → tech_stack, claude_md_path
|
||
├── Формирует МИНИМАЛЬНЫЙ контекст для конкретной роли:
|
||
│
|
||
│ Для архитектора: brief + ALL decisions (он должен знать историю)
|
||
│ Для программиста: spec + decisions WHERE category IN ('gotcha','workaround')
|
||
│ Для ревьюера: spec + код + decisions WHERE type='convention'
|
||
│ Для тестировщика: spec + код (минимум)
|
||
│ Для безопасника: код + security conventions
|
||
│
|
||
└── Запускает claude -p с собранным контекстом
|
||
```
|
||
|
||
**Это решает проблему "раздувшихся CLAUDE.md":** контекст собирается динамически и фильтруется по роли.
|
||
|
||
### 3.7 Meta-PM: обзор всех проектов
|
||
|
||
Meta-PM — самый "тупой" но самый полезный агент. Он работает с VIEW-запросами к БД:
|
||
|
||
```sql
|
||
-- "Что горит?" — для Meta-PM
|
||
SELECT p.name, p.priority, p.status,
|
||
COUNT(CASE WHEN t.status = 'blocked' THEN 1 END) as blocked_tasks,
|
||
COUNT(CASE WHEN t.status = 'in_progress' THEN 1 END) as active_tasks,
|
||
COUNT(CASE WHEN t.status = 'pending' THEN 1 END) as pending_tasks,
|
||
MAX(t.updated_at) as last_activity
|
||
FROM projects p
|
||
LEFT JOIN tasks t ON t.project_id = p.id
|
||
WHERE p.status = 'active'
|
||
GROUP BY p.id
|
||
ORDER BY p.priority ASC, blocked_tasks DESC;
|
||
|
||
-- "Сколько трачу?" — cost tracking
|
||
SELECT p.name,
|
||
SUM(al.cost_usd) as total_cost,
|
||
SUM(al.tokens_used) as total_tokens,
|
||
COUNT(*) as agent_calls
|
||
FROM agent_logs al
|
||
JOIN projects p ON p.id = al.project_id
|
||
WHERE al.created_at > datetime('now', '-7 days')
|
||
GROUP BY p.id
|
||
ORDER BY total_cost DESC;
|
||
```
|
||
|
||
### 3.8 Компоненты
|
||
|
||
```
|
||
kin/
|
||
├── core/
|
||
│ ├── db.py -- SQLite init, migrations
|
||
│ ├── models.py -- Projects, Tasks, Decisions, Modules, Pipelines
|
||
│ ├── context_builder.py -- формирование контекста ПО РОЛИ из БД
|
||
│ └── api.py -- REST API для GUI (FastAPI, читает ту же SQLite)
|
||
│
|
||
├── agents/
|
||
│ ├── prompts/ -- ~24 промпта (pm.md, architect.md, debugger.md...)
|
||
│ ├── routes.yaml -- шаблоны маршрутов (debug, feature, refactor...)
|
||
│ ├── specialists.yaml -- пул ролей с tools, model, context rules
|
||
│ └── runner.py -- запуск claude -p, pipeline executor
|
||
│
|
||
├── cli/
|
||
│ └── main.py
|
||
│ # kin status — все проекты одним взглядом
|
||
│ # kin run VDOL-043 — PM декомпозирует + pipeline
|
||
│ # kin run VDOL-043 --dry-run — показать pipeline без запуска
|
||
│ # kin ask "что горит?" — Intake отвечает
|
||
│ # kin support vdol "текст" — тикет от клиента
|
||
│ # kin cost --last 7d — расходы
|
||
│ # kin new-project "агрегатор" — analyst → architect → PM
|
||
│
|
||
├── web/ -- GUI (Vue 3 + TypeScript — твой стек!)
|
||
│ ├── src/
|
||
│ │ ├── views/
|
||
│ │ │ ├── Dashboard.vue -- обзор всех проектов
|
||
│ │ │ ├── ProjectView.vue -- один проект: задачи, модули, decisions
|
||
│ │ │ ├── PipelineView.vue -- pipeline задачи: кто работает, где блокер
|
||
│ │ │ ├── CostView.vue -- расходы по проектам и задачам
|
||
│ │ │ └── SupportView.vue -- тикеты от клиентов
|
||
│ │ ├── components/
|
||
│ │ │ ├── ProjectCard.vue -- карточка проекта со статусом
|
||
│ │ │ ├── PipelineGraph.vue -- визуализация pipeline (граф агентов)
|
||
│ │ │ ├── AgentStatus.vue -- статус агента (idle/working/done/error)
|
||
│ │ │ ├── DecisionsList.vue -- decisions проекта с поиском по тегам
|
||
│ │ │ └── LiveLog.vue -- real-time лог текущего pipeline
|
||
│ │ └── App.vue
|
||
│ └── package.json
|
||
│
|
||
├── integrations/
|
||
│ ├── telegram_bot.py -- бот-интерфейс (для тебя + клиентские боты)
|
||
│ └── forgejo_sync.py -- двусторонняя синхронизация issues ↔ tasks
|
||
│
|
||
├── config/
|
||
│ └── projects.yaml -- начальная конфигурация проектов
|
||
│
|
||
└── kin.db -- SQLite база (единственный source of truth)
|
||
```
|
||
|
||
### 3.9 GUI: что нужно видеть
|
||
|
||
**Dashboard (главный экран):**
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Kin Dashboard Cost: $47/week │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 🔴 vdolipoperek 3 active 1 blocked $12/week │
|
||
│ └─ VDOL-043: debug фильтров [████░░] debugger → tester │
|
||
│ └─ VDOL-044: mobile bottom-sheet [██████] done ✓ │
|
||
│ └─ VDOL-045: оплата [░░░░░░] blocked: ждёт юриста │
|
||
│ │
|
||
│ 🟡 sharedbox 1 active $8/week │
|
||
│ └─ SB-016: multi-tenant isolation [██░░░░] architect │
|
||
│ │
|
||
│ 🟢 neverdns 0 active $0/week │
|
||
│ └─ маркетинг-фаза, ждёт контент │
|
||
│ │
|
||
│ 🟢 barsik 1 active $5/week │
|
||
│ └─ BARS-007: RAG pipeline [████░░] backend_dev │
|
||
│ │
|
||
│ ⚪ askai 0 active $0/week │
|
||
│ ⚪ ddfo 0 active $0/week │
|
||
│ ⚪ stopleak 0 active $0/week │
|
||
│ │
|
||
│ ─── Support ─── │
|
||
│ 2 новых тикета (vdolipoperek) │
|
||
│ 1 ожидает твоего approve │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Pipeline View (конкретная задача):**
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ VDOL-043: Debug фильтров поиска Status: in_progress│
|
||
│ Priority: high Cost: $1.82 Duration: 12 min │
|
||
├─────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ [PM] ──────► [Debugger] ──────► [Tester] ──────► [Frontend]│
|
||
│ ✓ 0.3s ✓ $0.45 ● working ○ pending│
|
||
│ decomposed found: writing │
|
||
│ pipeline race condition regression │
|
||
│ in useSearch.ts test │
|
||
│ │
|
||
│ Decisions добавлены: │
|
||
│ #47: "race condition в async фильтре — AbortController" │
|
||
│ │
|
||
│ ─── Live Log ─── │
|
||
│ 12:04:32 [tester] Запущен: session tst-VDOL043-1710... │
|
||
│ 12:04:33 [tester] Читает: src/composables/useSearch.ts │
|
||
│ 12:04:45 [tester] Пишет: tests/search.filter.spec.ts │
|
||
│ 12:05:01 [tester] Bash: npm run test -- search.filter │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Почему Vue 3:** это твой стек, ты на нём строишь vdolipoperek.
|
||
GUI Kin — это тоже проект, который Kin может помогать разрабатывать.
|
||
Meta-moment: Kin строит свой собственный GUI.
|
||
|
||
**Архитектура GUI:**
|
||
```
|
||
[kin.db] ← SQLite (source of truth)
|
||
│
|
||
├── [core/api.py] ← FastAPI, REST endpoints
|
||
│ GET /projects — список проектов со статусами
|
||
│ GET /projects/{id} — детали проекта + задачи + modules
|
||
│ GET /tasks/{id} — задача + pipeline + agent logs
|
||
│ GET /tasks/{id}/live — SSE stream для live log
|
||
│ GET /pipelines/{id} — граф pipeline с статусами
|
||
│ GET /decisions?project=X — decisions с фильтрами
|
||
│ GET /support/tickets — тикеты от клиентов
|
||
│ GET /cost?period=7d — расходы
|
||
│ POST /tasks — создать задачу
|
||
│ POST /tasks/{id}/run — запустить pipeline
|
||
│ POST /support/approve/{id} — одобрить ответ клиенту
|
||
│
|
||
└── [web/] ← Vue 3 + TypeScript, Vite
|
||
Подключается к API
|
||
SSE для live обновлений pipeline
|
||
Responsive (работает с MacBook и с телефона)
|
||
```
|
||
|
||
**Ключевое:** GUI читает ту же SQLite что и CLI/runner.
|
||
Нет отдельной базы для GUI, нет sync проблем.
|
||
runner.py пишет в kin.db → API читает → Vue показывает.
|
||
Real-time через SSE (Server-Sent Events) — runner пишет лог → API стримит → Vue обновляет.
|
||
|
||
### 3.10 Интеграция с существующей инфраструктурой
|
||
|
||
- **Forgejo**: Двусторонний sync — issue создано в Forgejo → task в kin, task завершён → issue закрыт. Forgejo остаётся UI для ручного просмотра.
|
||
- **Obsidian**: Decisions из БД экспортируются как .md в vault. Kanban-доска читает задачи. Направление: kin → Obsidian (read-only зеркало).
|
||
- **Telegram бот**: Основной мобильный интерфейс. Свободная форма: "продебажь фильтры в vdolipoperek" → dispatcher парсит → PM → pipeline.
|
||
- **Mac Mini M4 Pro**: Основной хост. Агенты запускаются как процессы на нём.
|
||
- **MacBook**: Через SSH + Telegram бот. Или Syncthing синхронизирует kin.db (receive-only на MacBook).
|
||
- **CLAUDE.md per project**: Минимальный (30 строк), содержит ТОЛЬКО: "tech stack", "coding conventions", "ссылка на kin для контекста". Decisions НЕ дублируются.
|
||
|
||
### 3.10 Ключевые отличия от Ruflo
|
||
|
||
| Аспект | Ruflo | Kin |
|
||
|--------|-------|---------|
|
||
| Мультипроектность | Нет | Intake + Project PMs |
|
||
| Полнота команды | Только dev | ~22 роли: research, design, marketing, dev, QA, ops, support |
|
||
| Маршрутизация | Фиксированная | PM динамически собирает команду |
|
||
| Изоляция | Один промпт | Каждый агент = отдельный процесс |
|
||
| Обратная связь | Нет | Support → Guard → PM → команда → ответ клиенту |
|
||
| Клиентские боты | Нет | Telegram per project (перспектива) |
|
||
|
||
---
|
||
|
||
## ЧАСТЬ 4: План действий
|
||
|
||
### Фаза 1: Фундамент + один проект (2-3 дня)
|
||
- [ ] SQLite схема (все таблицы включая support)
|
||
- [ ] context-builder, runner.py, pipeline executor
|
||
- [ ] Intake-агент, PM, routes.yaml, specialists.yaml
|
||
- [ ] Базовые промпты: architect, frontend_dev, debugger, tester, reviewer
|
||
- [ ] CLI + тест на vdolipoperek.com
|
||
|
||
### Фаза 2: Полная команда ~22 роли (2-3 дня)
|
||
- [ ] Все промпты, разделение прав
|
||
- [ ] Тест полной цепочки marketer → ux → architect → dev → review
|
||
|
||
### Фаза 3: Все 10 проектов (1-2 дня)
|
||
### Фаза 4: Telegram интеграция (1-2 дня)
|
||
### Фаза 5: Саппорт + Support Guard (1-2 дня)
|
||
### Фаза 6: Forgejo + Obsidian sync (1 день)
|
||
### Фаза 7: Боевой прогон на vdolipoperek (1-2 недели)
|
||
### Фаза 8: Клиентские Telegram-боты (перспектива)
|
||
### Фаза 9: Самоподдерживающиеся проекты (далёкая перспектива)
|
||
|
||
---
|
||
|
||
## ЧАСТЬ 5: Критические ограничения реализации
|
||
|
||
### 5.1 Запрет блокирующего time.sleep в pipeline execution thread
|
||
|
||
**Корень бага KIN-145.** Pipeline агентов выполняется в отдельном потоке (ThreadPoolExecutor или threading.Thread). Этот поток является единственным для всего пайплайна задачи. Любой блокирующий вызов внутри него блокирует весь runner-процесс на время сна.
|
||
|
||
**Механизм каскадного падения:**
|
||
1. `runner.py` вызывает `merge_worktree(worktree_path, p_path, max_retries=3, retry_delay_s=15)` (старый баг)
|
||
2. При git-конфликте `merge_worktree` вызывает `time.sleep(15)` трижды → 45 секунд блокировки
|
||
3. Родительский web-сервер (FastAPI) теряет ответ от воркера
|
||
4. `_check_parent_alive()` во всех других пайплайнах видит `ESRCH` (процесс недоступен) или таймаут
|
||
5. Все in-flight пайплайны помечаются как `failed` → массовое падение всех задач во всех проектах
|
||
|
||
**Почему retry для git-конфликтов бессмысленен:**
|
||
Git merge conflict — детерминированная ошибка. Конфликт возник потому что два ветки расходятся в одном месте файла. Повторная попытка через 15 секунд не изменит содержимое файлов и снова завершится конфликтом. Retry тут не помогает, только блокирует.
|
||
|
||
**Допустимые альтернативы в зависимости от контекста:**
|
||
- `async`-задержка (`asyncio.sleep`) — если код работает в async-окружении
|
||
- отдельный поток (`threading.Thread`) — если нужен polling или retry с задержкой
|
||
- отказ от retry — для детерминированных ошибок (git merge conflict, validation error)
|
||
- `Event.wait(timeout)` — если нужно ждать внешнего события без CPU spin
|
||
|
||
**Правило:**
|
||
> `time.sleep()` в `agents/` ЗАПРЕЩЁН без исключений.
|
||
> В `core/` разрешён только в файлах с явным daemon-thread или retry-контекстом:
|
||
> — `core/watchdog.py` (daemon-поток, отдельный от pipeline)
|
||
> — `core/worktree.py` (retry-delay, вызывается только с явными kwargs, не из runner.py)
|
||
|
||
**Static regression guard:** `tests/test_kin_fix_025_regression.py` сканирует `agents/` и `core/`
|
||
на наличие `time.sleep` — любой новый вызов вне allowlist ломает тест.
|
||
|
||
---
|
||
|
||
## Заметки
|
||
|
||
**Архитектура:** Изоляция контекста через процессы. Decisions = внешняя память PM. PM тупой/памятливый, workers умные/забывчивые. context-builder фильтрует по роли. ~22 роли = полная софтверная компания.
|
||
|
||
**Бизнес:** Полнота > скорость. Продукт = коммерческий, не поделка. Саппорт замыкает цикл. Support Guard критичен. В перспективе проекты живут сами.
|
||
|
||
**Техника:** Python, SQLite (source of truth), cost tracking встроен, Forgejo sync, Obsidian read-only.
|
||
|
||
**Из Ruflo взять:** MCP, SQLite memory, model routing, ADR, hooks. **НЕ брать:** fake parallelism, over-engineering.
|