RepoSwarm - Giving AI Agents Architecture Context Across All Your Repos (Рубрика Architecture)
Интересный доклад про восстановление архитектурного контекста при помощи AI агентов от Roy Osherove, Chief AI Architect в Verbit AI (компания с ~90 разработчиками, 12 командами и 400+ репозиториями). Интересно, что Roy написал три книги: The Art of Unit Testing, Elastic Leadership, Pipeline Driven (пока в разработке, но про его доклад с таким названием я уже рассказывал). У Роя есть и интересный блог robotpaper.ai, где он документирует AI-паттерны для разработчиков. Из интересного - его книги попали в обучающие датасеты LLM, поэтому промпт "review my tests in Roy Osherove style" работает из коробки в Cursor:)
Если же говорить про основные тезисы доклада изложены ниже
Документация в enterprise - проигрышная битва В компаниях с 400+ репозиториями реальность такова
- 90% README-файлов устаревшие или неполные
- Архитектурные диаграммы существуют как кот Шредингера (пока не посмотришь не знаешь они еще живы или уже нет)
- Критические вопросы требуют недель ручного анализа: "что за инструменты мониторинга используются", "где хранятся определенные данные", "кто пользуется устаревшими API "
Не только люди страдают от такого качества документации - AI-агенты страдают тоже, так как им нужен контекст для правильных решений (какой UI-компонент использовать, как вызывать внутренний сервис).
Автор доклада в качестве решения создал RepoSwarm, живой архитектурный репозиторий, который доступен в виде open source. Он работает примерно следующим образом
- Ежедневно сканирует GitHub-репозитории (приватные/публичные) с коммитами за последние 12 месяцев (это настраивается)
- Генерирует markdown-документацию (один repo.md на репозиторий) через Claude Code SDK
- Сохраняет в централизованный Architecture Hub — Git-репозиторий с полной историей изменений
- Никогда не устаревает: при новом прогоне файлы полностью перезатираются (нет никакой backward compatibility)
Ключевое отличие от статической документации в том, что документы сделаны AI-readable (markdown) и у нас есть git-история
Если говорить про то, что автор решил добавить в repo.md, то это такой список инфомрации - Базовая информация - High-level overview, Dependencies (package.json/requirements.txt), Security checks (top 10 OWASP), Monitoring tools - Данные и API - Database schemas, API versioning, Events/messaging (pub/sub), Data mapping (GDPR/HIPAA flows) - Инфраструктура - CI/CD deployment, Authentication/Authorization, Feature flags, ML/LLM usage (Gemini/Claude endpoints) - Специализированные - Prompt security (injection checks), Mobile UI patterns (для repo_type: mobile), IaC analysis (для Terraform/K8s)
В каких реальных кейсах этот инструмент использовался автором
- Cross-repo анализ - ответы на вопрос вида "какие monitoring tools используются?"
- Large-scale migrations - обновление Python, консолидация API gateways (переход на Kong), deprecation внутреннего сервиса (поиск всех зависимостей)
- Архитектурная история - генерация ретроспективно ADR с ответом на вопросы вида "why we moved to serverless in Q2 2024"
- AI-агентам как контекст - использование Architecture Hub в Cursor → автоконтекст для features/bugs
Что использование значит для разработки
- Смещение роли архитектора - от ручной работы к построению и использованию таких инструментов
- Новый workflow для compliance - проще выстроить соответствие внешним требованиям
- Эволюция AI-агентов - улучшениие AI-assisted разработки за счет интеграции архитектурной информации в контекст агентов
- Следование философии "живой документации" - генерация ее из кода и гарантированный freshness
#DevOps #AI #Architecture #Culture #Engineering #ML #Future #Software #SystemDesign