Codebase Architecture Map

Large or unfamiliar repositories often paralyze agents with too much context and not enough structure. This skill provides a structural map of a codebase to prevent blind edits and excessive file reads. It gives you a clear understanding of tech stacks, module relationships, and the potential blast radius of your changes.

What it does

• Architectural mapping Identifies core languages, frameworks, entry points, and top-level project structure.
• Dependency analysis Maps internal import graphs to reveal circular dependencies and central "hub" modules.
• Risk assessment Locates hotspots by identifying the largest, most complex, and most frequently changed files.
• Impact analysis Calculates the transitive blast radius before you edit a file to see what else will break.
• Codebase orientation Generates summaries of specific folders, classes, functions, and external requirements.

How it works

1. Orient Run architecture_overview to identify the tech stack and entry points.
2. Map Execute dependency_graph to see how modules connect and find circular imports.
3. Analyze Use hotspots and impact_analysis to identify high-risk files and the ripple effects of proposed changes.
4. Explain Trigger explain on specific sub-directories to understand local implementation details before reading source code.

Frameworks & tools

This skill requires the mcp-architect server. It supports full AST parsing for Python and import parsing for JavaScript and TypeScript. It provides file statistics for over 25 other languages.

Why this beats prompting it yourself

Standard agents try to read every file to understand structure, which wastes tokens and misses hidden dependencies. This skill uses specialized local tools to build a graph of the codebase, identifying circular imports and high-risk hubs that a simple file search would overlook.

Use cases

• Onboard onto a massive legacy codebase without reading every file manually.
• Identify circular dependencies that are causing runtime or build issues.
• Calculate the blast radius of a refactor before touching a shared utility module.
• Find tech debt by listing files with the highest complexity and change frequency.

Known limitations

Full AST parsing is limited to Python. JavaScript and TypeScript support import parsing. Other languages return basic file and line statistics only. Complexity data requires a local git history.