Skip to content
BranchesTags

Repository files navigation

Read this in other languages: English.

CoderTeam: Мультиагентная разработка с Quality Gates

Python 3.10+ CrewAI 1.15.2 Tests License: MIT

CoderTeam: фокус на продукте

Между «гениальной идеей» и успешным IT-бизнесом лежит пропасть из рутины, багов и потраченного времени. Проверка каждой новой гипотезы стоит бизнесу дни разработок и сжигает бюджет, не гарантируя, что экономика продукта сойдется.

CoderTeam — это не просто очередной «умный промпт» для генерации кода. Это автономный отдел исследований и разработок, занимающийся созданием новых продуктов, который стирает барьер между идеей и готовым MVP.

Под капотом системы трудятся 4 AI-агента (Тимлид, Бэкендер, Фронтендер и Тестировщик), выстроенные в строгий конвейер с гейтами качества. Они сами пишут, тестируют и чинят код. Но их главная ценность — не безошибочность. Их главная >ценность — свобода для экспериментов.

Что CoderTeam дает создателю продукта:

  • Мгновенный краш-тест гипотез. Проверяйте идеи прямо во время мозгового штурма. Разворачивайте проекты, чтобы протестировать их на реальных пользователях, убедиться в наличии юнит-экономики или наоборот, быстро и дешево отбросить нежизнеспособный концепт.
  • Запуск MVP со скоростью мысли. Больше не нужно ждать днями, чтобы «просто посмотреть, как это будет работать». Вы получаете точно структурированный код для старта за минимальное время.
  • Чистый фокус на главном. Вам больше не нужно держать в голове правила синтаксиса, спорить об архитектуре и тратить энергию на микроменеджмент разработки.

Вам нужно лишь задавать верный вектор. Всю инженерную рутину CoderTeam берет на себя.

CoderTeam не просто пишет код — он помогает вашим идеям быстрее встретиться с реальностью.

⚙️ Движок оркестрации: Осознанный выбор CrewAI

CrewAI выбран в качестве фундамента не случайно. Его базовые абстракции (Agents, Tasks, Tools) задают отличный индустриальный стандарт для маршрутизации задач и управления контекстом.

«Из коробки» ни один агентный инструмент не даёт гарантий надежности кода. Поэтому стандартный флоу CrewAI (Process.sequential) здесь обёрнут в жёсткий каркас: поверх него надстроены детерминированные guardrails, изолированная песочница для pytest и направленная петля фиксов. Этот проект демонстрирует, как взять популярный open-source инструмент и довести его работу до строгих production-стандартов.

🧠 Архитектура конвейера

Ключевое отличие системы от «просто сгенерировать» — код реально выполняется. Кастомный инструмент запускает pytest на сгенерированном модуле, и если тесты красные, traceback уходит агенту - бэкендеру на починку.

graph TD
    Req([📄 Входные требования]) --> Lead[🧑‍💻 design_task<br/>Тимлид: пишет дизайн-док]
    Lead --> Back[⚙️ code_task<br/>Бэкендер: пишет Python-модуль]
    Back --> QA[🧪 test_task<br/>Тестировщик: пишет юнит-тесты]
    QA --> Loop

    subgraph "Петля фиксов (sandbox)"
        Loop{run_tests<br/>в песочнице}
        Loop -- Ошибка --> Fix[🛠 fix<br/>Бэкендер чинит по traceback]
        Fix -. Повторная проверка .-> Loop
    end

    Loop -- Успех (тесты зелёные) --> Front[🎨 frontend_task<br/>Фронтендер: Gradio UI]
    
    style Req fill:#ffb3ba,stroke:#333,stroke-width:2px,color:#000
    style Loop fill:#ffdfba,stroke:#d2691e,stroke-width:2px,color:#000
Loading

👥 Команда и разделение ролей

Разделение ролей — не декорация. Роли разведены на уровне конфигурации задач и доступа к инструментам, а не просто пожеланиями в промпте.

Агент Роль Зона ответственности и ограничения
🧑‍💻 engineering_lead Тимлид Проектирует архитектуру (классы, сигнатуры, инварианты). Не пишет реализацию.
⚙️ backend_engineer Бэкендер Реализует код по дизайну. Единственный, кто имеет право править код по трейсбекам. Не имеет инструмента для запуска тестов.
🧪 test_engineer Тестировщик Пишет и запускает юнит-тесты через песочницу. Строгий запрет на изменение целевого кода (маскировка багов невозможна).
🎨 frontend_engineer Фронтендер Создает UI (Gradio) исключительно под финальную, прошедшую гейты версию бэкенда.

