AI-Секретарь: дизайн системы из 5 агентов

Дата: 2026-04-21 Статус: утверждён для перехода в план реализации Автор дизайна: brainstorming-сессия с пользователем Источник требований: Instructions.md в корне проекта

1. Контекст и цели

Пользователь — предприниматель, у которого главная боль: «не успеваю делать всё руками». Нужен персональный AI-ассистент, выполняющий рутину: работа с документами, финансовый учёт, поиск информации, управление расписанием.

Целевая система: команда из 5 ролей в Claude Code, работающая в реактивном режиме — пользователь пишет сообщение → главный Claude (координатор) маршрутизирует на нужного специалиста → специалист выполняет задачу → координатор возвращает результат.

Роли

  1. Координатор — главный Claude, читающий CLAUDE.md. Решает, кого звать. Не использует MCP.
  2. Юрист (lawyer.md, sub-agent) — анализ и составление юридических документов под право РФ.
  3. Финансист (finance.md, teammate) — учёт доходов/расходов в Google Sheets.
  4. Ресёрч-агент (researcher.md, sub-agent) — веб-исследование и отчёты.
  5. Ассистент календаря (assistant.md, teammate) — управление Google Calendar.

Решения, принятые на брейншторме

Вопрос Решение
Количество агентов 5 (координатор через CLAUDE.md + 4 специалиста в .claude/agents/)
MCP-зависимости В дизайне прописаны как требования; установку делает пользователь
Режим работы Реактивный (инициируется пользователем)
Порядок сборки Все 4 специалиста + координатор сразу
Хранение артефактов Единый artifacts.md в корне проекта
Политика подтверждений B — автономный для очевидного, подтверждение для неочевидного, с per-agent уточнениями
Механика запуска Гибрид: юрист+ресёрч как sub-agents; финансист+ассистент как teammates (tmux)

2. Обзор архитектуры

┌──────────────────────────────────────────────────────┐
│               Пользователь (вы)                       │
│  пишет в Claude Code: текст / файлы / скриншоты       │
└────────────────────────┬─────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  Координатор = главный Claude, читает CLAUDE.md       │
│  • парсит сообщение                                   │
│  • смотрит матрицу маршрутизации                      │
│  • выбирает одного или нескольких агентов             │
│  • если задача неоднозначна — уточняет у пользователя │
└─┬─────────────────┬───────────────┬──────────────────┘
  │ Agent tool      │ Agent tool    │ SendMessage (team)
  ▼                 ▼               ▼
┌─────────────┐ ┌─────────────┐ ┌──────────┬──────────┐
│ lawyer      │ │ researcher  │ │ finance  │ assist   │
│ (sub-agent) │ │ (sub-agent) │ │ (teammate)│(teammate)│
│             │ │             │ │          │          │
│ • pdf skill │ │ • Firecrawl │ │ • Sheets │ • Cal    │
│ • docx skill│ │ • Brave MCP │ │   MCP    │   MCP    │
│ • Drive MCP │ │ • Docs MCP  │ │ • Drive  │          │
└─────────────┘ └─────────────┘ └──────────┴──────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────┐
│  Persistent state                                     │
│  • artifacts.md (корень проекта) — ссылки на URL      │
│  • Google Drive / Sheets / Calendar (внешнее хранилищ)│
└──────────────────────────────────────────────────────┘

Ключевые правила архитектуры

  1. Агенты не знают друг о друге. Координатор — единственная точка маршрутизации. Для комбо-задач (юрист создал счёт → финансист его записал) координатор делает два последовательных вызова.
  2. Sub-agent vs Teammate — критическое различие:
    • Sub-agents: чистый контекст на вызов, для эпизодических задач.
    • Teammates: живой tmux-процесс, сохраняет контекст и MCP-коннекты между сообщениями.
  3. Единственный источник истины для URL артефактов — artifacts.md.
  4. Все агенты работают на русском, что соответствует settings.json.

3. Структура файлов проекта

Day 1/
├── CLAUDE.md                    ← Координатор: роли, маршрутизация, политики
│
├── .claude/
│   └── agents/
│       ├── lawyer.md            ← Юрист (sub-agent)
│       ├── researcher.md        ← Ресёрч-агент (sub-agent)
│       ├── finance.md           ← Финансист (teammate)
│       └── assistant.md         ← Ассистент (teammate)
│
├── artifacts.md                 ← Каталог URL всех созданных артефактов
│
├── templates/                   ← Пусто при старте; наполняется юристом по мере
│   └── README.md                   появления типовых документов
│
├── inbox/                       ← Файлы для анализа (PDF договоров, скриншоты)
│   └── README.md                   опционально — пользователь может кидать файлы
│                                   и прямо в чат через drag-and-drop
│
├── reports/                     ← Юридические отчёты и локальные копии
│   └── .gitkeep                    ресёрч-отчётов (страховка на случай Drive)
│
├── docs/
│   └── superpowers/
│       └── specs/
│           └── 2026-04-21-ai-secretary-design.md  ← этот файл
│
├── Instructions.md              ← Оригинальное ТЗ (не трогаем)
├── Information.md               ← Заметка про VPS (не трогаем)
└── settings.json                ← Настройки Claude Code

Обоснование:

4. Роли и обязанности агентов

4.1 Координатор (CLAUDE.md)

Функции:

4.2 Юрист (lawyer.md, sub-agent)

Идентичность: «Профессиональный юрист в РФ с 15-летним стажем, специализация — договорное право, корпоративное право, налогообложение».

Задачи:

Инструменты: Read, Write, Edit, Glob, skill pdf, skill docx, MCP Google Drive.

Выход: (1) локальный файл в reports/ с отчётом, (2) готовый документ + URL в artifacts.md.

Политика подтверждений: перед записью финального документа — всегда показывает draft и ждёт «ок». Аналитический отчёт выдаёт сразу.

4.3 Финансист (finance.md, teammate)

Идентичность: «Бухгалтер-автоматизатор: учёт ИП, фокус — быстро и точно фиксировать движение денег».

Задачи:

Инструменты: MCP Google Sheets, Read, Write.

Почему teammate: частые короткие операции в одной сессии; живой контекст ловит дубли; не теряет MCP-коннект.

4.4 Ресёрч-агент (researcher.md, sub-agent)

Идентичность: «Аналитик-исследователь: собирает информацию из открытых источников, критически оценивает качество, пишет структурированные отчёты».

Задачи:

Инструменты: MCP Firecrawl, MCP Brave Search, MCP Google Docs, Write, WebFetch (резерв).

Политика подтверждений: отчёт — сразу. При слишком широком запросе — уточняет scope до начала работы.

4.5 Ассистент календаря (assistant.md, teammate)

Идентичность: «Персональный ассистент по расписанию: владеет тайм-менеджментом, предлагает оптимизации, проверяет конфликты».

Задачи:

Инструменты: MCP Google Calendar.

Почему teammate: календарные диалоги многоходовые.

5. Матрица маршрутизации координатора

Порядок принятия решения

получено сообщение
  ├── приложен файл?
  │     ├── image со суммой → finance
  │     └── PDF/DOCX документ → lawyer
  └── текст без файла
        ├── есть ключевое слово → маршрут по таблице ниже
        └── неясно → уточнение у пользователя

Ключевые слова

Агент Триггеры
Юрист договор, контракт, акт, счёт-фактура, КП, коммерческое предложение, ТЗ, NDA, ИП, ООО, оферта, претензия, иск, «проверь документ», «составь договор», приложенный PDF/DOCX
Финансист потратил, купил, заплатил, получил оплату, расход, доход, зарплата, аренда, налог, «сколько я», «мои финансы», «за месяц», скриншот с суммой
Ресёрч «найди информацию», «что такое», «сравни», «лучшие X», «обзор», «исследуй», «анализ рынка», вопрос на знание
Ассистент встреча, календарь, расписание, завтра, на этой неделе, «перенеси», «освободи время», «что у меня», «когда у меня окно»

Обработка неоднозначностей

  1. Два агента в одном запросе — координатор объявляет план вслух и вызывает последовательно.
  2. Неясное намерение — задаёт пользователю уточняющий вопрос с вариантами A/B/C.
  3. Fallback — если за 2 попытки не понял, честно говорит «уточните: юрист / финансист / ресёрч / календарь?».

6. Поток данных и artifacts.md

Формат artifacts.md

# Artifacts — AI-Секретарь

## Финансы
- **Google Sheets:** <URL>
  - Создана: <дата>
  - Категории: Зарплата, Аренда, Транспорт, Логистика, ПО, Налоги

## Юрист
- **Google Drive папка "Документы":** <URL>
- **Договоры:**
  - <дата> — описание — <URL>
