Building an Architecture Analyst Agent

Why You Need an Architecture Analyst Agent

Before we dive into implementation, let's talk about the problem we're solving.

Most teams operate with implicit architecture. The team knows (roughly) how things fit together, but that knowledge lives in people's heads—and people leave. Your documentation is either nonexistent or outdated. PRs pass code review but silently increase coupling. Microservices aren't actually micro anymore.

The issue? Manual architecture analysis doesn't scale. Reviewing module boundaries by hand takes hours. Tracking dependencies across a large codebase is error-prone. Detecting when code drifts from intended architecture happens after the damage is done.

An architecture analyst agent automates this process. It:

• Reads your codebase without executing it (no security risks)
• Maps dependencies by analyzing imports, requires, and module structure
• Calculates coupling metrics (afferent/efferent coupling, instability)
• Detects cohesion issues (modules doing too many things)
• Generates ADRs (Architecture Decision Records) from code patterns
• Reports architectural drift (comparing actual code vs. documented architecture)
• Produces diagrams (Mermaid dependency graphs you can version control)

The beauty? Once you've built the agent, you run it on demand. New codebase? Point it there. Quarterly architecture review? Run the agent. Pre-refactoring analysis? Instant insights.

This is the power of Claude Code agents—they handle the mechanical work so you can focus on interpretation and decision-making. An agent can analyze a medium-sized codebase in minutes, extracting insights that would take a human days to uncover manually.

Architecture Agent Design Principles

Before writing code, let's establish some design principles that keep this agent focused and effective.

Principle 1: Read-Only Analysis

This agent never modifies code. It uses only read operations (Read, Grep, Glob, Bash) to gather data. This means:

• Zero risk of breaking production
• Can be safely automated in CI/CD pipelines
• Works across any codebase (yours or third-party)
• No authentication needed beyond file system access

Principle 2: Structural Focus

We analyze structure, not semantics. We care about:

• Where files live (directory hierarchy)
• What imports what (dependency graph)
• Module boundaries and coupling
• Patterns in the code (not the code's meaning)

We don't try to understand business logic. That's beyond scope and fragile.

Principle 3: Actionable Output

The agent produces artifacts you can actually use:

• Dependency graphs (Mermaid format, version-controllable)
• ADR templates (ready for human refinement)
• Coupling/cohesion metrics (quantifiable)
• Drift reports (before vs. after comparisons)

Principle 4: Language Agnostic

The core analysis patterns work across JavaScript, Python, Go, Java, etc. We adapt the import detection to the target language, but the overall pipeline remains consistent.

Keep these principles in mind as you build. They'll guide every design decision.

Building the Agent: Core Structure

Let's construct an architecture analyst agent step by step. We'll use YAML to define the agent configuration, showing how to encode analysis instructions, data pipelines, and output generation. This makes it clear, testable, and language-independent.

Phase 1: Project Discovery

The agent starts by understanding the codebase structure. It scans the file system to identify module boundaries and technology stack.

---
name: architecture-analyst
version: "1.0.0"
description: "Read-only codebase analyzer for architectural insights"
access:
  - read_files
  - glob_patterns
  - grep_search
  - bash_queries
 
# Phase 1: Discovery
discovery:
  description: "Map project structure and identify modules"
 
  steps:
    - name: identify_root_structure
      tool: glob
      pattern: "**/*"
      depth: 2
      description: "List top-level directories to understand module organization"
 
    - name: detect_language
      tool: glob
      patterns:
        - "**/*.js"
        - "**/*.ts"
        - "**/*.py"
        - "**/*.go"
        - "**/*.java"
      description: "Detect supported languages in the codebase"
 
    - name: find_package_metadata
      tool: glob
      patterns:
        - "**/package.json"
        - "**/pyproject.toml"
        - "**/go.mod"
        - "**/pom.xml"
      description: "Locate package/module metadata files"
 
    - name: scan_config_files
      tool: glob
      patterns:
        - "**/tsconfig.json"
        - "**/jest.config.js"
        - "**/.eslintrc.*"
        - "**/setup.cfg"
      description: "Find tooling configurations that reveal architecture decisions"
 
  outputs:
    structure_map:
      type: json
      content:
        root_modules: []
        detected_languages: []
        metadata_files: []
        config_files: []

Why this matters: Before analyzing dependencies, we need to understand what we're looking at. A monorepo looks different from a modular app. A Python package library differs from a Node.js backend. This discovery phase gives the agent context about the project shape, technology choices, and structural patterns before diving into detailed dependency analysis. It's the equivalent of a human architect walking the building before analyzing the blueprint.

Phase 2: Dependency Mapping

Now we analyze imports and requires to build a dependency graph. This is the heart of architectural analysis.

  # Phase 2: Dependency Mapping
  dependency_mapping:
    description: "Analyze imports/requires to build dependency graph"
 
    language_patterns:
      javascript:
        patterns:
          - 'import .* from ["\']([^"\']+)["\']'
          - 'require\(["\']([^"\']+)["\']\)'
          - 'import\(["\']([^"\']+)["\']\)'
        extensions: [".js", ".ts", ".jsx", ".tsx"]
 
      python:
        patterns:
          - 'from ([\w\.]+) import'
          - 'import ([\w\.]+)'
        extensions: [".py"]
 
      go:
        patterns:
          - 'import\s+"([^"]+)"'
        extensions: [".go"]
 
    steps:
      - name: extract_imports_per_file
        tool: grep
        for_each: "discovered_source_files"
        parameters:
          pattern: "language_patterns[language].patterns"
          extensions: "language_patterns[language].extensions"
        output:
          file_path: string
          imports: array
          language: string
 
      - name: classify_imports
        description: "Categorize each import (internal, external, stdlib)"
        logic:
          - internal: "import within project boundaries"
          - external: "third-party or npm packages"
          - stdlib: "standard library imports"
 
      - name: build_import_graph
        description: "Create directed graph of module dependencies"
        output:
          nodes:
            - id: "module_id"
              type: "module|package|file"
              path: "file_path"
              language: "language"
 
          edges:
            - from: "source_module"
              to: "target_module"
              type: "import|require|reference"
              strength: "direct|transitive"

Key insight: Different languages have different import syntax. The agent needs language-specific regex patterns, but the overall approach remains consistent: extract import statements, classify them, build a graph. Notice the for_each pattern—this parallelizes analysis across many files efficiently, making the agent scalable even for large codebases.

Phase 3: Coupling and Cohesion Analysis

With a dependency graph built, we calculate metrics that reveal architectural problems. This is where raw data becomes actionable insights.

# Phase 3: Metrics Calculation
metrics_analysis:
  description: "Analyze coupling and cohesion"
 
  coupling_metrics:
    afferent_coupling:
      description: "How many modules depend on this module?"
      formula: "count(modules that import X)"
      interpretation:
        high: "This is a core/foundation module (good)"
        low: "This module is independent (good)"
 
    efferent_coupling:
      description: "How many modules does this module depend on?"
      formula: "count(imports from X)"
      interpretation:
        high: "This module has many dependencies (potential issue)"
        low: "This module is focused (good)"
 
    instability:
      description: "Probability that change will cascade"
      formula: "E / (A + E)  # where E=efferent, A=afferent"
      range: [0, 1]
      interpretation:
        close_to_0: "Stable (depended on, few dependencies)"
        close_to_1: "Unstable (many dependencies, few dependents)"
 
  cohesion_analysis:
    description: "Do modules in a package serve similar purposes?"
 
    metrics:
      - name: module_count_per_package
        description: "How many modules in each package?"
        concern: "Too many (>20) suggests split needed"
 
      - name: imports_across_package_boundary
        description: "Do files within a package mostly depend on each other?"
        formula: "internal_imports / total_imports"
        concern: "Low ratio suggests split or reorganization"
 
      - name: circular_dependencies
        description: "Do any modules form import cycles?"
        severity: "high"
        concern: "Circular deps prevent independent testing/versioning"

Why these metrics? They're objective measures that reveal architectural problems:

• High instability = module will break if many things change
• Low cohesion = package should be split
• Circular dependencies = modules can't be tested or versioned independently

These numbers guide refactoring decisions with data, not opinion.

Phase 4: Architectural Drift Detection

If you have documented architecture (an ADR, a design doc), we can compare actual code against intended design. This is powerful because it catches problems early.

# Phase 4: Drift Detection
drift_detection:
  description: "Compare actual code structure vs documented architecture"
 
  documentation_sources:
    - path: "docs/ARCHITECTURE.md"
      format: "markdown"
    - path: "docs/ADR/"
      format: "adr_files"
    - path: "architecture-decision-log.md"
      format: "markdown"
 
  drift_checks:
    - name: boundary_violations
      description: "Does code cross module boundaries that docs forbid?"
      check: "For each documented module boundary, verify no imports cross it"
 
    - name: layer_violations
      description: "Does code respect layering (UI → Business → Data)?"
      documented_layers: ["presentation", "business", "persistence"]
      check: "Verify layer hierarchy is preserved in imports"
 
    - name: dependency_plan_vs_actual
      description: "Are only documented dependencies present?"
      check: "Compare graph edges to ADR-specified dependencies"
 
    - name: module_scope_creep
      description: "Has module grown beyond its documented responsibility?"
      check: "Has file count or import count exceeded thresholds?"
 
  outputs:
    drift_report:
      violations_found: number
      violation_type: string
      module_involved: string
      documented_intent: string
      actual_behavior: string
      severity: "low|medium|high"
      recommendation: string

The power here: Drift detection turns documentation from a static artifact into a living contract. When code violates documented architecture, the agent flags it automatically. This catches problems before they compound.

Phase 5: Output Generation

Finally, the agent produces artifacts you can use immediately—graphs, reports, and recommendations.

# Phase 5: Output Generation
outputs:
  dependency_graph:
    format: "mermaid"
    style: "graph LR"
    node_size: "scaled by afferent coupling"
    node_color: "based on instability"
    description: "Visual dependency map, ready for version control"
 
  coupling_cohesion_report:
    format: "markdown_table"
    fields:
      - module_name
      - afferent_coupling
      - efferent_coupling
      - instability_index
      - cohesion_score
    sorting: "by instability descending"
 
  circular_dependency_report:
    format: "markdown_list"
    content:
      - cycle_path: "module A → module B → module C → module A"
        severity: "high"
        breaking_point: "suggestion for where to cut the cycle"
 
  adr_template:
    format: "markdown"
    title: "ADR: Refactor [Module Name]"
    sections:
      - status: "Proposed"
      - context: "Coupling metrics show module X has instability 0.85"
      - decision: "Suggest splitting module X into X-a and X-b"
      - consequences: "Positive: reduced coupling. Negative: more directories."

This is where the analysis becomes actionable. A graph you can paste in a doc. Metrics that quantify problems. ADRs ready for your team to refine.

Practical Example: Running the Agent

Let's see this in action. Imagine we run the agent on a moderately complex Node.js project with an e-commerce backend. The agent discovers 8 JavaScript files organized in 4 packages (api, services, models, utils). It builds a dependency graph:

routes.js → [middleware.js, user-service.js, order-service.js]
middleware.js → [logger.js, config.js]
user-service.js → [user.js, logger.js]
product-service.js → [product.js, logger.js]
order-service.js → [order.js, user-service.js, product-service.js, logger.js]
models/* → [logger.js]
logger.js → [config.js]
config.js → (no internal imports)

It calculates metrics:

Insights: Routes is completely unstable (100%), which is actually okay for a router. But order-service has high instability (80%) and high dependencies (4)—it's doing too much.

It generates a Mermaid diagram showing the dependency flow, colored by stability. And it proposes an ADR: split order-service into order-fulfillment-service and order-validation-service, reducing coupling and enabling parallel development.

All of this happens in 2-3 minutes without manual analysis.

Real-World Implementation Challenges

When you actually deploy an architecture analyst agent, you'll hit snags that the theory doesn't cover. Let me walk you through the most common ones.

Challenge 1: Aliased Imports and Path Mappings

Many projects use TypeScript path aliases or webpack module aliases. Your agent sees import { service } from '@services/order' but needs to map that to the actual file location. Without this mapping, the dependency graph is wrong.

Solution: Parse tsconfig.json or webpack.config.js before dependency extraction. Extract the alias mappings and use them to resolve imports to actual file paths.

Challenge 2: Dynamic Imports and Indirect Dependencies

Code like const service = require(serviceNames[i]) or dynamic ESM imports can't be statically analyzed. Your agent will miss these dependencies, leading to incomplete graphs and false metrics.

Solution: Flag dynamic imports as "unanalyzable" rather than ignoring them. In your reports, note: "3 dynamic imports detected; metrics may underestimate actual coupling." This transparency is better than false confidence.

Challenge 3: Monorepo Workspace Confusion

A monorepo with multiple package.json files at different levels creates ambiguity. Is src/services a module? A package? The root? Different tools answer differently.

Solution: Establish clear workspace definitions in your agent configuration. Typically: one workspace per package.json, with module boundaries within each workspace. Document this explicitly in your reports.

Challenge 4: Test File Noise

Including test files doubles your graph size and introduces artificial dependencies (tests import production code). Your coupling metrics become skewed.

Solution: Make this configurable. Default: exclude test files (**/*.test.js, **/*.spec.js). Offer an --include-tests flag for analysis when you specifically want to understand test architecture.

Challenge 5: Third-Party Library Explosion

A large project imports hundreds of third-party packages. Including all of them in your dependency graph makes it unreadable.

Solution: Separate internal from external dependencies. Generate two reports: one for internal-only (for architectural analysis), one for all (for dependency audit). In the internal graph, group third-party imports as "external dependencies" without showing individual packages.

Integration into Development Workflows

The real value of an architecture analyst agent emerges when you integrate it into your team's development process. Don't run it once and file the report away. Run it regularly—weekly, before major PRs, before refactorings, after significant feature additions. Track metrics over time and watch for trends.

One pattern that works particularly well is running the agent before sprint planning. The generated ADRs and coupling reports become conversation starters. "Our order service has 80% instability," the team lead points out. "What's driving that? Should we address it this sprint, or push it to next quarter?" These metrics-driven conversations are far more productive than vague complaints like "this module feels big."

Another integration point is pre-refactoring analysis. Before tackling a major refactor, run the agent to establish baseline metrics. Calculate what you expect the metrics to be after the refactor. Then use those targets to guide implementation decisions.

You can also automate the analysis. Set up a scheduled job that runs the agent nightly, compares results against baseline metrics, and alerts the team if something changed unexpectedly. "Instability of api/auth module jumped 40% in the last 24 hours." The team investigates, discovers an accidental coupling, and fixes it before it compounds.

Handling Large Codebases and Monorepos

The patterns we've covered work for small projects, but what about enterprise-scale systems? A single monorepo with 200,000 files and a million lines of code? The analysis becomes computationally expensive.

Optimize by implementing analysis caching. Store results at the module or package level. If src/services/payment/ hasn't changed since the last analysis, reuse those results. Only re-analyze the modules that changed. This transforms analysis time from 10 minutes to 30 seconds if only 10% of the codebase changed.

Also implement hierarchical analysis. Instead of analyzing all 200,000 files as a flat graph, group them into packages or services first. Build a high-level graph of package dependencies, then within each package, build a detailed graph of module dependencies. This gives you insights at multiple granularities.

For truly massive codebases, implement windowed analysis. Instead of analyzing the entire codebase at once, analyze it in sections. "Analyze modules touching payment." "Analyze modules that changed in the last week." "Analyze dependencies on the utils module." Windowed analysis lets you answer specific architectural questions without analyzing everything.

Advanced Metrics Beyond Coupling

We covered afferent coupling, efferent coupling, and instability. But you can calculate more sophisticated metrics that reveal deeper architectural truths. Consider implementing:

Change impact analysis: When a module changes, how many other modules are affected? This is the transitive closure of the dependency graph. Modules with high change impact are architectural bottlenecks.

Information flow complexity: Do dependencies form clean layers (UI → Business → Data), or are there violations? Measure layering adherence explicitly.

Testability metrics: Can a module be tested in isolation, or does it have so many dependencies that testing requires mocking everything? Calculate a "testability score" based on dependency complexity.

Velocity impact: Couple your architectural metrics with development velocity. If your most unstable modules are also the ones where development velocity is slowest, you've found a high-value refactoring target.

Why This Matters: Architecture as a First-Class Asset

Most teams treat architecture as secondary to features. You build features, and architecture emerges (or degrades). But architecture is your infrastructure for feature velocity. Good architecture means new features are fast to implement. Bad architecture means every feature takes twice as long because you're fighting the structure.

An architecture analyst agent makes architecture visible. Invisible problems can't be fixed. Once metrics show "the auth module has 92% instability," the team can't ignore it. Metrics drive action.

This is particularly valuable for organizations with multiple teams or projects. Without architecture visibility, each team makes local optimization decisions that create global problems. When you can measure architecture, you can govern it. You can establish standards: "all modules should have under 70% instability." You can enforce it: if a PR increases instability above 70%, it doesn't merge.

The net effect: better architecture, faster feature delivery, happier engineers. That's worth the investment in a good architecture analyst.

Common Pitfalls When Building Architecture Analysts

Teams building architecture analyzers hit predictable problems. Here's how to avoid them.

Pitfall 1: Measuring without context You measure that Module A has 80% instability, but you don't understand why. Is it a cache module (dependencies are natural)? Is it a business logic module (problematic)? Raw metrics without context mislead. Solution: always pair metrics with context. Annotate the dependency graph. Note: "api/auth is a facade—high efferent coupling is expected."

Pitfall 2: Over-interpreting metrics You measure two modules have identical instability scores, so you assume they're equivalent. But one is genuinely well-designed, and the other is a mess that happens to score the same. Metrics are one signal, not the truth. Solution: use metrics to identify problem areas, then use human judgment to understand them. The agent suggests refactoring, but humans decide if it's necessary.

Pitfall 3: Ignoring temporal analysis You run the analyzer once, get results, and move on. You don't track how metrics change over time. You miss trends: "instability is increasing by 5% per month." Solution: run the analyzer regularly (weekly or monthly). Track metrics over time. Alert on significant changes. This turns architecture analysis from a one-time activity into continuous monitoring.

Pitfall 4: Not handling polyglot codebases You have JavaScript services and Python microservices. The analyzer works on JavaScript but struggles with Python. Different languages have different import patterns. Solution: implement language-specific analysis modules. Each language has its own import detection regex. The overall architecture is language-agnostic.

Pitfall 5: Fixating on perfect purity You measure that some module violates the documented layering. It does. But the violation is necessary for performance or pragmatism. You refactor it to be "pure" and make everything slower. Solution: allow documented exceptions. If a module must violate layering for good reason, document that exception. Metrics should surface real architectural problems, not force dogmatic purity.

Troubleshooting Architecture Analysis Issues

When the analyzer produces confusing results, here's how to debug.

Problem: High coupling doesn't correlate with slow development The analyzer says module A has high coupling and should be refactored. But development velocity on module A is fine. Maybe the coupling is necessary, or maybe the metric is misleading. Solution: check if the high coupling is to stable modules. If A depends heavily on B, but B is stable and rarely changes, high coupling is okay. Refine your coupling metric to distinguish "dangerous coupling" from "stable coupling."

Problem: Circular dependencies keep reappearing You fix a circular dependency, and weeks later, a different circular dependency appears. This suggests your team doesn't understand why circular dependencies are bad, or the architecture doesn't prevent them. Solution: document the risks (can't test in isolation, can't version independently). Add a pre-commit hook that fails if new circular dependencies are introduced. Make it costly to create them.

Problem: Different analysis runs give wildly different results You run the analyzer twice and get different dependency graphs. This is usually a sign of non-deterministic analysis (random import detection order, different machines with different tools). Solution: ensure the analysis is deterministic. Use sorted output. Run on identical hardware if possible. Version your analysis scripts so you know what produced what results.

Alternatives and Extensions

The basic architecture analyst covers structure and coupling. But you can extend it.

Extension 1: Semantic analysis Not just "module A imports module B" but "module A imports module B for reason X." This requires parsing comments or type hints. More expensive, but richer understanding. Example: "api/user imports models/user (entity definition) vs. api/user imports utils/logging (cross-cutting concern)"—these are different kinds of dependencies.

Extension 2: Change history analysis Combine architecture analysis with git history. Which modules change together? Which modules are coupled by common bugs (they fix the same issues repeatedly)? This is empirical coupling based on change patterns, not just imports.

Extension 3: Performance impact analysis Couple architecture analysis with performance metrics. Which modules impact latency when they change? Which can tolerate slow implementations? This guides optimization priorities.

Extension 4: Team structure analysis Analyze not just code dependencies but team dependencies. Which teams own which modules? Do module dependencies match team dependencies (Conway's Law)? Misalignment causes bottlenecks.

Real-World Scenario: Quarterly Architecture Review

Imagine you're a staff engineer doing a quarterly architecture review. Historically, this is manual: you spend a day reading code, tracing dependencies, making notes. Then you present findings.

With an architecture analyst:

Week 1: Run the analyzer. Get dependency graphs, coupling metrics, ADR templates, and drift reports.

Week 2: Review the results. Spot the three modules with highest instability. Check if there are circular dependencies. Read the AI-generated ADRs.

Week 3: Dig into the top issues. Talk to engineers who built those modules. Understand the tradeoffs. Some high instability is necessary and documented. Some is a problem worth fixing.

Week 4: Present findings to leadership. Show metrics. Explain the top 3 issues and recommended fixes (and effort estimates). Because you have data, the discussion is productive.

Total time: 20 hours of focused review instead of 40+ hours of manual analysis.

And the output is better. You have graphs you can reference. You have metrics. Engineers trust data more than intuition.

What Happened in the Quarterly Review

The analyzer ran on a Tuesday morning. By 10am, you had results. The output was stark: three modules had instability over 80% (routes.js, services/orders.js, api/payments.js). Six circular dependencies were detected. Several modules had more than 20 files and high internal coupling, suggesting they should be split.

You knew routes.js was supposed to be unstable (it's a facade). But services/orders.js was news. You called the engineer who built it: "Hey, the analyzer says orders.js depends on seven other modules. Is that right?" They said: "Yeah, it's complicated. Orders touch inventory, payments, shipping, notifications, analytics, audit logging, and performance monitoring. It has to coordinate a lot." You asked: "Is that a permanent requirement, or did we just layered it together over time?" They said: "Both. Some of it is inherent. Some of it is because we don't have a proper event bus. We're doing synchronous calls where we should have async events."

That's valuable insight. The metric (high instability) surfaced the problem. The conversation uncovered the root cause. Now you can estimate a fix: implement an event bus so services don't need to call each other directly. That's a week-long project. It would reduce orders.js instability from 85% to 30%. Boom. You've got a concrete refactoring that's worth doing.

You dug into the circular dependencies. One was payment.js → order.js → payment.js (orders need to validate payment status, payments need to reference orders). This is actually necessary. You documented it as an exception: "This cycle is acceptable because of domain requirements. Break the cycle only if payment processing architecture changes." The other cycles were mistakes: api.js → middleware.js → api.js (middleware was importing from api to access utilities). That's easy to fix: extract utilities into a shared utils module. Now there's no cycle.

The ADR template the analyzer generated was rough—it said "Refactor orders service to reduce instability"—but it gave you a starting point. You refined it with context: "ADR-42: Implement Event Bus for Service Decoupling. Rationale: orders.js currently has 85% instability due to synchronous dependencies on seven modules. An async event bus would decouple services and reduce instability. Effort: ~40 hours. Payoff: ~30% latency reduction, easier to test, easier to scale."

This became the centerpiece of your quarterly review. You presented metrics showing the problem. You presented a concrete solution. You presented effort estimate. The conversation with leadership was practical: "Here's a real bottleneck. Here's how to fix it. Here's the cost." They approved it for next quarter.

The Unexpected Value

Here's what surprised you: The analyzer also flagged that api/auth.js had increasing instability over the past 3 months. You didn't have historical data, but the analyzer detected that afferent coupling doubled and efferent coupling tripled in recent weeks. You asked the team: "What's changing in auth?" They said: "We've been adding MFA, SAML integration, API key management..." Aha. Auth module was becoming a mega-module. The analyzer was telling you: this module is growing and gathering too many responsibilities.

You recommended: split auth into separate services. Auth-core (basic login/logout), Auth-mfa (MFA handling), Auth-federation (SSO/SAML), Auth-keys (API key management). Each would be focused. Dependencies would be cleaner. The team had been planning this vaguely. The analyzer made it concrete. "Auth instability increased 200% in 3 months. Split recommended to prevent further degradation."

Now the quarterly review has multiple concrete recommendations backed by data. That's how you move architecture from vague hand-waving to managed evolution. The analyzer didn't make the decisions (humans did). But it surfaced the problems and quantified them. That's exactly the right division of labor between automation and human judgment.

Handling Very Large Codebases

Enterprises run massive monorepos. The analyzer needs to handle scale.

Optimization 1: Incremental analysis Only re-analyze files that changed. Cache results for stable files. This reduces analysis time from 10 minutes to 30 seconds for small changes.

Optimization 2: Distributed analysis Analyze different packages in parallel. This scales to many CPU cores.

Optimization 3: Hierarchical reporting Instead of one massive dependency graph, generate graphs at multiple levels: high-level (service dependencies), mid-level (package dependencies), low-level (module dependencies). Users can drill down as needed.

Optimization 4: Filtering and focus Instead of analyzing everything, let users focus: "Show me dependencies on the payment module," "Show me modules that changed this week," "Show me unstable modules." Answer specific questions fast instead of analyzing everything slowly.

Team Adoption and Culture

For the architecture analyst to be valuable, your team needs to adopt it.

Step 1: Make it a tool, not a mandate "Here's an agent that can analyze architecture. It's optional. Run it when you want insights." This is safer than making it mandatory. Teams experiment. Early adopters share results.

Step 2: Share early wins When the analyzer reveals something valuable (a refactoring that improves performance, a circular dependency that was causing bugs), share that story. Show the team: "This agent helped us" builds credibility.

Step 3: Integrate into review process Run the analyzer on PRs that touch multiple modules. Include a comment: "This PR increases module X's instability from 45% to 62%. Is that intentional?" Now the metrics inform code review.

Step 4: Make it part of planning Before sprint planning, run the analyzer. Use the results to inform what to work on. "We have three modules with over 80% instability. Should we pick one for refactoring this sprint?" Metrics drive prioritization.

Over time, architecture analysis becomes normal. Teams develop intuition. They start thinking about architecture proactively instead of reactively.

Summary: The Architecture Analyst Agent

You now have the blueprint for a powerful tool: an agent that reads your codebase, maps its dependencies, quantifies coupling and cohesion, detects drift from documented architecture, and generates actionable artifacts.

This agent doesn't replace human architecture thinking. It amplifies it. It handles the mechanical work—scanning files, building graphs, calculating metrics—so your team can focus on interpretation, decision-making, and design.

The beauty of Claude Code agents? You can build this once and apply it everywhere. New microservice? Run the agent. Evaluating an open-source library? Run the agent. Quarterly architecture review? Run the agent.

The patterns we've covered here scale to any codebase, any language, any size. You've got everything you need to build an architecture analyst that works for your team.

Now get out there and make your architecture visible.

-iNet