⚙️ Что здесь интересного технически

  • 1. Guardrails: детерминированные фильтры вместо уговоров
    Вместо заклинаний вроде OUTPUT ONLY RAW CODE в промптах, используется цепочка чистых Python-функций на каждой генерирующей задаче. Каждый guardrail мутирует output.raw. При провале — автоматический ретрай с текстом ошибки в контексте, чтобы модель знала, что чинить.

  • 2. PytestRunnerTool: песочница для кода
    Кастомный наследник crewai.tools.BaseTool. Сохраняет модуль и тесты во временную директорию, запускает pytest с таймаутом и возвращает структурированный отчёт. Поле COLLECTION_ERROR помогает агенту понять, нужно ли чинить логику (упал assert) или синтаксис (не импортируется).

  • 3. Петля фиксов: одна осознанная попытка (ADR-011)
    Проблема отсутствия циклов в Process.sequential решена статической проводкой run_tests → fix → verify с одной попыткой починки. Холостой проход fix_task при зелёном отчёте (SUCCESS: True) доказан побайтовым diff артефактов: код возвращается дословно. Риск деградации не реализовался на практике, что подтверждено измерениями, а не теорией.

  • 4. Эволюция Structured Outputs
    Изначальный план с output_pydantic=ModulePlan ронял пайплайн из-за багов фреймворка. Строгая Pydantic-валидация была перенесена внутрь guardrail'а. Фича выведена из продакшена с полным сохранением кода, схем и 12 тестов на них. Включение обратно — одна строка.

  • 5. Модель: приёмка пройдена на GPT-5.6 Terra и Claude Sonnet 5
    Пайплайн проектировался под Claude Sonnet, а финальную приёмку прошел на GPT-5.6 Terra и Claude Sonnet 5. Переключение выполняется одной строкой в .env. Guardrails, петля фиксов и разделение ролей отработали идентично, доказав, что качество результата гарантирует архитектура системы, а не конкретная LLM.

Стоимость одного полного прогона (7 задач: дизайн → код → тесты → петля фиксов → UI):

Модель Прогон Токены (in/out) Стоимость Приёмка
GPT-5.6 Terra 3 мин 31 сек 78 827 / 41 867 $0.74 ✅ 5/5
Claude Sonnet 5 3 мин 14 сек 12 309 / 39 695 $0.63 ✅ 5/5

Тарифы на момент замера (июль 2026): Terra $2.50/$15.00, Sonnet 5 $2.00/$10.00 за 1M токенов. Стоимость логируется в logs/costs.log и выводится в консоль после каждого прогона.

Tip

Инженерный инсайт: обход ограничений CrewAI + OpenAI Смена модели вскрыла неочевидный конфликт: OpenAI запрещает function tools для reasoning-моделей в /v1/chat/completions, если не задан параметр reasoning_effort: "none". Чтение исходников CrewAI показало: штатный путь игнорирует параметр. Обход найден через подмешивание сырых параметров до проверок фреймворка:

LLM(model=MODEL, additional_params={"reasoning_effort": "none"})

🛡 Инженерный процесс: Quality Gates

Проект разрабатывался не «одним промптом», а через строгий workflow:

  • 📄 WORKFLOW.md — гейты G0–G4 с exit-критериями.
  • 🕵️ gate-reviewer — субагент с чистым контекстом, проверяющий факты по коду (file:line), а не по отчетам.
  • ✍️ test-writer — субагент, пишущий тесты от контракта, не читая реализацию бэкенда.
  • 📚 DECISIONS.md — 18 ADR-записей (сохранены все архитектурные решения, трейдоффы, миграции и отклоненные идеи).
  • 🧪 Два яруса тестов: 99 бесплатных юнит-тестов (guardrails, схемы) + 1 платный e2e-прогон с лимитом попыток.

Important

Харнес вместо надежды Контракт приёмки tests/test_e2e.py заблокирован от правок AI на уровне харнеса (permissions.deny в .claude/settings.json). Агент структурно не способен ослабить критерии успеха, чтобы пройти проверку.

💡 Уроки разработки: Post-mortem и реальные дефекты

