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. Он работает примерно следующим образом
1. Ежедневно сканирует GitHub-репозитории (приватные/публичные) с коммитами за последние 12 месяцев (это настраивается)
2. Генерирует markdown-документацию (один repo.md на репозиторий) через Claude Code SDK
3. Сохраняет в централизованный Architecture Hub — Git-репозиторий с полной историей изменений
4. Никогда не устаревает: при новом прогоне файлы полностью перезатираются (нет никакой 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)

В каких реальных кейсах этот инструмент использовался автором

1. Cross-repo анализ - ответы на вопрос вида "какие monitoring tools используются?"
2. Large-scale migrations - обновление Python, консолидация API gateways (переход на Kong), deprecation внутреннего сервиса (поиск всех зависимостей)
3. Архитектурная история - генерация ретроспективно ADR с ответом на вопросы вида "why we moved to serverless in Q2 2024"
4. AI-агентам как контекст - использование Architecture Hub в Cursor → автоконтекст для features/bugs

Что использование значит для разработки
1. Смещение роли архитектора - от ручной работы к построению и использованию таких инструментов
2. Новый workflow для compliance - проще выстроить соответствие внешним требованиям
3. Эволюция AI-агентов - улучшениие AI-assisted разработки за счет интеграции архитектурной информации в контекст агентов
4. Следование философии "живой документации" - генерация ее из кода и гарантированный freshness

#DevOps #AI #Architecture #Culture #Engineering #ML #Future #Software #SystemDesign