agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/arch-lens-module-dependency/SKILL.md

arch-lens-module-dependency

Skill1 starsChanged 8 months agoMITView on GitHub

Create Module Dependency architecture diagram showing package coupling, layering, and fan-in/fan-out. Structural lens answering "How are modules coupled?

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 7 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

    line 38
  2. Distinctive:

    Look for: build configs, project structure, architectural boundaries

    line 51
  3. Distinctive:

    Look for: import statements, dependencies, module references

    line 56
  4. Distinctive:

    Look for: conditional imports, late imports, circular references

    line 61
  5. Distinctive:

    Check for forbidden cross-domain imports

    line 69
  6. Distinctive:

    Document violations with file paths

    line 70
  7. Distinctive:

    Create a matrix showing:

    line 74
  8. Very specific:

    Write the diagram to: temp/arch-lens-module-dependency/arch_diag_module_dependency_{YYYY-MM-DD_HHMMSS}.md

    line 128
  9. Distinctive:

    Before creating the diagram, verify:

    line 246

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Module Dependency Architecture Lens

Cognitive Mode: Structural Primary Question: "How are modules coupled?" Focus: Package Dependencies, Layering, Coupling Patterns, Fan-In/Fan-Out

When to Use

  • Need to understand module coupling and dependencies
  • Analyzing architectural layering violations
  • Identifying high fan-in modules (stability concerns)
  • User invokes /arch-lens-module-dependency or /make-arch-diag dependency

Critical Constraints

NEVER:

  • Modify any source code files
  • Include runtime behavior details
  • Show external system integrations in detail

ALWAYS:

  • Focus on IMPORT relationships between modules
  • Identify layering and valid dependency directions
  • Flag circular dependencies and violations
  • Calculate fan-in for key modules
  • BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

Analysis Workflow

Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

Layer Identification

  • Find top-level directories and their purposes
  • Identify the intended layering structure
  • Look for: build configs, project structure, architectural boundaries

Import Analysis by Layer

  • For each top-level module, find its imports
  • Categorize: internal vs external, layer violations
  • Look for: import statements, dependencies, module references

Circular Dependency Detection

  • Find modules that import each other
  • Identify deferred imports (often indicate issues)
  • Look for: conditional imports, late imports, circular references

High Fan-In Modules

  • Count how many modules import each module
  • Identify the most depended-upon modules
  • These require stable interfaces

Cross-Domain Imports

  • Check for forbidden cross-domain imports
  • Document violations with file paths

Step 2: Build Dependency Matrix

Create a matrix showing:

              layer3  layer2  layer1
  layer3        -       X       X
  layer2        -       -       X
  layer1        ?       ?       -

Where:

  • X = valid imports (downward)
  • ? = potential violations to investigate
  • - = no imports

CRITICAL - Analyze Read/Write Direction: For EVERY dependency relationship:

  • Import direction: Which module imports which?
  • Data flow direction: Does data flow with or against the import?
  • Call direction: Who calls whom?

Note: Import direction (A imports B) doesn't always equal data flow direction (B may return data to A). Document both.

Step 3: Calculate Metrics

For key modules:

  • Fan-In: How many modules depend on this one
  • Fan-Out: How many modules does this depend on
  • Instability: Fan-Out / (Fan-In + Fan-Out)

Step 4: Create the Diagram

Use graph with:

Direction: TB for layer hierarchy

Subgraphs for Layers:

  • Layer N: Application (highest)
  • Layer N-1: Services/Business Logic
  • Layer N-2: Infrastructure/Utilities
  • Layer 0: External (lowest)

Node Styling:

  • cli class: Application layer modules
  • phase class: Service/business logic layer modules
  • handler class: Infrastructure/utility modules
  • stateNode class: High fan-in modules (highlight)
  • integration class: External dependencies

Connection Types:

  • Solid arrows: Valid downward dependencies
  • Dashed arrows: Violations or concerns (with notes)
  • Label with import counts where significant

Step 5: Write Output

Write the diagram to: temp/arch-lens-module-dependency/arch_diag_module_dependency_{YYYY-MM-DD_HHMMSS}.md


Output Template

# Module Dependency Diagram: {Project Name}

**Lens:** Module Dependency (Structural)
**Question:** How are modules coupled?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## Layer Structure

| Layer | Modules | May Import From |
|-------|---------|-----------------|
| N - Application | app/ | services/, utils/ |
| N-1 - Services | services/ | utils/ |
| N-2 - Utilities | utils/ | (internal only) |
| 0 - External | stdlib, packages | N/A |

## Dependency Diagram

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 70, 'curve': 'basis'}}}%%
graph TB
    %% CLASS DEFINITIONS %%
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef integration fill:#c62828,stroke:#ef9a9a,stroke-width:2px,color:#fff;

    subgraph LayerN ["LAYER N - APPLICATION"]
        direction LR
        APP1["app/<br/>━━━━━━━━━━<br/>Entry points"]
    end

    subgraph LayerN1 ["LAYER N-1 - SERVICES"]
        direction LR
        SVC1["services/<br/>━━━━━━━━━━<br/>Business logic"]
    end

    subgraph LayerN2 ["LAYER N-2 - UTILITIES"]
        direction LR
        UTIL1["utils/core/<br/>━━━━━━━━━━<br/>Core utilities"]
        UTIL2["utils/helpers/<br/>━━━━━━━━━━<br/>Helper functions"]
    end

    subgraph Layer0 ["LAYER 0 - EXTERNAL"]
        direction LR
        EXT1["External Libs<br/>━━━━━━━━━━<br/>Third-party"]
    end

    %% VALID DEPENDENCIES (Downward) %%
    APP1 -->|"imports"| SVC1
    APP1 -->|"imports"| UTIL1
    SVC1 -->|"imports"| UTIL1
    SVC1 -->|"imports"| UTIL2
    UTIL1 --> EXT1
    UTIL2 --> EXT1

    %% VIOLATIONS (if any) - dashed %%
    UTIL1 -.->|"VIOLATION"| SVC1

    %% HIGH FAN-IN MODULES %%
    HI_FAN["High Fan-In Module<br/>━━━━━━━━━━<br/>{N} dependents"]

    %% CLASS ASSIGNMENTS %%
    class APP1 cli;
    class SVC1 phase;
    class UTIL1,UTIL2 handler;
    class HI_FAN stateNode;
    class EXT1 integration;

Color Legend:

ColorCategoryDescription
Dark BlueAppsApplication layer entry points
PurpleServicesService/business logic layer
OrangeUtilitiesShared utilities and infrastructure
TealHigh Fan-InCore modules with many dependents
RedExternalExternal dependencies
Dashed LinesViolationArchitectural violations

Dependency Matrix (DSM)

              app   services  utils
  app          -       X        X
  services     -       -        X
  utils        -       ?*       -

  Legend: X = valid imports, ?* = violation (investigate)

Key Metrics

MetricValueAssessment
Circular Dependencies{count}{risk level}
High Fan-In Modules{count}{list them}
Layer Violations{count}{severity}

Violations Identified

SourceTargetTypeSeverity
{module}{module}{violation type}{HIGH/MEDIUM/LOW}

---

## Pre-Diagram Checklist

Before creating the diagram, verify:

- [ ] LOADED `/mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table

---

## Related Skills

- `/make-arch-diag` - Parent skill for lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/arch-lens-c4-container` - For container-level view

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.