From: Aleksey Filippov Date: Wed, 14 Jan 2026 09:05:43 +0000 (+0300) Subject: Добавление agentics.md X-Git-Url: https://gitweb.erp-flowers.ru/?a=commitdiff_plain;h=refs%2Fremotes%2Forigin%2Ffeature_filippov_20260114_add_agentics;p=erp24_rep%2Fyii-erp24%2F.git Добавление agentics.md --- diff --git a/.gitignore b/.gitignore index 2c259cd6..74ddd0c7 100644 --- a/.gitignore +++ b/.gitignore @@ -42,3 +42,6 @@ coordination/orchestration/* claude-flow # Removed Windows wrapper files per user request hive-mind-prompt-*.txt + +# Auto Claude data directory +.auto-claude/ diff --git a/erp24/agents/README.md b/erp24/agents/README.md index c2df6697..d1cba913 100644 --- a/erp24/agents/README.md +++ b/erp24/agents/README.md @@ -6,10 +6,20 @@ Расширенное описание подхода приведено в [статье на Хабре](https://habr.com/ru/articles/971620/). +## Лучшие практики + +**[agentics.md](./agentics.md)** — полное руководство по лучшим практикам agentic-разработки: +- Философия и принципы мультиагентной системы +- Архитектура и роли агентов +- Золотые правила и антипаттерны +- Чеклисты для каждого этапа +- Практические примеры + ## Структура файлов | Файл | Описание | | ---- | -------- | +| [agentics.md](./agentics.md) | **Лучшие практики agentic-разработки** | | [00_agent_development.md](./00_agent_development.md) | Общее описание подхода для ERP24 | | [01_orchestrator.md](./01_orchestrator.md) | Оркестратор (координатор) | | [02_analyst_prompt.md](./02_analyst_prompt.md) | Аналитик | diff --git a/erp24/agents/agentics.md b/erp24/agents/agentics.md new file mode 100644 index 00000000..182bb826 --- /dev/null +++ b/erp24/agents/agentics.md @@ -0,0 +1,870 @@ +# Лучшие практики Agentic-разработки для ERP24 + +Руководство по эффективному использованию мультиагентной системы разработки в проекте ERP24. + +--- + +## Оглавление + +1. [Философия мультиагентной разработки](#философия-мультиагентной-разработки) +2. [Архитектура агентной системы](#архитектура-агентной-системы) +3. [Золотые правила](#золотые-правила) +4. [Workflow и жизненный цикл](#workflow-и-жизненный-цикл) +5. [Роли агентов и их взаимодействие](#роли-агентов-и-их-взаимодействие) +6. [Паттерны проектирования промптов](#паттерны-проектирования-промптов) +7. [Управление контекстом](#управление-контекстом) +8. [Обработка ошибок и неопределённости](#обработка-ошибок-и-неопределённости) +9. [Метрики и мониторинг](#метрики-и-мониторинг) +10. [Антипаттерны и как их избежать](#антипаттерны-и-как-их-избежать) +11. [Чеклисты для каждого этапа](#чеклисты-для-каждого-этапа) +12. [Практические примеры](#практические-примеры) + +--- + +## Философия мультиагентной разработки + +### Принцип разделения ответственности + +Каждый агент выполняет **одну роль** и делает это хорошо: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ РАЗДЕЛЕНИЕ ЗОНЫ ОТВЕТСТВЕННОСТИ │ +├─────────────────────────────────────────────────────────────┤ +│ Аналитик │ ЧТО делать │ Юзер-кейсы, требования │ +│ Архитектор │ КАК устроено │ Компоненты, интерфейсы │ +│ Планировщик │ КАК делать │ Задачи, последовательность│ +│ Разработчик │ ДЕЛАЕТ │ Код, тесты │ +│ Ревьюер │ ПРОВЕРЯЕТ │ Качество, соответствие │ +│ Тестировщик │ ВАЛИДИРУЕТ │ Корректность работы │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Принцип минимального контекста + +Каждый агент получает **только необходимую** информацию: + +| Агент | Обязательный контекст | Опциональный контекст | +|-------|----------------------|----------------------| +| Аналитик | Постановка задачи, PROJECT_SUMMARY.md | Существующий код | +| Архитектор | ТЗ, PROJECT_SUMMARY.md, 11_erp24_context.md | CODE_STYLE.md | +| Планировщик | ТЗ, Архитектура, код проекта | Примеры похожих задач | +| Разработчик | Описание задачи, CODE_STYLE.md, 11_erp24_context.md | Смежные модули | +| Ревьюер | Код, описание задачи, тесты | CODE_STYLE.md | + +### Принцип "сверху вниз" + +Разработка идёт от общего к частному: + +``` +Этап 1: Заглушки (структура есть, логики нет) + ↓ +Этап 2: Бизнес-логика (заглушки → реальный код) + ↓ +Этап 3: Интеграция (компоненты → система) + ↓ +Этап 4: Тестирование (работает → корректно) +``` + +--- + +## Архитектура агентной системы + +### Иерархия агентов + +``` + ┌───────────────────┐ + │ ПОЛЬЗОВАТЕЛЬ │ + │ (Product Owner) │ + └────────┬──────────┘ + │ + ┌────────▼──────────┐ + │ ОРКЕСТРАТОР │ + │ (Координатор) │ + └────────┬──────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ +┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐ +│ АНАЛИТИК │ │ АРХИТЕКТОР │ │ ПЛАНИРОВЩИК │ +│ (opus) │ │ (opus) │ │ (opus) │ +└───────┬───────┘ └───────┬───────┘ └───────┬───────┘ + │ │ │ +┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐ +│ РЕВЬЮЕР ТЗ │ │ РЕВЬЮЕР АРХИТ │ │ РЕВЬЮЕР ПЛАНА │ +│ (sonnet) │ │ (sonnet) │ │ (sonnet) │ +└───────────────┘ └───────────────┘ └───────────────┘ + │ + ┌────────▼──────────┐ + │ РАЗРАБОТЧИК │ + │ (sonnet) │ + └────────┬──────────┘ + │ + ┌────────────────────┼────────────────────┐ + │ │ │ +┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐ +│ РЕВЬЮЕР КОДА │ │ ТЕСТИРОВЩИК │ │ (опц.) │ +│ (sonnet) │ │ (sonnet) │ │ ДЕПЛОЕР │ +└───────────────┘ └───────────────┘ └───────────────┘ +``` + +### Выбор модели для агента + +| Тип задачи | Рекомендуемая модель | Обоснование | +|------------|---------------------|-------------| +| Креативные (анализ, архитектура) | claude-opus-4-5-20251101 | Глубокое понимание, генерация идей | +| Проверочные (ревью) | claude-sonnet-4-20250514 | Следование правилам, быстрота | +| Исполнительные (код, тесты) | claude-sonnet-4-20250514 | Точность, следование инструкциям | + +--- + +## Золотые правила + +### 1. Никогда не пропускай согласование + +``` +╔══════════════════════════════════════════════════════════════╗ +║ ОБЯЗАТЕЛЬНЫЕ ТОЧКИ СОГЛАСОВАНИЯ С ПОЛЬЗОВАТЕЛЕМ: ║ +║ ║ +║ 1. После утверждения плана (перед кодированием) ║ +║ 2. При возникновении блокирующих вопросов ║ +║ 3. После превышения лимита итераций ревью ║ +║ 4. При противоречии с существующим функционалом ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +### 2. Соблюдай лимиты итераций + +| Этап | Максимум итераций | При превышении | +|------|-------------------|----------------| +| Анализ → Ревью ТЗ | 2 | СТОП → пользователь | +| Архитектура → Ревью | 2 | СТОП → пользователь | +| Планирование → Ревью | 2 | СТОП → пользователь | +| Разработка → Ревью кода | 2 | СТОП → пользователь | + +### 3. Веди статус + +Оркестратор **обязан** поддерживать файл `status.md`: + +```markdown +# Статус разработки: TASK-001 + +## Общий прогресс + +| Этап | Статус | Итераций | Замечания | +|------|--------|----------|-----------| +| Анализ | ✅ ОДОБРЕНО | 1 | - | +| Архитектура | ✅ ОДОБРЕНО | 2 | 3 замечания исправлены | +| Планирование | ⏳ В РАБОТЕ | 1 | - | +| Разработка | ⬜ НЕ НАЧАТО | 0 | - | +| Тестирование | ⬜ НЕ НАЧАТО | 0 | - | +``` + +### 4. Используй существующее + +**Перед созданием нового компонента:** + +```bash +# Проверить существующие сервисы +ls -la erp24/services/ + +# Поиск похожих методов +grep -r "calculateBonus" erp24/services/ + +# Проверить Actions +ls -la erp24/actions/ +``` + +### 5. Не выходи за рамки роли + +| Агент | МОЖЕТ | НЕ МОЖЕТ | +|-------|-------|----------| +| Аналитик | Описывать требования | Писать код | +| Архитектор | Проектировать структуру | Писать код | +| Планировщик | Описывать сигнатуры | Писать реализацию | +| Разработчик | Писать код по описанию | Рефакторить без указания | +| Ревьюер | Указывать проблемы | Переписывать код | + +--- + +## Workflow и жизненный цикл + +### Полный цикл разработки + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ WORKFLOW РАЗРАБОТКИ │ +├─────────────────────────────────────────────────────────────────┤ +│ │ +│ ФАЗА 1: ПРОЕКТИРОВАНИЕ │ +│ ═══════════════════════ │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ Аналитик │ → │ Ревьюер │ → │ Аналитик │ (при замечаниях) │ +│ │ ТЗ │ │ ТЗ │ │ доработка│ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ ↓ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │Архитектор│ → │ Ревьюер │ → │Архитектор│ (при замечаниях) │ +│ │ схема │ │ архитект │ │ доработка│ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ ↓ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │Планиров- │ → │ Ревьюер │ → │Планиров- │ (при замечаниях) │ +│ │ щик │ │ плана │ │ щик │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ │ +│ ════════════════ СОГЛАСОВАНИЕ С ПОЛЬЗОВАТЕЛЕМ ════════════════ │ +│ │ +│ ФАЗА 2: РЕАЛИЗАЦИЯ (для каждой задачи) │ +│ ═══════════════════════════════════════ │ +│ │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │Разработ- │ → │ Ревьюер │ → │Разработ- │ (при замечаниях) │ +│ │ чик │ │ кода │ │ чик │ │ +│ └──────────┘ └──────────┘ └──────────┘ │ +│ ↓ │ +│ ┌──────────┐ │ +│ │Тестиров- │ → Финальный отчёт │ +│ │ щик │ │ +│ └──────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Состояния задачи + +``` +⬜ НЕ НАЧАТО + ↓ +⏳ В РАБОТЕ + ↓ +🔄 НА РЕВЬЮ + ↓ +⚠️ ДОРАБОТКА ─────→ 🔄 ПОВТОРНЫЙ РЕВЬЮ + ↓ ↓ +✅ ОДОБРЕНО или ❌ ЗАБЛОКИРОВАН (→ пользователь) +``` + +--- + +## Роли агентов и их взаимодействие + +### Аналитик + +**Входные данные:** +- Постановка задачи от пользователя +- PROJECT_SUMMARY.md +- 11_erp24_context.md + +**Выходные данные:** +- specification.md (ТЗ) +- Список юзер-кейсов с UC-идентификаторами +- open_questions.md (если есть) + +**Ключевые принципы:** +1. Максимальное внимание к неясным моментам +2. Каждый юзер-кейс имеет: актёра, сценарии, критерии приёмки +3. НЕ пишет код, только требования + +### Ревьюер ТЗ + +**Проверяет:** +- Полноту описания задачи +- Соответствие существующему проекту ERP24 +- Противоречия и пробелы +- Совместимость с Yii2 архитектурой + +**Формат замечаний:** +```markdown +## Замечание 1 +**Уровень:** 🔴 Критичное / 🟡 Важное / 🟢 Рекомендация +**Проблема:** [Описание] +**Рекомендация:** [Как исправить] +``` + +### Архитектор + +**Входные данные:** +- Утверждённое ТЗ +- PROJECT_SUMMARY.md +- 11_erp24_context.md +- CODE_STYLE.md + +**Выходные данные:** +- architecture.md + - Функциональная архитектура + - Системная архитектура + - Модель данных (PostgreSQL) + - Интерфейсы + +**Ключевые принципы:** +1. Использует существующий стек ERP24 +2. Следует паттернам: Action, Service, ActiveRecord +3. НЕ пишет код, только проектирует + +### Планировщик (Техлид) + +**Входные данные:** +- ТЗ и Архитектура +- Код проекта ERP24 +- PROJECT_SUMMARY.md + +**Выходные данные:** +- plan.md +- tasks/task_X_Y.md для каждой задачи + +**Структура задачи:** +```markdown +# Задача X.Y: [Название] + +## Связь с юзер-кейсами +- UC-XX: [Название] + +## Описание изменений + +### Новые файлы +#### migrations/mYYYYMMDD_HHMMSS_*.php +- Структура таблицы +- Индексы, FK + +#### records/*.php +- Правила валидации +- Связи + +### Изменения в существующих файлах +#### services/*.php +- Сигнатура метода +- Параметры с типами +- Логика (словами) + +## Тест-кейсы + +### Unit тесты +1. test* — входные данные, ожидаемый результат + +### Functional тесты +1. test* — endpoint, тело запроса, ожидаемый ответ + +## Критерии приёмки +- [ ] Пункт 1 +- [ ] Пункт 2 +``` + +### Разработчик + +**Входные данные:** +- Описание задачи (task_X_Y.md) +- CODE_STYLE.md +- 11_erp24_context.md + +**Выходные данные:** +- Код (новые файлы, изменения) +- Тесты (unit, functional) +- test_report_task_X_Y.md + +**Ключевые принципы:** +1. Точно следует описанию задачи +2. НЕ добавляет "улучшения" по своей инициативе +3. НЕ рефакторит код без указания +4. Запускает ВСЕ тесты + +### Ревьюер кода + +**Проверяет:** +1. Соответствие постановке задачи +2. Качество реализации (паттерны ERP24) +3. Непротиворечивость с существующим функционалом +4. Тестирование +5. Соответствие CODE_STYLE.md + +**Уровни критичности:** +- 🔴 Критичные — блокируют приёмку +- 🟡 Важные — требуют исправления +- 🟢 Рекомендации — опционально + +### Тестировщик + +**Входные данные:** +- Код после ревью +- Описание задачи +- Существующие тесты + +**Выходные данные:** +- Результаты Codeception тестов +- Отчёт о покрытии +- Рекомендации + +--- + +## Паттерны проектирования промптов + +### 1. Структурированный контекст + +```markdown +## КОНТЕКСТ ПРОЕКТА + +- **Проект:** ERP24 — ERP-система для сети цветочных магазинов +- **Стек:** PHP 8.1, Yii2 2.0.45, PostgreSQL, RabbitMQ +- **Документация:** PROJECT_SUMMARY.md, CODE_STYLE.md + +## ВХОДНЫЕ ДАННЫЕ + +[Что агент получает] + +## ТВОИ ЗАДАЧИ + +[Что агент должен сделать] + +## ФОРМАТ РЕЗУЛЬТАТА + +[Как структурировать ответ] + +## ЧЕГО НЕ ДЕЛАТЬ + +[Ограничения] +``` + +### 2. Явные ограничения + +```markdown +## ЧЕГО НЕ ДЕЛАТЬ + +❌ НЕ пиши код — только сигнатуры и описания +❌ НЕ добавляй endpoint в API1 — только API2/API3 +❌ НЕ создавай дубликаты сервисов — используй существующие +❌ НЕ используй MySQL — только PostgreSQL +``` + +### 3. Примеры правильного и неправильного + +```php +// ✅ Правильно: транзакция в сервисе +public function createTransaction(int $clientId, float $amount): BonusTransaction +{ + $transaction = Yii::$app->db->beginTransaction(); + try { + // логика + $transaction->commit(); + return $result; + } catch (\Exception $e) { + $transaction->rollBack(); + throw $e; + } +} + +// ❌ Неправильно: нет транзакции +public function createTransaction(int $clientId, float $amount): ?BonusTransaction +{ + $bonus = new BonusTransaction(); + $bonus->save(); + return $bonus; +} +``` + +### 4. Шаблоны результата + +```markdown +# Результат работы [роль] + +## Созданные файлы +- [путь/файл1.md] — [описание] +- [путь/файл2.md] — [описание] + +## Открытые вопросы +[Если есть — ссылка на open_questions.md] +[Если нет — "Открытых вопросов нет"] + +## Статус +✅ Готово к следующему этапу +``` + +--- + +## Управление контекстом + +### Структура артефактов + +``` +docs/artifacts/{task-id}/ +├── specification.md # ТЗ от аналитика +├── architecture.md # Архитектура +├── plan.md # План задач +├── tasks/ # Описания задач +│ ├── task_1_1.md +│ ├── task_1_2.md +│ └── ... +├── status.md # Статус (ведёт оркестратор) +├── open_questions.md # Блокирующие вопросы +└── reviews/ # Результаты ревью + ├── tz_review.md + ├── arch_review.md + └── ... +``` + +### Передача контекста между агентами + +``` +Аналитик + ↓ specification.md +Ревьюер ТЗ + ↓ tz_review.md (замечания) или specification.md (одобрено) +Архитектор + ↓ architecture.md + specification.md +Ревьюер архитектуры + ↓ architecture.md (одобрено) +Планировщик + ↓ plan.md + tasks/*.md +... +``` + +### Что НЕ передавать + +- Промежуточные черновики +- Отклонённые варианты +- Историю переписки между агентами +- Полный код проекта (только затрагиваемые файлы) + +--- + +## Обработка ошибок и неопределённости + +### Типы неопределённости + +| Тип | Пример | Действие | +|-----|--------|----------| +| Бизнес-требования | "Какой % бонуса?" | open_questions.md → пользователь | +| Технический выбор | "API2 или API3?" | open_questions.md → пользователь | +| Противоречие в ТЗ | "В ТЗ 10%, в коде 5%" | open_questions.md → пользователь | +| Недостаток данных | "Не указан формат даты" | Использовать стандарт проекта | + +### Формат блокирующего вопроса + +```markdown +# Открытые вопросы + +## БВ-001: [Краткое описание] + +**Контекст:** [Где возникла проблема] +**Проблема:** [Суть неясности] +**Варианты:** +- A) [Вариант 1] — [последствия] +- B) [Вариант 2] — [последствия] +**Рекомендация:** [Предпочтительный вариант] +**Блокирует:** [Какие задачи] +``` + +### Когда задавать vs не задавать вопросы + +**Задавать:** +- Противоречия между ТЗ и кодом +- Неясности в бизнес-логике +- Выбор между несовместимыми подходами + +**НЕ задавать:** +- Мелкие технические детали (см. документацию) +- Стиль кода (см. CODE_STYLE.md) +- То, что есть в PROJECT_SUMMARY.md + +--- + +## Метрики и мониторинг + +### Ключевые метрики процесса + +| Метрика | Норма | Тревога | +|---------|-------|---------| +| Итераций на этап | 1-2 | >2 | +| Время на этап | < 1 день | > 2 дней | +| Блокирующих вопросов | 0-1 | > 3 | +| Критичных замечаний | 0-2 | > 5 | + +### Метрики качества кода + +| Метрика | Минимум | Целевое | +|---------|---------|---------| +| Покрытие тестами | 80% | 90% | +| Unit тестов на метод | 2 | 3-4 | +| Functional тестов на endpoint | 1 | 2-3 | +| Регрессия | 0 упавших | 0 упавших | + +### Шаблон status.md + +```markdown +# Статус: {task-id} + +## Метрики + +| Показатель | Значение | +|------------|----------| +| Дата начала | 2024-01-15 | +| Итераций всего | 5 | +| Блокировок | 1 | +| Критичных замечаний | 2 | + +## Этапы + +| Этап | Статус | Итераций | +|------|--------|----------| +| Анализ | ✅ | 1 | +| Архитектура | ✅ | 2 | +| Планирование | ⏳ | 1 | +| Разработка | ⬜ | 0 | +| Тестирование | ⬜ | 0 | + +## История + +- 2024-01-15 10:00: Начало работы +- 2024-01-15 12:30: ТЗ одобрено +- 2024-01-15 15:00: Архитектура на доработке +- 2024-01-16 09:00: Архитектура одобрена +``` + +--- + +## Антипаттерны и как их избежать + +### 1. "Супер-агент" + +**Проблема:** Один агент делает всё — анализ, архитектуру, код. + +**Решение:** Строгое разделение ролей. Один агент = одна функция. + +### 2. "Бесконечный цикл" + +**Проблема:** Ревьюер постоянно находит новые замечания. + +**Решение:** Лимит итераций (2). При превышении — эскалация. + +### 3. "Тихий провал" + +**Проблема:** Агент не сообщает о проблемах. + +**Решение:** Обязательный раздел "Открытые вопросы" в каждом результате. + +### 4. "Scope creep" + +**Проблема:** Агент добавляет "улучшения" не из задачи. + +**Решение:** Явный запрет: "Реализуй ТОЛЬКО то, что указано". + +### 5. "Потерянный контекст" + +**Проблема:** Агент забывает предыдущие решения. + +**Решение:** Структурированные артефакты, передача всех решений. + +### 6. "Дублирование" + +**Проблема:** Создаётся новый сервис при наличии существующего. + +**Решение:** Обязательная проверка существующего кода перед созданием нового. + +### 7. "Отсутствие тестов" + +**Проблема:** Код без тестов принимается. + +**Решение:** Тесты — обязательный критерий приёмки. + +--- + +## Чеклисты для каждого этапа + +### Чеклист Аналитика + +- [ ] Прочитал PROJECT_SUMMARY.md +- [ ] Прочитал 11_erp24_context.md +- [ ] Все юзер-кейсы имеют UC-идентификаторы +- [ ] У каждого UC есть: актёр, сценарии, критерии приёмки +- [ ] Неясности вынесены в open_questions.md +- [ ] НЕ написал код + +### Чеклист Архитектора + +- [ ] Использовал существующие паттерны ERP24 +- [ ] Модель данных для PostgreSQL (не MySQL) +- [ ] Интерфейсы описаны +- [ ] Не создал дубликаты существующих сервисов +- [ ] НЕ написал код + +### Чеклист Планировщика + +- [ ] Все UC покрыты задачами +- [ ] Задачи упорядочены "сверху вниз" +- [ ] Каждая задача имеет тест-кейсы +- [ ] Указаны точные пути к файлам +- [ ] Сигнатуры методов с типами +- [ ] НЕ написал реализацию + +### Чеклист Разработчика + +- [ ] Прочитал CODE_STYLE.md +- [ ] Реализовал ТОЛЬКО то, что в задаче +- [ ] НЕ рефакторил другой код +- [ ] Миграции используют safeUp/safeDown +- [ ] Type hints везде +- [ ] DocBlocks есть +- [ ] Тесты написаны и проходят +- [ ] Регрессионные тесты проходят + +### Чеклист Ревьюера кода + +- [ ] Все требования реализованы +- [ ] Паттерны ERP24 соблюдены +- [ ] Новый код не в API1 +- [ ] Обратная совместимость сохранена +- [ ] Тесты проходят +- [ ] Замечания классифицированы по критичности + +### Чеклист Оркестратора + +- [ ] status.md обновлён +- [ ] Лимиты итераций не превышены +- [ ] Блокирующие вопросы эскалированы +- [ ] Контекст передан следующему агенту +- [ ] Пользователь согласовал план + +--- + +## Практические примеры + +### Пример 1: Добавление нового API endpoint + +**Постановка:** Добавить endpoint для получения истории бонусов клиента. + +**Workflow:** + +1. **Аналитик** → создаёт UC: + - UC-01: Клиент получает историю своих бонусов + +2. **Архитектор** → проектирует: + - GET /api2/bonus/history/{clientId} + - Использует существующий BonusService + - Возвращает пагинированный список + +3. **Планировщик** → разбивает на задачи: + - 1.1: Метод BonusService::getHistory() + - 1.2: Action GetBonusHistoryAction + - 1.3: Интеграция в BonusController + - 2.1: Unit тест + - 2.2: Functional тест API + +4. **[СТОП]** → Согласование с пользователем + +5. **Разработчик** → реализует каждую задачу + +6. **Ревьюер** → проверяет код + +7. **Тестировщик** → запускает полный регресс + +### Пример 2: Блокирующий вопрос + +**Ситуация:** При анализе выяснилось, что требуемый % бонуса отличается от текущего в коде. + +**Действия:** + +1. Аналитик создаёт `open_questions.md`: + +```markdown +## БВ-001: Процент бонуса + +**Контекст:** В ТЗ указано начисление 15%, в коде 10% +**Варианты:** +- A) Оставить 10% — не ломает текущую логику +- B) Изменить на 15% — требует пересчёта для всех клиентов +**Рекомендация:** Обсудить с бизнесом +**Блокирует:** UC-01, UC-02 +``` + +2. Оркестратор останавливает процесс + +3. Вопрос эскалируется пользователю + +4. После ответа — продолжение с учётом решения + +### Пример 3: Превышение лимита итераций + +**Ситуация:** Архитектура получила критичные замечания на 2-м ревью. + +**Действия:** + +1. Оркестратор фиксирует в status.md: + +```markdown +| Архитектура | ❌ ЗАБЛОКИРОВАН | 2 | Критичные замечания | +``` + +2. Создаёт сообщение пользователю: + +```markdown +⚠️ ПРОЦЕСС ОСТАНОВЛЕН + +**Этап:** Архитектура +**Итерация:** 2 из 2 (лимит достигнут) + +**Нерешённые замечания:** +1. Противоречие в выборе API (API2 vs API3) +2. Неясность в модели данных + +Требуется ваше решение для продолжения. +``` + +3. Ожидает ответа пользователя + +--- + +## Команды для работы с агентной системой + +### Запуск в Claude Code + +``` +Используя подход по оркестрации мультиагентной разработки (agents/01_orchestrator.md), +выполни доработку {ссылка на файл с постановкой задачи}. + +Описание проекта: PROJECT_SUMMARY.md +Контекст ERP24: agents/11_erp24_context.md +Промпты агентов: agents/02*.md..10*.md +``` + +### Запуск в Cursor + +``` +Используя подход по оркестрации мультиагентной разработки (agents/01_orchestrator.md), +выполни доработку {ссылка на файл с постановкой задачи}. + +Описание проекта: PROJECT_SUMMARY.md +Контекст ERP24: agents/11_erp24_context.md +Промпты агентов: agents/02*.md..10*.md + +Агентов нужно вызывать shell-командами: +cursor-agent -f --model {модель} -p {промпт} + +Модель: +- Аналитик, архитектор, планировщик: claude-opus-4-5-20251101 +- Ревьюеры и разработчик: claude-sonnet-4-20250514 +``` + +--- + +## Заключение + +Мультиагентная разработка — это **процесс**, а не просто набор промптов. Успех зависит от: + +1. **Чёткого разделения ролей** — каждый агент знает свои границы +2. **Структурированного workflow** — предсказуемая последовательность +3. **Обязательных точек контроля** — согласование с пользователем +4. **Управления контекстом** — правильная передача информации +5. **Мониторинга** — отслеживание метрик и статусов + +При соблюдении этих принципов мультиагентная система становится **предсказуемой**, **управляемой** и **эффективной**. + +--- + +## Ссылки + +- [00_agent_development.md](./00_agent_development.md) — Общее описание подхода +- [01_orchestrator.md](./01_orchestrator.md) — Промпт оркестратора +- [11_erp24_context.md](./11_erp24_context.md) — Контекст проекта +- [PROJECT_SUMMARY.md](../PROJECT_SUMMARY.md) — Описание проекта +- [CODE_STYLE.md](../CODE_STYLE.md) — Стандарты кодирования +- [Статья на Хабре](https://habr.com/ru/articles/971620/) — Расширенное описание подхода