RepoSwarm - Giving AI Agents Architecture Context Across All Your Repos (Category Architecture)

Interesting. report Rebuilding Architectural Context with AI Agents from Roy Osherove, Chief AI Architect at Verbit AI (company90 developers, 12 teams 400+ repositories). Roy has written three books: The Art of Unit Testing, Elastic Leadership and Pipeline Driven. (I'm still working on it, but I'm already talking about it. told). Roy also has an interesting blog, robotpaper.ai, where he documents AI patterns for developers. The interesting thing is that his books are in LLM training datasets, so the prompt "review my tests in Roy Osherove style" works out of the box in Cursor:)

If we talk about the main theses of the report are set out below

Enterprise documentation is a losing battle In companies with 400+ repositories the reality is

• 90% README files obsolete
• Architectural diagrams exist as Schrödinger's cat (You don't know if they're still alive or not.)
• Critical issues require weeks of manual analysis: "what kind of monitoring tools are used", "where certain data is stored", "who is using outdated APIs".

It’s not just people who suffer from this quality of documentation – AI agents suffer too, as they need context to make the right decisions. (What UI component to use, how to call internal service).

The author of the report created a decision RepoSwarmA living architectural repository that is available as open source. It works roughly as follows.

1. It scans every day. GitHub repositories (private/public) commissioned 12 months (it's customizable)
2. Generates markdown documentation (one repo.md on the repository) via Claude Code SDK
3. Stored in a centralized Architecture Hub Git repository with a complete history of changes
4. It never gets old: with a new run, files are completely wiped over (There is no such thing as backward compatibility.)

The key difference from static documentation in that documents are made AI-readable (markdown) And we have a git story.

If we talk about what the author decided to add to repo.md, then this is a list of information. - Basic information - High-level overview, Dependencies (package.json/requirements.txt), Security checks (top 10 OWASP), Monitoring tools - Data and APIs - Database schemas, API versioning, Events/messaging (pub/sub), Data mapping (GDPR/HIPAA flows) - Infrastructure. - CI/CD deployment, Authentication/Authorization, Feature flags, ML/LLM usage (Gemini/Claude endpoints) - Specialized - Prompt security (injection checks), Mobile UI patterns (for repo\ type: mobile), IaC analysis (for Terraform/K8s)

In what real cases was this tool used by the author?

1. Cross-repo analysis – answers to the question “What monitoring tools are used?”
2. Large-scale migrations - Python update, API gateway consolidation (kong)Deprecation of internal service (dependency-seeking)
3. Architectural history - ADR generation with the answer to questions like "why we moved to serverless in Q2" 2024"
4. AI Agents as a Context - Using Architecture Hub in Cursor → Autocontext for features/bugs

What Use Means for Development

1. Shifting the role of architect from handmade to building and using such tools
2. New workflow for compliance – easier to align with external requirements n
3. The evolution of AI agents – improving AI-assisted development by integrating architectural information into agent context
4. Follow the philosophy of "living documentation" - generating it from code and guaranteed freshness

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