Самая ценная часть — честный разбор того, что пошло не так. Приёмочные прогоны падали, и диагнозы изначально были лишь гипотезами. После внедрения полного логирования выяснилось главное:

Warning

DEF-005a — Guardrails не защищали артефакты. CrewAI записывал output_file из сырого первого ответа модели, а не из очищенного через guardrails контента. Цепочка честно отрабатывала и одобряла результат, но на диск падал первоначальный битый вывод. Фикс: Запись артефактов перенесена в task callbacks.

Warning

DEF-006 — Кеш маскировал отсутствие проверок. Идеальное продолжение предыдущего бага. После того как инструмент тестирования заставили читать файлы с диска (чтобы не гонять код строками), его аргументы стали идентичными между вызовами. Как следствие: CrewAI закешировал результат, и задача verify_task просто вернула ответ из кеша (from cache), даже не запустив pytest. Финальная верификация петли оказалась фикцией. Если бы агент испортил код, никто бы этого не заметил.

Главный урок: Каждый фикс порождал следующий скрытый дефект, и ни один из них не был пойман тестами — их выявила только тотальная наблюдаемость логов. Структурная верификация не заменяет наблюдаемость исполнения.

Весь путь задокументирован в реестре дефектов (DEF-001…DEF-006) с доказательствами и ремедиационными гейтами.

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

На вход подается абзац требований (например, «система управления торговым счётом: депозиты, покупка акций, портфель, P&L»). На выходе — рабочий Python-модуль, юнит-тесты к нему и готовый Gradio-интерфейс.

Убедитесь, что у вас установлен Python и настроено окружение:

git clone <repo>
cd coder_team

# Настройте провайдера и модель в .env
echo "MODEL=openai/gpt-5.6-terra" > .env
echo "OPENAI_API_KEY=sk-..." >> .env

# 1. Запуск бесплатных тестов (99 проверок логики фреймворка, без вызовов LLM):
pytest

# 2. Полный прогон пайплайна (платный, зависит от модели):
crewai run

# 3. Приёмочный контракт (включает защиту от случайного запуска):
E2E_ACCEPTANCE=1 pytest tests/test_e2e.py -m acceptance -s

Note

Все сгенерированные артефакты (accounts.py, test_accounts.py, app.py, дизайн-док) автоматически сохраняются в директорию output/. Полные логи исполнения лежат в logs/.

🤝 Как это делалось: человек + AI

Проект разрабатывался в паре с Claude Code. Распределение ролей — это часть демонстрируемого подхода:

  • 👤 Человек: Проектировал архитектуру процесса, принимал финальные решения, писал контракт приёмки и проверял факты.
  • 🤖 AI: Предлагал архитектурные концепции, анализировал исходники фреймворка, исполнял код и активно оспаривал ошибки человека (например, выявил нерабочий main.py, отсутствие декоратора @task и вскрыл механику кеширования CrewAI).
  • ⚙️ Система: Не давала никому срезать углы (deny на изменение контракта, строгие бюджеты и лимиты).

Тезис проекта: Ценность LLM-агентов определяется не моделью, а процессом вокруг неё — обратной связью, наблюдаемостью и гарантиями на каждом шаге.

🛠 Стек

  • Фреймворк: CrewAI 1.15.2
  • LLM (Модель-агностик): Конфигурируется через .env. Пайплайн успешно протестирован на Claude Sonnet 5 и GPT-5.6 Terra.
  • Валидация: Pydantic v2
  • Тестирование: pytest
  • Среда: Claude Code (с настроенным харнесом прав)

📊 Статус и цифры

Метрика Значение
Юнит-тестов (без LLM-вызовов) 99
Задач в пайплайне 7 (+1 экспериментальная, выведена с документацией)
ADR-решений 18 (включая миграцию, настройки LLM и фиксы кеша)
Задокументированных дефектов 7 (DEF-001…DEF-006)
Стоимость полного прогона $0.74 (GPT-5.6 Terra, 120 694 токена)
Стоимость полного прогона $0.63 (Claude Sonnet 5, 52 004 токена)
Суммарно за все приёмочные прогоны ~$4.8 (6 прогонов, включая 3 упавших)

About

Автономный отдел исследований и разработок, занимающийся созданием новых продуктов, который стирает барьер между идеей и готовым MVP

Topics

crewaicrewai-agentsmvpmvp-architecturemvp-developmentmvp-patternpython

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages