# Architecture Review

> Analyze Python module architecture using pyscn - class coupling (CBO), cohesion (LCOM), dependency cycles, and module communities. Use when user asks about architecture, module structure, coupling, circular dependencies, or which files to review or change together.

- Skill: `ludo-technologies/architecture-review-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ludo-technologies/architecture-review-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ludo-technologies/architecture-review-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ludo-technologies (https://skillmd.com/u/ludo-technologies)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ludo-technologies/architecture-review-2

---


# Python Architecture Review with pyscn

Run the pyscn CLI to understand module structure and coupling. No install needed: `uvx pyscn@latest <command>`.

## Commands

| User Request | Command |
|-------------|---------|
| "Check class coupling" | `uvx pyscn@latest analyze --select cbo <path>` |
| "Find circular dependencies" | `uvx pyscn@latest analyze --select deps <path>` |
| "Check class cohesion" | `uvx pyscn@latest analyze --select lcom <path>` |
| "Which files should I review together?" | `uvx pyscn@latest analyze --select communities --json <path>` |
| "Map the module architecture" | `uvx pyscn@latest analyze --select communities --json <path>` |

Useful flags: `--min-cbo <n>` (minimum CBO to report), `--json` (detailed report file). **Report files are NOT written to stdout**; they go to `.pyscn/reports/` and the path is printed on completion.

## Module Communities (context map for agents)

Module community detection is **opt-in**: run with `--select communities --json` and read the report file.

The JSON report includes `community_analysis.community_context_map`, a compact, deterministic map telling you which modules to inspect together:
- `bundles[]`: clusters of modules that change together. Each has `modules`, `packages`, `risk_level`, the cluster's `bridge_modules`, an optional `suggested_review_scope` (path prefix to focus a review on), and a one-line `summary`. Large bundles cap the module list with a `... +N more` marker (`module_count` always holds the true total).
- `bridge_modules[]`: modules that couple two or more communities (`module`, the communities it `connects`, and a `reason`). Widen the review scope to include these when touching a bundle they connect.

Use the map to scope reviews and refactors: load all modules in a bundle together, and pull in connected bridge modules before changing cluster boundaries.

## Interpreting Coupling Results

- High CBO classes depend on many others; changes ripple widely. Suggest interface extraction or dependency inversion.
- High LCOM4 classes bundle unrelated responsibilities; suggest splitting along the disconnected method groups.
- Dependency cycles are the highest-priority architectural issue; name the modules in each cycle and the weakest edge to break.

Always tie findings back to concrete modules and suggest a specific structural change.

## MCP Alternative

If the `pyscn-mcp` MCP server is connected, you can use its tools instead of the CLI: `check_coupling` for CBO metrics, or `analyze_code` with `analyses: ["deps"]`, `["lcom"]`, or `["communities"]` (communities require `output_mode: "full"`; the full response includes the same `community_context_map`). Results are returned inline with no report files.