- **Счета и акты:**
  - <дата> — описание — <URL>

## Ресёрч
- <дата> — "<тема>" — <URL>
  - Локальная копия: reports/<file>.md

## Календарь
- **Google Calendar ID:** primary

Протокол

Что не хранится в репо

7. Политика подтверждений

Агент Автономно Запрашивает подтверждение
Финансист Явная категория и сумма Непонятная категория; аномальная сумма (>5× медианы); возможный дубль; неясно доход/расход
Юрист Аналитический отчёт Всегда перед записью финального документа
Ресёрч Публикация готового отчёта При слишком широком запросе — уточняет scope
Ассистент 1 событие без конфликтов; 1 перенос без конфликтов Массовые операции; конфликты в слоте; удаление; перенос с участниками

Формат уточняющих вопросов

Агенты не просто спрашивают «уточните», а дают варианты ответа A/B/C/D.

Пример (финансист):

«Получил скриншот 12 400 ₽ “Яндекс.Услуги”. Категория неясна: A) Транспорт B) Логистика C) ПО D) Другое — напишите Это расход или доход? (похоже на расход)»

8. Обработка ошибок

Ошибка Реакция
MCP недоступен Одна retry с задержкой 2с. Если не помогло — возвращает honest error + сохраняет операцию в inbox/pending-<agent>.json для последующего синка
Нераспознаваемый скриншот/PDF Запрашивает ручной ввод, не гадает
Пользователь отказался от подтверждения Удаляет временные файлы, не сохраняет как draft
Противоречие в запросе Останавливается, подсвечивает противоречие, предлагает варианты
Rate limit Сообщает, не ретраит автоматически

Общее правило «честной неуверенности»: если confidence < 0.8 — уточнять, не изобретать.

9. MCP-зависимости и инициализация

Необходимые MCP

MCP Агенты Обязательность
Firecrawl researcher Да (уже подключен ✅)
Brave Search researcher Желателен
Google Sheets finance Критичен
Google Drive lawyer, researcher Желателен
Google Docs lawyer, researcher Желателен
Google Calendar assistant Критичен

Рекомендация по подключению

Установку Google Workspace MCP (покрывающего Sheets + Docs + Drive + Calendar одним сервером) делает пользователь. Варианты: taylorwilsdon/google_workspace_mcp, mattdonders/google-workspace-mcp. В CLAUDE.md — ссылка на инструкцию подключения.

Процедура инициализации (первый запуск)

Пользователь пишет координатору: «Инициализируй систему». Координатор:

  1. Пингует каждый MCP probe-запросом.
  2. Запускает finance: «Создай главную таблицу с тремя листами и дашбордом».
  3. Запускает lawyer: «Создай на Drive папку “Документы AI-Секретарь”».
  4. Собирает созданные URL в artifacts.md.
  5. Отчитывается перед пользователем: что создано, что не создано, какие MCP не подключены.

Graceful degradation

Недоступен Что работает
Brave Search researcher через WebFetch + Firecrawl search
Google Drive lawyer пишет локально в reports/
Google Docs lawyer/researcher отдают .md и .docx
Google Sheets finance отключается
Google Calendar assistant отключается
Firecrawl researcher через Brave + WebFetch (без полного текста)

10. Механика запуска агентов

11. Тестирование и приёмка

Для каждого агента в CLAUDE.md будет секция «Проверочные запросы»:

Агент Тестовый запрос Ожидание
finance «Запиши расход 500 ₽ на кофе сегодня» Ряд в Sheets Расходы, категория Транспорт или уточнение
lawyer «Составь NDA между ИП Петров и ООО Ромашка» Уточнение недостающих полей → draft NDA
researcher «Сравни тарифы Timeweb и Beget для VPS 2GB RAM» Структурированный отчёт в Google Docs с ≥3 источниками
assistant «Что у меня завтра?» Список событий primary календаря

12. Out of scope

Не делаем в рамках этой спеки:

13. Открытые вопросы для плана реализации

Вопросы, которые должен решить writing-plans skill на следующем шаге:

  1. Порядок написания агентов и тестов для них.
  2. Точное содержание промтов каждого агента (frontmatter model, tools, allowed_mcps).
  3. Как тестировать без живых MCP (mock vs skip).
  4. Точное содержание CLAUDE.md — структура секций.
  5. Формат artifacts.md стартового (пустой шаблон или заготовленные заголовки).

Конец спецификации.